Convenciones de la API

​

1. Superficies y montaje de rutas

​

2. Autenticación

• WhatsApp: el usuario se identifica por su número de teléfono (normalizado a E.164). No hay token; el canal es el identificador.
• API web (cliente): token Bearer de Supabase (Authorization: Bearer <token>). El ID de usuario sale del JWT.
• API de comercio (/merchant/*): token Bearer + el usuario debe tener un comercio asociado. Algunas acciones (administradores) requieren ser dueño.
• MCP: token OAuth propio (o JWT de Supabase en modo compatibilidad). Ver MCP.
• Endpoints públicos: POST /merchant/leads, GET /qr/:merchantCode, assets públicos y los webhooks no requieren auth (los webhooks validan firma).
• Admin interno: ciertas operaciones administrativas usan API key.

​

3. snake_case vs. camelCase

• Las rutas /merchant/* usan snake_case en request y response. Un middleware transforma automáticamente:
  • Request: snake_case → camelCase (antes de llegar a la lógica).
  • Response: camelCase → snake_case (antes de salir).
• El resto de las rutas usan camelCase directamente.

​

4. Formato de respuesta

​

Comercio (/merchant/*) — formato estándar obligatorio

// Lista paginada
{ "success": true, "data": { "items": [ ... ], "pagination": { "page": 1, "limit": 20, "total": 0, "total_pages": 0 } } }

// Lista simple (sin paginación)
{ "success": true, "data": [ ... ] }

// Objeto único
{ "success": true, "data": { ... } }

// Acción sin datos
{ "success": true }

// Error
{ "success": false, "error": "mensaje" }

• La clave envoltorio es siempre data (nunca el nombre del dominio como spins, coupons, customers).
• Los arrays paginados van en data.items (nunca data.data).
• La paginación usa totalPages (camelCase interno) → el middleware lo convierte a total_pages en la respuesta.

​

Otras rutas

​

5. Errores

​

6. Paginación

• Query params: page (1-indexado) y limit.
• Las respuestas paginadas de comercio usan la estructura data.items + data.pagination (ver sección 4).

​

7. Fechas y zona horaria

• Gastuki opera con calendario de Argentina (ART, UTC−3).
• Los totales mensuales se calculan con límites de mes en ART (tanto en la API HTTP como en MCP devuelven los mismos agregados).
• Los reportes de comercio aceptan rango de fechas con tope de 90 días; si no se especifica, usan los últimos 30 días.
• Los timestamps de respuesta son ISO 8601.
• En MCP, los rangos de período se resuelven en zona local y se devuelve el rango efectivo en period: { from, to } (ver MCP).

​

8. Webhooks

​

Más información

• API interactiva: /api-docs (Swagger UI).
• Esta documentación describe el comportamiento funcional del producto, no su implementación.