API docs by Redocly

API de integración NOMAD (1.0.0)

Download OpenAPI specification:

Consulta de solo lectura de empleados y nóminas timbradas. No permite escribir, timbrar ni cancelar nada, y no da acceso al sistema NOMAD ni a su base de datos.

Autenticación

OAuth 2.0 client credentials (RFC 6749 §4.4). Con el client_id y el secreto que se le entregan, solicite un token al tokenUrl y envíelo en cada petición:

Authorization: Bearer <access_token>
  • El token dura aproximadamente 1 hora; cuando venza, pida otro (no hay refresh token).
  • Cada petición se valida contra el proveedor de identidad, por lo que un token revocado, o un cliente dado de baja, deja de funcionar de inmediato.
  • Scopes: empleados:read (para /empleados) y nominas:read (para /nominas).
  • Solo verá los datos de las sociedades y clientes que se autorizaron para sus credenciales. Pedir algo fuera de ese alcance responde 403.

Cómo sincronizar

Los dos recursos se recorren igual y devuelven { data, nextCursor, count }.

  1. Sincronice primero /empleados y después /nominas: el detalle de una nómina hace referencia a empleados del catálogo.
  2. Carga completa: llame sin updatedSince y siga nextCursor hasta que sea null.
  3. Cargas incrementales: tome el encabezado X-Sync-Watermark de la corrida anterior (es el mismo en todas sus páginas) y páselo como updatedSince. Guárdelo solo después de procesar la última página; no use la hora en que terminó su proceso.
  4. updatedSince es inclusivo, así que puede recibir filas que ya tiene: actualice por identificador (id en empleados y nóminas, uuidCfdi en el detalle) en lugar de insertar, y repetir una corrida no duplica nada.
  5. Recomendado: además de las incrementales, haga una carga completa periódica para reconciliar cualquier cambio que no haya movido la fecha de modificación en origen.
  6. Los cancelados y los retimbrados no se borran: un comprobante cancelado sigue apareciendo con estadoTimbre: CANCELADO y su sustituto llega con otro uuidCfdi.

El cursor es opaco, está atado a sus credenciales y a los filtros de esa corrida (cambiarlos responde 400) y expira a las 24 horas (410; inicie una corrida nueva sin cursor).

Límites

Por cliente: 60 solicitudes por minuto, ráfaga de 10 y máximo 2 consultas simultáneas. Al excederlos se responde 429 con el encabezado Retry-After (segundos). Una sincronización diaria queda muy por debajo de estos límites.

Formato de los datos

  • Fechas YYYY-MM-DD; marcas de tiempo ISO 8601 con zona horaria.
  • Los importes son cadenas decimales exactas con dos decimales ("18450.30"), nunca números de punto flotante.
  • Los campos opcionales sin dato vienen como null.
  • CURP/RFC ausentes o de longitud incorrecta se entregan como Sin Informacion, para solicitar su captura a los operadores. Esa marca no es una identidad fiscal ni una llave para cruzar personas.
  • NSS sin 11 dígitos se entrega como null.
  • bajaAt usa medianoche en America/Mexico_City por convención: el origen solo proporciona la fecha, no la hora real de baja.

Errores

Todos los errores son application/problem+json (RFC 9457) con type, title, status, detail y un requestId que puede citar al pedir soporte. Un fallo de una dependencia responde 503; nunca un 200 vacío.

Empleados

Catálogo de empleados autorizados. Sincronícelo antes que las nóminas.

Catálogo de empleados autorizados

Empleados con al menos una relación laboral dentro de las sociedades y clientes autorizados, incluidos los dados de baja. Ordenado por updatedAt y id ascendente.

Authorizations:
oauth2ClientCredentials
query Parameters
updatedSince
string <date-time>

Solo filas modificadas en o después de esta marca de tiempo (inclusivo). Use el X-Sync-Watermark de la corrida anterior. Sin este parámetro se devuelve todo el historial autorizado.

cursor
string

El nextCursor de la página anterior. Es opaco: no lo interprete ni lo modifique. Solo sirve con las mismas credenciales, ruta y filtros con los que se emitió, y expira a las 24 horas.

limit
integer [ 1 .. 250 ]
Default: 100

Filas por página.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": null,
  • "count": 1
}

Nóminas

Nóminas timbradas con el detalle de cada comprobante (CFDI).

Nóminas timbradas, con su detalle por trabajador

Nóminas de las sociedades y clientes autorizados, con un elemento de detalle por cada comprobante (CFDI), incluidos los cancelados y los retimbrados. Cada nómina llega completa: su detalle no se recorta. Solo se entregan nóminas con al menos un comprobante timbrado (nunca borradores). Ordenado por updatedAt y id ascendente.

Authorizations:
oauth2ClientCredentials
query Parameters
updatedSince
string <date-time>

Solo filas modificadas en o después de esta marca de tiempo (inclusivo). Use el X-Sync-Watermark de la corrida anterior. Sin este parámetro se devuelve todo el historial autorizado.

cursor
string

El nextCursor de la página anterior. Es opaco: no lo interprete ni lo modifique. Solo sirve con las mismas credenciales, ruta y filtros con los que se emitió, y expira a las 24 horas.

limit
integer [ 1 .. 250 ]
Default: 100

Filas por página.

ejercicio
string^[0-9]{4}$

Año (YYYY). Filtra por el año de periodoDesde, la fecha inicial del periodo de la nómina; no por fechaPago.

rfcSociedad
string

RFC de una sociedad emisora, para reducir la consulta a esa sociedad. No concede acceso por sí solo: una sociedad fuera de las autorizadas para sus credenciales responde 403.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "nextCursor": null,
  • "count": 1
}