Convenciones del API Bancario

Todas las operaciones del API Bancario comparten el mismo formato de respuesta, las mismas reglas de paginación y el mismo formato de fechas. Esta página describe lo que el spec declara de forma transversal.

Envelope de respuesta#

Cada respuesta, exitosa o no, viaja en el mismo sobre:

{
  "success": true,
  "http_status_code": 200,
  "response_code": "OK",
  "message": "The request was processed successfully.",
  "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {}
}

En las respuestas de error el sobre trae además errors, un objeto de detalle que puede incluir campos arbitrarios como code, message o detail.

Ramificá tu lógica por response_code, no por el texto de message.

Correlación#

Enviá X-Correlation-Id en el request para propagar tu propio identificador; el valor vuelve como correlation_id en el sobre. Guardalo en tus logs: es el dato con el que soporte rastrea una llamada puntual.

Reintentos seguros#

Dos operaciones aceptan la cabecera Idempotency-Key:

POST /api/public/v1/transactions/payments
POST /api/public/v1/accounts/statements

Reenviar la misma llave con el mismo cuerpo devuelve el resultado original en vez de crear un segundo registro, así un timeout de red se puede reintentar sin duplicar. Si reusás una llave con un cuerpo distinto, la respuesta es 409 con response_code: IDEMPOTENCY_CONFLICT.

Generá una llave por intención de negocio (por ejemplo un UUID por orden), no una por reintento. El resto de las operaciones son consultas y se pueden repetir sin efectos adicionales.

Paginación#

El API usa dos esquemas según el recurso.

Cursor, en el listado de pagos. GET /api/public/v1/transactions/payments acepta limit (por defecto 20, máximo 100) y cursor. La respuesta trae pagination.next_cursor: pasalo como cursor en el siguiente request. Cuando viene vacío u omitido, no hay más páginas.

Offset, en cuentas. GET /api/public/v1/accounts y GET /api/public/v1/accounts/balances aceptan limit (1 a 100) y offset (desde 0), y devuelven pagination con limit, offset y total.

Fechas y montos#

Los parámetros y campos de fecha usan RFC 3339, por ejemplo 2026-09-02T15:04:05Z. Los filtros date_from y date_to del listado de pagos siguen ese mismo formato.

Salud y documentación del host#

El propio host expone tres rutas de servicio:

GET /api/public/v1/healthz
GET /openapi.yaml
GET /docs

healthz sirve para chequeo de disponibilidad, openapi.yaml devuelve el spec crudo y /docs la interfaz de documentación del servicio. En este portal el mismo spec está en openapi.json y openapi.yaml.