Endpoints
Endpoints
Resumen
| Ruta | Método | Propósito | Auth |
|---|
/api/token/ |
POST |
Obtener JWT |
No |
/api/token/refresh/ |
POST |
Renovar JWT |
No |
/corresponsales/api/factura/consulta/ |
POST |
Consultar factura |
JWT + api-key |
/corresponsales/api/factura/pago/ |
POST |
Notificar pago |
JWT + api-key |
/corresponsales/api/factura/pago/reversar/ |
POST |
Reversar pago |
JWT + api-key |
Rate limit: 200 requests/hora por usuario autenticado. 20 requests/hora para requests sin autenticación (token endpoint).
1. Consulta de factura
Consulta el estado de una factura. Devuelve un request_id que debes usar en el siguiente paso si deseas notificar un pago.
| Propiedad | Valor |
|---|
| Método | POST |
| Ruta | /corresponsales/api/factura/consulta/ |
| Autenticación | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/consulta/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"invoice_id": "2025407608"
}
| Campo | Tipo | Requerido | Descripción |
|---|
invoice_id |
string |
Sí |
Identificador de la factura a consultar (número de recibo de pago) |
Response 200 — Consulta exitosa
{
"status": "0",
"message": "Consulta exitosa",
"data": {
"ReciboPago": "2025407608",
"Total": 1003973,
"Vencimiento": "2026-02-09",
"Pagado": false,
"Vencido": false,
"Usable": true
},
"request_id": "f7002954-8ec2-4248-9c8e-6625a2588117"
}
| Campo | Tipo | Descripción |
|---|
status | string | "0" = éxito, "1" = error |
data.ReciboPago | string | Número de recibo de pago |
data.Total | number | Monto total de la factura |
data.Vencimiento | string (ISO) | Fecha de vencimiento |
data.Pagado | boolean | Si ya fue pagada |
data.Vencido | boolean | Si está vencida |
data.Usable | boolean | Debe ser true para proceder al pago |
request_id | string (UUID) | ID de esta consulta. Úsalo como input del endpoint de pago. |
Si data es un objeto vacío {}, la factura no fue encontrada. El request fue técnicamente exitoso pero sin resultados.
2. Notificación de pago
Registra el pago de una factura previamente consultada. Requiere el request_id de una consulta exitosa con Usable: true.
| Propiedad | Valor |
|---|
| Método | POST |
| Ruta | /corresponsales/api/factura/pago/ |
| Autenticación | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/pago/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"request_id": "f7002954-8ec2-4248-9c8e-6625a2588117"
}
| Campo | Tipo | Requerido | Descripción |
|---|
request_id |
string (UUID) |
Sí |
El request_id devuelto por la consulta de factura previa. Debe corresponder al mismo usuario autenticado. |
El sistema valida internamente que: (1) el request_id corresponde a una transacción exitosa del mismo usuario API, (2) la factura tiene Usable: true. Si alguna condición falla, retorna 400.
Response 200 — Pago notificado
{
"status": "0",
"message": "Pago notificado exitosamente",
"data": {
"ReciboPago": "2025407608",
"Pliq_ReciboPago": "...",
...
},
"llave_recibo": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
| Campo | Descripción |
|---|
status | "0" = éxito, "1" = error |
data | Datos de liquidación retornados por el SP configurado. Los campos exactos dependen de la implementación. |
llave_recibo | Clave TLOG del recibo de caja generado. Guárdala para posibles reversas. |
3. Reversa de pago
Cancela un pago previamente notificado. Los parámetros del body los define el stored procedure configurado para este endpoint en el sistema.
| Propiedad | Valor |
|---|
| Método | POST |
| Ruta | /corresponsales/api/factura/pago/reversar/ |
| Autenticación | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/pago/reversar/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
... // parámetros definidos por el SP configurado
}
El body de este endpoint no tiene un esquema fijo en la capa API. Los campos requeridos los determina el stored procedure configurado para tu empresa. Consulta a tu equipo de operaciones.
Response 200 — Reversa exitosa
{
"status": "0",
"message": "Pago revertido exitosamente",
"data": [...]
}
Summary
| Path | Method | Purpose | Auth |
|---|
/api/token/ |
POST |
Get JWT |
No |
/api/token/refresh/ |
POST |
Renew JWT |
No |
/corresponsales/api/factura/consulta/ |
POST |
Query invoice |
JWT + api-key |
/corresponsales/api/factura/pago/ |
POST |
Notify payment |
JWT + api-key |
/corresponsales/api/factura/pago/reversar/ |
POST |
Reverse payment |
JWT + api-key |
Rate limit: 200 requests/hour per authenticated user. 20 requests/hour for unauthenticated requests (token endpoint).
1. Invoice query
Queries an invoice's status. Returns a request_id you must pass to the payment endpoint if you want to notify a payment.
| Property | Value |
|---|
| Method | POST |
| Path | /corresponsales/api/factura/consulta/ |
| Authentication | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/consulta/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"invoice_id": "2025407608"
}
| Field | Type | Required | Description |
|---|
invoice_id |
string |
Yes |
Invoice identifier to query (payment receipt number) |
Response 200 — Successful query
{
"status": "0",
"message": "Consulta exitosa",
"data": {
"ReciboPago": "2025407608",
"Total": 1003973,
"Vencimiento": "2026-02-09",
"Pagado": false,
"Vencido": false,
"Usable": true
},
"request_id": "f7002954-8ec2-4248-9c8e-6625a2588117"
}
| Field | Type | Description |
|---|
status | string | "0" = success, "1" = error |
data.ReciboPago | string | Payment receipt number |
data.Total | number | Total invoice amount |
data.Vencimiento | string (ISO) | Due date |
data.Pagado | boolean | Whether it has been paid |
data.Vencido | boolean | Whether it is overdue |
data.Usable | boolean | Must be true to proceed to payment |
request_id | string (UUID) | ID of this query. Use it as input to the payment endpoint. |
If data is an empty object {}, the invoice was not found. The request was technically successful but with no results.
2. Payment notification
Records payment of a previously queried invoice. Requires the request_id from a successful query with Usable: true.
| Property | Value |
|---|
| Method | POST |
| Path | /corresponsales/api/factura/pago/ |
| Authentication | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/pago/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
"request_id": "f7002954-8ec2-4248-9c8e-6625a2588117"
}
| Field | Type | Required | Description |
|---|
request_id |
string (UUID) |
Yes |
The request_id returned by the prior invoice query. Must belong to the same authenticated user. |
The system internally validates that: (1) the request_id matches a successful transaction from the same API user, (2) the invoice has Usable: true. If either condition fails, returns 400.
Response 200 — Payment notified
{
"status": "0",
"message": "Pago notificado exitosamente",
"data": {
"ReciboPago": "2025407608",
"Pliq_ReciboPago": "...",
...
},
"llave_recibo": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
| Field | Description |
|---|
status | "0" = success, "1" = error |
data | Settlement data returned by the configured SP. Exact fields depend on implementation. |
llave_recibo | TLOG key of the generated cash receipt. Save it for potential reversals. |
3. Payment reversal
Cancels a previously notified payment. The body parameters are defined by the stored procedure configured for this endpoint.
| Property | Value |
|---|
| Method | POST |
| Path | /corresponsales/api/factura/pago/reversar/ |
| Authentication | JWT Bearer + api-key |
Request
POST /corresponsales/api/factura/pago/reversar/
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
api-key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
{
... // parameters defined by the configured SP
}
This endpoint has no fixed body schema at the API layer. Required fields are determined by the stored procedure configured for your company. Contact your operations team.
Response 200 — Reversal successful
{
"status": "0",
"message": "Pago revertido exitosamente",
"data": [...]
}