Saltar al contenido principal

API del CMS v1

Estado: Próximamente

El contrato v1 se publica para revisión y diseño de integraciones. La plataforma del gateway (token, alcances, idempotencia, límites de tasa, cursores y errores) está implementada y probada, pero ninguna operación de negocio funciona todavía de punta a punta: el servicio aún no está desplegado y no hay sandbox ni URL pública. En las guías, https://api-cms.example.com es un dominio de ejemplo.

La API del CMS v1 permite a emisores, fintechs, procesadores y sistemas de integración del emisor gestionar tarjetas de crédito y prepago de FINORA (no débito): clientes, cuentas, saldos, movimientos, plásticos, vínculos plástico-cuenta, topes, línea de crédito, recargas y ajustes prepago, lotes, estados de cuenta y eventos.

Arquitectura en una imagen​

Tú hablas siempre con el gateway. El gateway verifica tu token y tus alcances, aplica la idempotencia y los límites de tasa, firma el contexto de cada petición y la entrega al CMS, que vuelve a verificar que cada objeto pertenece a tus productos.

Principios del contrato​

  • Nunca hay número de tarjeta. Cada plástico se identifica por cardId (UUID opaco); las respuestas solo llevan panMasked (6 + 4) y last4. Un número de tarjeta en una consulta o un cuerpo se rechaza.
  • Montos como texto decimal con la escala exacta de su unidad: Bs y USD con 2 decimales, UVC con 4, IDI con 8. En las escrituras el importe es siempre positivo; el sentido lo dan sentido o tipo. Nunca se redondea.
  • Idempotency-Key obligatoria en las escrituras, con almacén que falla cerrado.
  • Paginación por cursor opaco y firmado, sin total exacto.
  • Errores RFC 9457 con un codigo estable.
  • Un objeto ajeno responde 404, nunca 403: no se revela si existe.
  • Los sistemas externos solicitan; no aprueban. Cambios de línea, lotes y cambios de cuenta principal quedan pendientes (HTTP 202) y los decide una persona en la consola del emisor con cuatro ojos.
  • Un emisor por instalación: no hay identificador de emisor en las rutas.

Guías​

  1. Inicio rápido: llaves, primer token y primeras lecturas en cinco pasos.
  2. Autenticación y alcances: private_key_jwt con ES256, contenido del token y alcances por operación.
  3. Idempotencia: Idempotency-Key, 409 en curso con Retry-After y reintentos seguros.
  4. Paginación y límites de tasa: cursor firmado, cabeceras X-RateLimit-* y topes.
  5. Errores y reintentos: catálogo completo de códigos y cuáles se reintentan.
  6. Movimientos y ajustes por indexación: qué se oculta por defecto y cómo activarlo.
  7. Solicitudes que aprueba una persona: respuestas 202 y su seguimiento.
  8. Eventos y webhooks: suscripciones PULL y WEBHOOK, firma, reintentos y replay.
  9. Referencia de la API: las 54 operaciones del contrato.

Qué llega en una fase posterior​

ElementoEstado
Todas las operaciones de negocio de /v1Próximamente (sin despliegue ni sandbox)
TLS mutuo (mTLS) para dinero, límites y búsqueda por númeroPróximamente (fase 2)
POST /v1/cards/lookup (buscar plástico por número)Próximamente (fase 2, solo con mTLS)
Lotes por archivo CSVPróximamente (hoy solo JSON, hasta 1.000 filas)
Sandbox con client_secretPróximamente