API
El contexto técnico que el Swagger no expresa — identificadores, errores, paginación e idempotencia
El Swagger tiene el contrato de cada endpoint: campos, tipos, ejemplos y códigos de respuesta. Es la fuente de verdad para eso.
Lo que no puede expresar son las convenciones compartidas por todos los endpoints. Están acá.
Identificadores
idType, y la decisión de la que dependen todas las demás.
Errores
El envelope común, el code para ramificar, y el traceId que necesita soporte.
Paginación y filtros
page y limit no tienen default, y los filtros van como JSON en el query.
Idempotencia
operationId, qué devuelve un duplicado, y qué es seguro reintentar.
Webhooks
Configuración, autenticación, payloads y garantías de entrega.
Ambientes y acceso
Hay dos ambientes: sandbox, para desarrollar y probar, y producción.
La URL base y las credenciales de cada uno te las entrega tu administrador, junto con el acceso al Control Center. No se deducen ni son las mismas para todas las organizaciones, y las credenciales de sandbox no operan en producción.
Si todavía no las tenés, pedilas antes de escribir código: sin ellas no se puede probar nada.
Versionado
Conviven dos formas de ruta y no hay una regla que las prediga:
| Forma | Ejemplos |
|---|---|
| Con versión | /v1/feed/account/{accountId}, /v1/gamification/missions/progress/{accountId}, /v1/scoring/accounts/{accountId}/score |
| Sin versión | /accounts, /gamification/triggers, /webhooks |
La ruta exacta de cada endpoint está en el Swagger. No asumas el prefijo /v1 ni lo saques por tu cuenta.
Compatibilidad
UIN puede agregar campos y valores de enum sin cambiar de versión. Tu integración debe ignorar los campos que no conoce y tolerar valores de enum nuevos. Sacar, renombrar o cambiar el tipo de un campo solo ocurre en una versión nueva de la ruta, con aviso previo.
Los dos 403
Un 403 puede significar dos cosas distintas, y conviene distinguirlas antes de escribir a soporte:
- La feature no está habilitada para tu cliente. Cada módulo está detrás de una funcionalidad contratada, y su ausencia responde a lo contratado, no a un error.
- mTLS. Si tu organización lo tiene activo, falta el certificado o el presentado no ancla a tu tenant — y entonces cualquier endpoint responde
403, no sólo los sensibles.
Ver Errores y Credenciales.
Convenciones generales
- HTTPS obligatorio.
- Content-Type:
application/json. - Auth: header
Authorization: Bearer <API key>en todas las requests. Ver Credenciales. - Fechas: ISO-8601 en UTC. Convertilas a la zona del usuario antes de mostrarlas.