Referencia del API
Base local: http://localhost:4000 · Producción: URL del servicio Railway.
Autenticación: Authorization: Bearer <jwt> (7 días). Errores:
{ "error": { "code", "message", "issues?" } }.
Público (sin auth)
| Método | Ruta | Descripción |
|---|---|---|
| GET | /health | estado, provider activo y modo demo |
| GET | /public/config | modo demo + límites min/max |
| GET | /public/corridors | países, monedas y métodos disponibles |
| POST | /public/quotes | cotización con desglose (amount, sourceCurrency, destinationCountry, deliveryMethod) |
| POST | /public/leads | alta de lead desde la landing |
| GET | /public/remittances/:token | vista del receptor (smart link) |
| POST | /public/remittances/:token/delivery | el receptor elige método y datos de cobro |
Auth
| Método | Ruta | Descripción |
|---|---|---|
| POST | /auth/register | alta de persona (rol USER) |
| POST | /auth/register-business | alta de empresa + operador (rol BUSINESS, KYB pendiente) |
| POST | /auth/login | devuelve { token, user, company? } |
| GET | /auth/me | perfil + empresa |
KYC
| Método | Ruta | Descripción |
|---|---|---|
| POST | /kyc | enviar documento + selfie + prueba de residencia |
| GET | /kyc/me | estado y última submission |
Beneficiarios
CRUD estándar en /beneficiaries (+/:id). Reglas: al menos un método de
cobro; los datos deben corresponder a corredores del país (p. ej. banco en
Kenia → 422 UNSUPPORTED_CORRIDOR).
Remesas
| Método | Ruta | Descripción |
|---|---|---|
| POST | /remittances | crear (beneficiario guardado o smartRecipient) |
| GET | /remittances | mías (BUSINESS: todas las de la empresa) |
| GET | /remittances/:id | detalle |
| GET | /remittances/:id/events | timeline |
| GET | /remittances/:id/receipt | recibo estructurado |
| POST | /remittances/:id/cancel | solo en PENDING |
Códigos de negocio relevantes: KYC_REQUIRED, KYB_REQUIRED,
MONTHLY_LIMIT_EXCEEDED, COUNTRY_MISMATCH, METHOD_DETAILS_MISSING,
UNSUPPORTED_CORRIDOR.
B2B
| Método | Ruta | Descripción |
|---|---|---|
| GET | /b2b/company | empresa + resumen de volumen |
| POST | /b2b/batches | 501 — stub de mass payouts (Fase 6) |
Webhooks Cashela
POST /webhooks/cashela con header x-cashela-signature
(HMAC-SHA256 del JSON con CASHELA_WEBHOOK_SECRET).
{ "type": "payin.completed", "data": { "payinId": "pi_…" } }Tipos: payin.completed, payin.failed, payout.completed,
payout.failed. El handler es idempotente.
Admin (rol ADMIN)
| Método | Ruta | Descripción |
|---|---|---|
| GET | /admin/stats | KPIs agregados |
| GET | /admin/users · PATCH /admin/users/:id/limit | usuarios y límites |
| GET | /admin/kyc · POST /admin/kyc/:id/review | cola y revisión KYC |
| GET | /admin/companies · POST /admin/companies/:id/kyb | KYB de empresas |
| GET | /admin/remittances?status=&review=&search= | buscador |
| POST | /admin/remittances/:id/approve / …/reject | compliance |
| GET | /admin/alerts?status= · POST /admin/alerts/:id/resolve | alertas AML |
| GET | /admin/leads · PATCH /admin/leads/:id | CRM |
| POST | /admin/wiki-token | token firmado (15 min) + URL de esta wiki |
Demo
Con DEMO_MODE=true: POST /dev/remittances/:id/advance simula el siguiente
webhook de Cashela para la remesa (requiere ser el dueño o admin).