Convenciones de la API

• Convenciones de la API
  • URL base y versión
  • Formato de las peticiones
  • Paginación
  • Fechas y horas
  • Montos y monedas
  • Identificadores
  • Idempotencia
  • Límites, tiempos y reintentos
  • Lo que nunca devolvemos

URL base y versión

https://sag-qa.efipay.co/api/v1

La versión va en la ruta. Hoy solo existe v1; cuando exista otra, v1 seguirá respondiendo.

Dentro de una versión solo agregamos: campos nuevos en las respuestas, parámetros opcionales nuevos, valores nuevos en las enumeraciones. Nunca quitamos un campo ni cambiamos el significado de uno existente.

{warning} Por eso tu código no debe romperse si aparece un campo que no conocías, ni si una enumeración trae un valor nuevo. Ignora lo que no uses.

Formato de las peticiones

• Cuerpo en JSON, con Content-Type: application/json.
• Header Accept: application/json. Sin él, un error de validación puede llegarte como HTML en lugar de JSON.
• Autenticación con Authorization: Bearer. Ver Autenticación.
• Nombres de campo en snake_case en lo que envías.

La única excepción es crear una sucursal con logo o RUT, que va como multipart/form-data porque lleva archivos.

{info} En las respuestas verás dos estilos: snake_case en la mayoría de los endpoints y camelCase en algunos de suscripciones. Cada página muestra el suyo; no lo adivines.

Paginación

Los listados vienen paginados con el sobre estándar de Laravel:

{
    "data": [ "..." ],
    "links": {
        "first": "https://sag-qa.efipay.co/api/v1/...?page=1",
        "last": "https://sag-qa.efipay.co/api/v1/...?page=8",
        "prev": null,
        "next": "https://sag-qa.efipay.co/api/v1/...?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 8,
        "per_page": 15,
        "to": 15,
        "total": 118
    }
}

{danger} Dos excepciones que muerden:

• Listar planes trae 2 por página. Si no envías per_page parecerá que tienes dos planes.
• Reservas de cupo trae 25.

Para recorrer todo, sigue links.next hasta que sea null. No calcules las URLs a mano.

Fechas y horas

{warning} La zona horaria de la operación es America/Bogotá (UTC−5). Un cobro de las 8 p.m. del 31 de julio en Colombia es 2026-08-01T01:00:00Z en UTC: si conviertes mal, te cambia de mes en la conciliación.

Montos y monedas

Los montos van como número decimal en la unidad principal de la moneda, no en centavos: 120000 son ciento veinte mil pesos, y 1200.50 son mil doscientos pesos con cincuenta centavos.

En una transacción en moneda extranjera verás amount (moneda original), value_cop (el equivalente en pesos) y currency_rate_conversion con la tasa aplicada. Concilia con value_cop: es lo que efectivamente se movió.

{info} Las reservas de cupo solo operan en COP.

Identificadores

Una transacción tiene los dos: id (UUID) y transaction_id (consecutivo). Los endpoints de consulta aceptan cualquiera de los dos; guarda el que le vayas a mostrar a una persona.

{warning} Los ids no se comparten entre ambientes. Un id de prueba da 404 con token de producción, y al revés.

Idempotencia

Las escrituras de suscripciones, pagos y reservas de cupo aceptan el header Idempotency-Key. Si repites la misma llamada con la misma clave y los mismos parámetros, te devolvemos la respuesta original con el header Idempotency-Replayed: true, sin volver a ejecutar el cobro.

{info} Las consultas no la aceptan, aunque vayan por POST: transaction-status, transaction/{id}, all-transaction-status y el sync de una reserva. Ahí la clave no tendría sentido: se pide justamente el estado más reciente. Los pasos de 3DS tampoco, porque su resultado cambia entre llamadas.

curl -X POST \
'/api/v1/subscriptions/subscription' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-type: application/json' \
-H 'Idempotency-Key: 9b1f0e34-6b2a-4a7e-9d0a-uno-por-operacion' \
-d '{ "...": "..." }'

• Usa una clave distinta por operación (un UUID sirve). No reutilices la misma clave para dos cobros diferentes.
• La clave vale 24 horas y su alcance es tu comercio y el usuario del token.
• La misma clave con parámetros distintos responde 409.
• La misma clave mientras la primera petición sigue en curso responde 409.
• Los errores 5xx no se memorizan, para que puedas reintentar un fallo transitorio.

Detalle en Suscripciones.

Límites, tiempos y reintentos

Límite de peticiones

No publicamos hoy un límite de peticiones por minuto. Lo que sí existe es un candado de concurrencia por cobro: no se procesan dos pagos del mismo cobro a la vez.

{warning} Un 429 no significa que hayas excedido una cuota: significa que esa misma operación ya se está procesando. Espera el resultado y consúltalo; no la reenvíes.

Tiempos de respuesta

Pon en tu cliente un timeout mayor a 45 segundos para las operaciones de cobro. Si cortas antes, no cancelas nada: la operación sigue su curso en la red y te quedas sin saber cómo terminó.

Qué es seguro reintentar

{danger} La regla que evita cobros dobles: ante la duda, consulta antes de reenviar. Con estado de transacción o con la misma Idempotency-Key, que te devuelve la respuesta original en vez de cobrar de nuevo.

Lo que nunca devolvemos

• El número completo de una tarjeta. Siempre enmascarado: 491617******1313.
• El CVV. No se guarda.
• Tokens en claro. El token de un cobro en modalidad api y el token de una tarjeta se devuelven una sola vez, al crearse. De ahí en adelante solo guardamos su hash.

{danger} Si necesitas volver a mostrar «con qué tarjeta pagó», usa el BIN y los últimos cuatro dígitos que ya te devolvemos. No hay forma de recuperar el número completo, y eso es deliberado.