Integración · API
Aburrida a propósito.
REST sobre HTTPS, JSON de entrada y de salida, versiones fechadas, escrituras idempotentes y errores que le dicen qué campo estaba mal. Más allá de los recursos aquí no hay nada que aprender, y esa es la intención.
- RESTsobre HTTPS
- 24 hventana de idempotencia
- 90 díaspreaviso de retirada
Contrato
Las partes en las que va a confiar
- Versiones
- Fechadas, fijadas por clave
- Idempotencia
Idempotency-Key, 24 horas- Errores
- Por campo, legibles por máquina
- Límites de frecuencia
- Por clave, cabeceras en cada respuesta
- Autenticación
- Clave Bearer, solo del lado servidor
- Reloj
- UTC, RFC 3339
Una clave queda fijada a una versión. Las versiones nuevas no le llegan hasta que usted se mueve, y una versión se mantiene al menos 90 días desde que se anuncia su sucesora.
Repetir una creación devuelve la comprobación original. Una tormenta de reintentos durante un incidente no puede abrir cinco comprobaciones sobre un jugador.
Un 422 nombra el campo y la regla incumplida. Nada devuelve un 400 pelado con prosa en el cuerpo.
El resto y el momento de reinicio están siempre presentes: un cliente puede frenar antes de que se le diga que pare.
Las claves no llegan nunca a un navegador ni a un teléfono; el cliente recibe en su lugar tokens de paso de vida corta.
Cada marca de tiempo en cada carga útil y cada expediente, sin variantes en hora local.
Recursos
La superficie, completa
| Método y ruta | Hace | Idempotente |
|---|---|---|
POST /v1/checks | Abre una comprobación para una persona en un mercado | Sí, 24 h |
GET /v1/checks/{id} | Estado actual, veredicto y motivos | — |
POST /v1/checks/{id}/cancel | Abandona una comprobación que aún está recogiendo | Sí |
GET /v1/evidence/{id} | El expediente sellado detrás de un veredicto | — |
GET /v1/events | El diario, para todo lo que un webhook no pudo entregar | — |
POST /v1/policies | Publica una versión de política para un mercado | Sí |
POST /v1/exclusions | Publica su fichero de autoprohibición, allí donde usted es la fuente válida | Sí |
Siete recursos. Una API de verificación que necesita más suele estar exponiendo su propia estructura interna en vez de su problema.
Decisiones
Por qué tiene esta forma
¿Por qué la respuesta no se transmite en flujo?
Porque la parte lenta es el jugador, no nosotros. Una comprobación espera a que una persona encuentre su pasaporte; mantener una conexión abierta para eso es un coste para usted y una fragilidad para ambos. El webhook existe exactamente por esto.
¿Por qué el veredicto no incluye una puntuación?
Incluye las puntuaciones de cada señal, en el expediente. Lo que no hace es reducirlas a un número único, porque el número único es justo lo que después no se puede explicar a un supervisor.
¿Podemos asociar una política a una comprobación de forma retroactiva?
No. Una comprobación anota la versión de política que la decidió, y ese dato es inmutable. Volver a decidir bajo una política nueva abre una comprobación nueva que remite a la antigua.