Primeros pasos
Ciclo de una petición
Lo que comparten todas las llamadas a la API: formato, autenticación, errores, repetición y paginación.
La API es HTTP con JSON. Todas las rutas siguen las mismas convenciones; esta sección las reúne para que no haya sorpresas al integrar.
| Aspecto | Convención |
|---|---|
| AspectoFormato | ConvenciónCuerpos de petición y respuesta en JSON (content-type: application/json). Las únicas excepciones son la página de pago (HTML) y el QR (SVG). |
| AspectoAutenticación | ConvenciónCabecera x-api-key en las rutas /v1/.... |
| AspectoMontos | ConvenciónSiempre texto decimal ("103.101981"), nunca números de coma flotante. amount_units trae el mismo monto en la unidad mínima del token. |
| AspectoFechas | ConvenciónISO 8601 en UTC: 2026-10-13T15:04:12.310Z. |
| AspectoIdentificadores | ConvenciónUUID para clientes, depósitos, eventos y claves. Los clientes también se pueden buscar con ext:<external_id>. |
| AspectoDirecciones | ConvenciónLas de clientes y empresas vienen con mayúsculas de verificación (EIP-55); las de un depósito (address, from, token_address) vienen en minúsculas. Compáralas sin distinguir mayúsculas. |
| AspectoRespuestas | ConvenciónEl objeto viene dentro de una clave con su nombre: { "customer": … }, { "deposits": […], "total": 16 }. |
| AspectoTamaño | ConvenciónEl cuerpo de una petición no puede superar 64 KB. |
Autenticación
La cabecera x-api-key y quién usa cada tipo de ruta.
Peticiones repetidas
Qué rutas se pueden repetir y cómo no acreditar dos veces.
Ids de petición
La cabecera x-request-id, para tus logs y para soporte.
Errores
Formato, códigos de estado y cuándo reintentar.
Paginación
limit y offset en listados; after y before en eventos.
GET https://api.pasarela.melenashair.com/v1/customers/ext:TARJETA-000123
x-api-key: sk_test_4f9c…