Autenticación
Todas las llamadas usan la API key que genera el administrador, en cualquiera de estos encabezados:
Authorization: Bearer sk_xxxxxxxxxxxxxxxx X-API-Key: sk_xxxxxxxxxxxxxxxx
Cada API key solo ve los SINPE del buzón de su propio cliente. Límite: 120 solicitudes por minuto por IP.
POST /api/v1/verificar
Busca un SINPE por los últimos 4 dígitos del número de referencia y, si lo encuentra, lo marca como usado para que el mismo comprobante no se pueda usar dos veces.
Cuerpo (JSON)
| Campo | Tipo | Descripción |
|---|---|---|
| ultimos4 | string | Obligatorio. Últimos 4 dígitos del comprobante (ej. "9419"). |
| monto | number | string | Opcional, recomendado. Monto esperado en colones (4000 o "4,000.00"). Si no coincide responde monto_no_coincide. |
| telefono | string | Opcional. Teléfono de origen, para desempatar. |
| referencia | string | Opcional. Número de referencia completo. |
| referencia_externa | string | Opcional. Su número de pedido o factura; queda guardado junto al SINPE. |
| consumir | boolean | Opcional, por defecto true. Con false solo consulta sin marcar como usado. |
Ejemplo
curl -X POST https://SU-DOMINIO/api/v1/verificar \
-H "Authorization: Bearer sk_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"ultimos4":"9419","monto":4000,"referencia_externa":"PEDIDO-123"}'
Respuesta 200 · verificado
{
"verificado": true,
"consumido": true,
"transaccion": {
"referencia": "2022083015284000209039419",
"ultimos4": "9419",
"monto": 4000,
"monto_texto": "₡4,000.00",
"moneda": "CRC",
"telefono_origen": "00000000",
"nombre_origen": "VALVERDE SANCHEZ IGNACIO FRANCISCO",
"entidad_origen": "Banco de Costa Rica",
"motivo": "Camiseta Nacho*",
"fecha_transaccion": "2022-08-30T08:52:00-06:00",
"recibido_en": "2022-08-30T14:52:11.000Z",
"usado": true,
"usado_en": "2022-08-30T14:55:02.000Z",
"referencia_externa": "PEDIDO-123"
}
}
Respuestas de error
| HTTP | motivo | Significado |
|---|---|---|
| 400 | parametro_invalido | Faltan los 4 dígitos o el monto no es válido. |
| 401 | — | API key faltante, inválida o revocada. |
| 403 | — | El cliente está desactivado. |
| 404 | no_encontrado | No ha llegado ningún SINPE con esos dígitos (en los últimos 30 días). |
| 409 | ya_utilizado | El SINPE existe pero ya fue usado. Incluye transaccion con fecha y referencia externa. |
| 409 | ambiguo | Hay varios SINPE disponibles con esos 4 dígitos. Reintente enviando monto, telefono o referencia. |
| 422 | monto_no_coincide | El SINPE existe pero con otro monto. Incluye monto_recibido cuando hay un único candidato. |
Si no lo encuentra, el servidor revisa el buzón en ese mismo momento y vuelve a buscar antes de responder, así un SINPE que acaba de llegar se detecta sin esperar al siguiente ciclo.
GET /api/v1/verificar/{ultimos4}
Igual que el anterior pero solo consulta, nunca marca como usado. Acepta ?monto= y ?telefono=.
curl https://SU-DOMINIO/api/v1/verificar/9419?monto=4000 -H "Authorization: Bearer sk_xxxxxxxx"
GET /api/v1/transacciones
Lista los SINPE recibidos (más recientes primero). Filtros: ultimos4, usado=true|false, limite (máx. 500).
GET /api/v1/transacciones/{referencia}
Un SINPE por su número de referencia completo.
POST /api/v1/sincronizar
Revisa el buzón de correo en este momento y devuelve un resumen de lo encontrado.