Introducción

La API de Lade es el backend de la plataforma SaaS de gestión de flotas para empresas mexicanas de logística/transporte: vehículos, conductores, rutas, viajes, clientes, equipos (multi-tenancy), facturación CFDI (Facturapi) y suscripciones (Stripe).

Arquitectura en una línea

API Gateway (REST, regional) → Lambda (Python 3.11) → DynamoDB (single-table), con autenticación vía Amazon Cognito (JWT) e infraestructura definida en Terraform (repo lade-infra).

Cada endpoint es una función Lambda independiente organizada por dominio (auth, users, teams, clients, drivers, vehicles, routes, trips, billing, invoices, …). Las utilidades compartidas (validación, formato de respuesta, acceso a DynamoDB, modelos Pydantic) viven en un Lambda layer común.

Cómo leer esta documentación

• Empezar aquí — entornos/URLs y cómo autenticarse. Léelo antes de llamar cualquier endpoint.
• Convenciones — headers que toda llamada debe mandar, el formato de éxito/error que toda respuesta sigue, y cómo funciona el aislamiento por equipo.
• Referencia de la API — generada automáticamente desde openapi/openapi.json: por cada endpoint verás método, path, parámetros de ruta y query, body con schema y ejemplo, códigos de respuesta y el schema de lo que regresa.

Cobertura del spec

El openapi.json actual documenta los dominios core (Auth, Users, Teams, Members, Invitations, Clients, Drivers, Vehicles, RoutePoints, Routes, Trips, Health — 37 endpoints). Los dominios más nuevos (billing, invoices, payments, boxes, box-reservations, alerts, dms, reports, events, logs) todavía no están en el spec; su referencia provisional es lade-infra/docs/reference/lambdas-reference.md. Actualizar el spec es parte del plan activo (lade-infra/docs/plan-api-dominios-y-robustez.md).

Repos relacionados

Repo	Qué es
lade-infra	Terraform + lambdas + layer compartido. Fuente de verdad del OpenAPI (docs/reference/openapi.json).
lade-app	Frontend React 19 que consume esta API.
lade_infra_docs	Este sitio (Astro Starlight).