Referencia de la API

Explora los endpoints desde la barra lateral, agrupados por recurso (Máquinas, Operadores, SKUs, Registros de producción, Reportes, etc.). La página de cada endpoint incluye sus parámetros, los esquemas de solicitud y respuesta, y un generador de solicitudes en vivo con ejemplos de código.

Convenciones

• Los parámetros de ruta y de consulta usan snake_case, y los cuerpos JSON usan camelCase. Excepciones: los endpoints de señales también responden en snake_case, y GET /v1/shifts recibe machineId, igual que el campo que devuelve.
• Para buscar se hace un POST a una subruta /filters, porque los cuerpos de filtro son anidados.
• Las búsquedas están paginadas: page empieza en 1 y limit es 10 por defecto, y la respuesta envuelve las filas en totalCount / totalPages / currentPage. Otras listas, como GET /v1/machines y las rutas GET /v1/shifts, devuelven un arreglo JSON simple, sin paginación.
• Crear registros con un POST a una colección, como /v1/operators o /v1/production-logs, recibe un arreglo JSON, incluso para un solo registro. Las acciones sobre un registro existente, como asignar un operador a un turno o agregarle defectos, reciben un solo objeto JSON.
• Los IDs de máquinas y operadores son enteros. Los de señales, SKUs, órdenes de trabajo, registros de producción y velocidades nominales son cadenas UUID. Los endpoints de señales reciben el uuid de la máquina, no su ID entero.
• Una hora sin desfase UTC se interpreta como UTC.

Permisos

Cada endpoint requiere un scope con la forma section.action, como shifts.read o production_logs.delete. La página de cada endpoint empieza con su Scope requerido, y los endpoints que escriben en turnos también indican los scopes relacionados que una integración necesita para revisar o deshacer lo que envía. Las llaves creadas en la app de Pulsar en Configuraciones → Integraciones tienen todos los scopes públicos. Una llave sin el scope que requiere un endpoint recibe 403 con el código missing_scope, y detail indica el scope que falta:

{ "code": "missing_scope", "detail": "Not enough permissions. Missing scope: shifts.read" }

Errores

Todos los errores excepto 422 tienen el mismo cuerpo: un code estable para decidir qué hacer, y un detail legible que puede cambiar, así que no lo analices.

{ "code": "shift_not_found", "detail": "No shift of yours matches the request." }

La descripción y las respuestas de cada endpoint listan los códigos que devuelve, como shift_not_found, insufficient_production o idempotency_key_reused. Se pueden agregar códigos nuevos, así que trata uno desconocido según su estado HTTP. Si no hay un código más específico, cada estado tiene uno genérico:

Un 422 significa que el cuerpo o un parámetro no pasó la validación. Su detail es una lista, y el loc de cada elemento indica el campo que falló.

Reintentos

Si una llamada fallida registró algo depende de cómo falló:

• Una respuesta 4XX significa que la solicitud se rechazó y no se registró nada. Corrígela y vuelve a enviarla.
• Un tiempo de espera agotado, una conexión cortada o una respuesta 5XX dejan el resultado desconocido. La solicitud pudo haberse registrado aunque nunca recibiste la respuesta.

Las llamadas que registran producción o defectos se suman a lo que ya existe, así que una solicitud enviada dos veces se registra dos veces. Tres endpoints aceptan un encabezado Idempotency-Key que hace seguro un reintento: POST /v1/production-logs, POST /v1/shifts/defects y POST /v1/shifts/{shift_id}/defects. Genera un valor único para cada solicitud, como un UUID, y envía la misma llave y el mismo cuerpo en cada reintento de esa solicitud:

• Si la solicitud original se registró, el reintento no registra nada y devuelve la respuesta original, con el encabezado Idempotent-Replayed: true.
• Si la original no se registró, el reintento se procesa como una solicitud nueva.
• Reutilizar una llave con otro cuerpo u otra URL devuelve 409. También lo devuelve un reintento mientras la original todavía se está procesando: espera un momento y vuelve a intentarlo.

Las llaves de idempotencia las comparten todas las llaves de API de tu empresa, y cada una se guarda 24 horas. Después, una solicitud con la misma llave se procesa como nueva.

Sin un Idempotency-Key, revisa lo que se registró antes de volver a enviar la solicitud. GET /v1/shifts/{shift_id}/defects lista los defectos de un turno, y POST /v1/production-logs/filters busca registros de producción, también por turno con "shifts": {"include": [<shift id>]}.

Cubrir un periodo largo

GET /v1/shifts acepta un rango de hasta 31 días. Para cubrir un periodo más largo, divídelo en rangos consecutivos, donde el to de cada rango es el from del siguiente, y agrega match=start. Así cada turno se devuelve exactamente una vez. Con el valor por defecto match=overlap, un turno que cruza el límite entre dos rangos aparece en ambos, así que elimina los duplicados por id antes de actuar sobre ellos.