Panorama del API

Dirección base, forma de una solicitud, paginación, idempotencia y qué significa aquí una versión.

Un API REST sobre JSON. Cada solicitud se autentica con un token, cada recurso pertenece a la organización de ese token, y cada escritura se puede reintentar sin riesgo.

POST /v1/credentials HTTP/1.1
Host: api.nomi-tech.com
Authorization: Bearer nomi_sk_live_EXAMPLE
Content-Type: application/json
Idempotency-Key: order_example_12345

Dirección base y versión

Todo vive bajo https://api.nomi-tech.com. El prefijo /v1 es la versión del API: a las respuestas se les agregan campos sin aviso, y dentro de una versión no se quita ninguno ni se le cambia el significado.

Paginación

Los endpoints de lista reciben limit (1–100, por omisión 25) y paginan de dos maneras. cursor es el nextCursor de la respuesta anterior y es lo que debe usar un proceso. offset además devuelve total, que es lo que necesita una pantalla con números de página.

{
  "data": [ … ],
  "nextCursor": "…",
  "total": 1284
}

Idempotencia

Manda un Idempotency-Key en cualquier POST o PATCH y un reintento repite la primera respuesta en vez de hacer el trabajo dos veces. Las llaves duran 24 horas y son de tu organización. Tres casos:

• Misma llave, misma solicitud, ya contestada — se repite la respuesta guardada.
• Misma llave, solicitud distinta — se rechaza. Servirle la primera respuesta a una segunda llamada distinta es una escritura que desaparece en silencio.
• Misma llave, todavía corriendo — 409. Reintenta en un momento.