Conceptos

Conceptos

Lo que todo integrador del API Gateway debe dominar antes de ir a producción: autenticación, el sobre de respuesta, idempotencia, reintentos, errores problem+json, paginación, montos, deprecaciones y límites de tasa.

El gateway es una superficie headless y server-to-server: tu sistema (ERP, CRM, core financiero, app de la fintech, HIS de la IPS) le habla por HTTPS con una llave, y el gateway autentica, valida, aplica idempotencia y límites, y enruta al motor de negocio de Compense. Estas reglas son las mismas en los 13 módulos; entenderlas una vez te ahorra errores en todos.

sequenceDiagram
  autonumber
  participant S as Tu sistema (SDK)
  participant G as API Gateway /v1/gateway
  participant M as Motor de Compense
  S->>G: POST + X-API-Key + Idempotency-Key
  G->>G: llave → tenant + scopes · límite de tasa
  G->>G: ¿Idempotency-Key ya vista?
  alt primera vez
    G->>M: petición normalizada
    M-->>G: resultado del motor
    G-->>S: 200 {status, transaction_id, module, data}
  else repetida
    G-->>S: 200 respuesta guardada (idempotent_replay: true)
  end
  Note over S,G: Errores: application/problem+json con trace_id (= X-Request-ID)
ConceptoEn una frase
AutenticaciónCabecera X-API-Key; la llave resuelve el tenant y sus scopes.
Sobre de respuestaLas escrituras devuelven {status, transaction_id, module, data}; las lecturas, el cuerpo del motor.
IdempotenciaToda escritura lleva Idempotency-Key; repetirla devuelve la respuesta original.
Reintentos y backoffLos SDK reintentan 429/502/503/504 con backoff exponencial y jitter; las escrituras, solo si lo activas.
ErroresRFC 9457 problem+json, una excepción tipada por código en cada SDK.
PaginaciónPage (número de página) y OffsetPage (limit/offset).
MontosSiempre texto decimal ("3500000.00"), nunca float.
DeprecacionesCabeceras Deprecation/Sunset; los SDK avisan una vez por operación.
Límites de tasaLímite por minuto y cuota mensual por llave; 429 con Retry-After.

En esta sección #

Conceptos AutenticaciónLa cabecera X-API-Key, cómo la llave resuelve el tenant y los scopes, qué significan 401 y 403, la lista de IP permitidas y la firma de peticiones de alto valor. Conceptos Sobre de respuestaQué devuelve el gateway: el sobre de transacción de las escrituras (status, transaction_id, module, data, idempotent_replay), el cuerpo del motor en las lecturas y cómo … Conceptos IdempotenciaPor qué cada escritura lleva Idempotency-Key, qué pasa cuando la repites (respuesta guardada o 409), cómo elegir llaves estables por operación de negocio y cómo la … Conceptos Reintentos y backoffQué reintentan los SDK por su cuenta (429, 502, 503, 504 con backoff exponencial, jitter y Retry-After), por qué las escrituras no se reintentan por defecto y cómo … Conceptos Errores problem+jsonEl formato RFC 9457 de los errores del gateway, la tabla de códigos y tipos, la excepción equivalente en cada SDK y cómo leer los errores de validación y los rechazos del … Conceptos PaginaciónLas dos formas de lista del gateway (Page con número de página y OffsetPage con limit/offset) y cómo recorrerlas completas en Python, JavaScript/TypeScript, PHP, .NET y … Conceptos Montos como texto decimalPor qué el gateway envía y recibe dinero como texto decimal (MoneyCOP), qué tipos acepta cada SDK al enviar un monto y cómo leer los montos de las respuestas sin perder … Conceptos Versionado y deprecacionesCómo se versionan el API y los SDK (SemVer alineado con /v1), qué cambios no rompen tu integración y cómo te avisan los SDK cuando una operación va a retirarse (cabeceras … Conceptos Límites de tasa y cuotasEl límite por minuto y la cuota mensual de cada llave, las cabeceras RateLimit-*, qué hacer ante un 429 y los límites de tamaño de las peticiones.