Skip to content

Recursos ​

Todas las rutas son relativas a la dirección de la cuenta, https://<subdominio>.safetypanel.com.ar/api/v1/, y todas requieren una key con el permiso del recurso. Con PATCH se modifican los campos externos, y en los recursos que lo indican también sus propios datos. Toda escritura acepta el encabezado Idempotency-Key para reintentar sin repetirla, y algunas lo exigen: cada recurso lo indica.

Cuenta ​

GET   /api/v1/account
PATCH /api/v1/account

Permisos: account:read para leer, account:write para leer y modificar.

La cuenta a la que pertenece la key. Es la primera llamada para comprobar que una credencial funciona.

CampoTipoQué contiene
identeroIdentificador de la cuenta.
nametextoNombre de la cuenta.
subdomaintextoSubdominio de la cuenta.
account_typetexto o nullagency (consultora) o company (empresa).
countrytextoPaís de la cuenta, en código de dos letras (por ejemplo, AR).
time_zonetextoZona horaria en la que opera la cuenta (por ejemplo, Buenos Aires). Los instantes de la API van igual en UTC.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.

Sitios ​

GET /api/v1/sites
GET /api/v1/sites/:id
POST /api/v1/sites
PATCH /api/v1/sites/:id

Permisos: sites:read para leer, sites:write para leer, dar de alta, modificar, archivar y restaurar.

Los sitios de la cuenta. El listado se pagina y acepta los filtros status, updated_since y external_reference. Un sitio pedido por su id se devuelve en cualquier estado.

json
{
  "id": 12,
  "name": "Planta Norte",
  "cuit": "30-71234567-8 / 30-70123456-1",
  "responsible_entities": [
    {
      "id": 7,
      "name": "Metalúrgica Norte SA",
      "tax_id": "30-71234567-8",
      "economic_activities": [
        { "code": "251101", "name": "Fabricación de carpintería metálica" }
      ]
    },
    {
      "id": 9,
      "name": "Norte Logística SRL",
      "tax_id": "30-70123456-1",
      "economic_activities": []
    }
  ],
  "street": "Av. Siempreviva 742",
  "city": "Springfield",
  "province": "Buenos Aires",
  "postal_code": "1414",
  "status": "active",
  "slug": "planta-norte",
  "site_group": { "id": 3, "name": "Grupo Taller" },
  "responsible_professional_id": 45,
  "professional_ids": [45, 51],
  "external_reference": null,
  "external_metadata": {},
  "created_at": "2026-03-02T14:05:11Z",
  "updated_at": "2026-09-20T18:30:00Z"
}
CampoTipoQué contiene
identeroIdentificador del sitio. Es el único identificador que acepta /sites/:id.
nametextoNombre del sitio.
cuittexto o nullLos CUIT de las razones sociales responsables del sitio, separados por " / " (ver abajo).
responsible_entitieslista de objetosLas razones sociales responsables del sitio, cada una con su id, su name, su tax_id (el CUIT, o null si no lo tiene) y sus economic_activities (ver abajo). Siempre tiene al menos una.
street, city, province, postal_codetexto o nullDirección del sitio.
statustextoactive, inactive o deleted.
slugtextoIdentificador legible que el panel usa en sus direcciones.
site_groupobjeto o nullEl grupo de sitios al que pertenece, con su id y su name, o null si no pertenece a ninguno.
responsible_professional_identero o nullEl profesional responsable del sitio.
professional_idslista de enterosLos profesionales asignados al sitio. Para saber qué profesionales acceden a un sitio, ver a qué sitios accede un profesional.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

En las cuentas de empresa, el panel no carga grupo ni profesional responsable por sitio, así que site_group y responsible_professional_id vienen en null. Si la cuenta antes fue consultora, el grupo que cargó entonces se conserva pero la API no lo muestra, y el responsable que haya quedado se sigue mostrando porque todavía le da acceso al sitio. cuit y responsible_entities vienen en los dos tipos de cuenta. Un cambio de tipo de cuenta no cambia el updated_at de los sitios ni de los grupos: si account_type cambia en /account, hacé una lectura completa.

El CUIT viene de las razones sociales responsables ​

Desde octubre de 2026, el sitio no tiene CUIT propio y el grupo tampoco: el CUIT es de cada razón social responsable del sitio. responsible_entities las lista en el orden en que se vincularon, y cuit une sus CUIT con " / ", como se veían antes los sitios con varios CUIT. Es null cuando ninguna de sus responsables tiene CUIT.

Dos cambios en el formato de cuit respecto de antes:

  • Siempre con guiones. Un CUIT cargado sin guiones (30712345678) ahora llega como 30-71234567-8.
  • Ya no se hereda del grupo. Los sitios que tomaban el CUIT de su grupo tienen ahora como responsable una razón social con ese CUIT, así que el valor no cambia.

Para leer cada razón social por separado, usá responsible_entities en lugar de partir cuit.

Las actividades económicas de cada responsable ​

Desde octubre de 2026, cada objeto de responsible_entities trae economic_activities: la lista de actividades económicas de esa razón social, ordenada por código, cada una con su code (texto, en Argentina los seis dígitos del CLAE) y su name. Es una lista vacía cuando no tiene ninguna cargada.

El sitio no tiene un campo economic_activities propio. Las actividades son de cada razón social, y un sitio con varias responsables tiene las de cada una: una sola lista las mezclaría sin decir de quién es cada actividad. Para obtener todas las del sitio, recorré responsible_entities.

Estados ​

statusQué significa
activeActivo en el panel. Es el único estado que devuelve el listado por defecto.
inactiveInactivo en el panel.
deletedArchivado en el panel. El sitio se conserva con toda su información.

Para enterarte de los cambios de estado al sincronizar, pedí también status=inactive y status=deleted junto con updated_since.

Dar de alta ​

POST /api/v1/sites crea un sitio en la cuenta con los campos que se envíen en JSON. Es lo que usa un ERP para abrir el sitio de un contrato nuevo. Exige el encabezado Idempotency-Key: si la llamada se corta, reintentala con la misma clave y el sitio no se crea dos veces.

sh
curl -X POST "https://tuempresa.safetypanel.com.ar/api/v1/sites" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3d9b7f20-1c4e-4a8b-b6f2-8e0a5c1d9f37" \
  -d '{"name": "Planta Sur", "street": "Ruta 2 km 40", "city": "Brandsen", "responsible_entity_ids": [7], "site_group_id": 3, "external_reference": "C-981"}'
CampoObligatorioQué acepta
nameSíTexto.
responsible_entity_idsEn las consultoras, síLista con el id de una o más razones sociales vigentes de la cuenta: las responsables del sitio. En una empresa, si no se envía, la responsable es la razón social de la cuenta, igual que en el panel.
street, city, province, postal_codeNoTexto: la dirección del sitio.
site_group_idNoEl id de un grupo de sitios de la cuenta, o null para que no pertenezca a ninguno. Solo en las consultoras: en una empresa responde 422.
external_reference, external_metadataNoLos campos externos de tu sistema.

Responde 201 con el sitio, igual que GET, y el encabezado Location con su dirección. El sitio nace como uno cargado desde el panel con los valores que el formulario trae de entrada:

  • Activo, con el slug generado a partir del nombre.
  • Sin profesional responsable ni profesionales asignados. Se asignan desde el panel.
  • Con los módulos apagados para el sitio. Cada módulo se enciende por sitio desde el panel; la firma con validación y el acuse de lectura siguen lo que tenga configurado la cuenta.
  • En las consultoras, con el modelo de servicio Abono.

Un id de otra cuenta en responsible_entity_ids o en site_group_id responde 422, igual que una razón social fusionada, que trae además el survivor_id de la que la reemplaza. Cualquier otro campo, incluido status, responde 422.

Modificar ​

PATCH /api/v1/sites/:id cambia los campos que se envíen, los mismos del alta más status. Un campo que no se envía no cambia, y uno que no se puede escribir responde 422. La respuesta es el sitio completo, como lo devuelve GET.

  • responsible_entity_ids reemplaza la lista entera. Una razón social que deja de estar se desvincula del sitio sin borrar nada: su historia en el sitio se conserva, como cuando se cambia desde el panel. La lista no puede quedar vacía.
  • site_group_id mueve el sitio a otro grupo, y null lo saca del suyo.

Un PATCH que envía status o responsible_entity_ids, aunque sea con el valor que ya tiene, exige el encabezado Idempotency-Key, porque sus efectos van más allá del propio sitio (las tablets del sitio, los vínculos de las razones sociales, los documentos distribuidos). Uno que solo envía los demás datos lo acepta, pero no lo exige.

Archivar y restaurar ​

No hay DELETE: un sitio se archiva y se restaura cambiando su status con PATCH.

sh
curl -X PATCH "https://tuempresa.safetypanel.com.ar/api/v1/sites/12" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9a4e1b7c-2d6f-4c3a-8e5b-0f7d3a9c1b62" \
  -d '{"status": "deleted"}'
  • deleted lo archiva, inactive lo pasa a inactivo y active lo restaura. Tiene los mismos efectos que hacerlo desde el panel: al archivarlo, por ejemplo, se cierran los turnos abiertos en las tablets del sitio.
  • Archivar no borra nada. El sitio se conserva con toda su información y se restaura con todo su historial. Cuando un contrato vuelve, restaurá su sitio en lugar de crear otro: buscalo por external_reference, que encuentra también los archivados.

Qué mueve updated_at ​

Además de cualquier cambio en los datos del propio sitio, el updated_at de un sitio cambia cuando:

  • se asigna o se quita un profesional;
  • el sitio entra o sale de un grupo, o su grupo cambia de nombre o se elimina;
  • se agrega o se quita una de sus razones sociales responsables, o una de ellas cambia de nombre, de CUIT o de actividades económicas.

Así, updated_since alcanza para enterarse de todo lo que cambió en un sitio.

Grupos de sitios ​

GET /api/v1/site_groups
GET /api/v1/site_groups/:id
PATCH /api/v1/site_groups/:id

Permisos: site_groups:read para leer, site_groups:write para leer y modificar.

Los grupos de sitios de la cuenta: los sitios que una consultora atiende bajo un mismo contrato. Las empresas no tienen grupos, así que en sus cuentas el listado viene vacío y pedir un grupo por su id responde 404. Vale también para una cuenta que antes fue consultora: sus grupos se conservan y vuelven a aparecer si la cuenta vuelve a ser consultora.

El listado se pagina y acepta los filtros updated_since y external_reference. Los grupos no tienen estado, así que no aceptan status.

json
{
  "id": 3,
  "name": "Grupo Taller",
  "site_ids": [12, 14, 20],
  "external_reference": null,
  "external_metadata": {},
  "created_at": "2026-02-10T09:00:00Z",
  "updated_at": "2026-09-18T11:22:03Z"
}
CampoTipoQué contiene
identeroIdentificador del grupo.
nametextoNombre del grupo.
site_idslista de enterosTodos los sitios del grupo, en cualquier estado.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

El updated_at de un grupo también cambia cuando un sitio entra o sale de él.

Desde octubre de 2026, el grupo ya no trae la clave cuit, que venía siempre en null porque el grupo no tiene CUIT. El CUIT de cada sitio está en sus responsible_entities.

Un grupo eliminado deja de aparecer en la API. Sus sitios siguen existiendo: su updated_at cambia y su site_group pasa a ser null, así que una sincronización con updated_since sobre los sitios se entera.

Profesionales ​

GET /api/v1/professionals
GET /api/v1/professionals/:id
PATCH /api/v1/professionals/:id

Permisos: professionals:read para leer, professionals:write para leer y modificar.

Los profesionales de la cuenta. Sirve, por ejemplo, para que otra plataforma deje entrar a un profesional si su email está en esta lista.

El listado se pagina y acepta los filtros status, updated_since y external_reference. Un profesional pedido por su id se devuelve en cualquier estado.

json
{
  "id": 45,
  "dni": "30123456",
  "first_name": "Ana",
  "last_name": "Pérez",
  "email": "ana.perez@ejemplo.com",
  "phone": "+54 11 5555-0000",
  "status": "active",
  "full_client_access": false,
  "external_reference": "E-123",
  "external_metadata": { "cost_center": "4410" },
  "created_at": "2026-01-15T13:00:00Z",
  "updated_at": "2026-09-19T20:10:42Z"
}
CampoTipoQué contiene
identeroIdentificador del profesional. Es el que aparece en responsible_professional_id y professional_ids de los sitios.
dnitextoDocumento del profesional.
first_name, last_nametextoNombre y apellido.
emailtextoEmail del profesional.
phonetexto o nullTeléfono.
statustextoactive, inactive o deleted.
full_client_accessbooleanoSi el profesional tiene acceso a todos los sitios de la cuenta (ver abajo).
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

Estados ​

statusQué significa
activeActivo en el panel. Es el único estado que devuelve el listado por defecto.
inactiveInactivo en el panel.
deletedEliminado en el panel: dado de baja. Se conserva con todo su historial y puede restaurarse.

Un profesional dado de baja no aparece en el listado por defecto. Para enterarte de las bajas al sincronizar, pedí también status=deleted junto con updated_since.

A qué sitios accede un profesional ​

La API no trae una lista de sitios por profesional. Se arma con dos recursos:

  • Si full_client_access es true, el profesional accede a todos los sitios de la cuenta, incluidos los que se creen después.
  • Si es false, accede a los sitios que lo nombran como responsable (responsible_professional_id) o que lo incluyen entre los asignados (professional_ids).

Asignar o quitar un profesional cambia el updated_at del sitio, no el del profesional. Para mantener sincronizado el acceso, seguí los cambios de los dos recursos: full_client_access con updated_since sobre los profesionales, y las asignaciones con updated_since sobre los sitios.

Empleados ​

GET /api/v1/employees
GET /api/v1/employees/:id
POST /api/v1/employees
PATCH /api/v1/employees/:id
PUT /api/v1/employees/:id/sites/:site_id
DELETE /api/v1/employees/:id/sites/:site_id

Permisos: employees:read para leer, employees:write para leer, dar de alta, modificar, dar de baja, reactivar y asignar a sitios.

Los empleados de la cuenta, con su empleador y los sitios en los que trabajan. Es el recurso que un sistema de RRHH o un ERP sincroniza con su padrón de personal.

El listado se pagina y acepta los filtros status, updated_since y external_reference, más estos:

FiltroDevuelve
dniLos empleados con ese documento. Acepta el número con o sin puntos ni guiones (30.123.456 es lo mismo que 30123456).
personnel_numberLos empleados con ese número de legajo, exactamente.
site_idLos empleados asignados a ese sitio. Un sitio que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422.

Una búsqueda por dni o por external_reference devuelve al empleado en cualquier estado, igual que la búsqueda por referencia. Así un sistema encuentra a quien está dado de baja y lo reactiva en lugar de cargarlo dos veces. Si se indica status además, se respeta. Un empleado pedido por su id se devuelve en cualquier estado.

json
{
  "id": 81,
  "dni": "30123456",
  "first_name": "Juan",
  "last_name": "Gómez",
  "personnel_number": "L-0042",
  "email": "juan.gomez@ejemplo.com",
  "status": "active",
  "legal_entity_id": 7,
  "sites": [
    { "site_id": 12, "position_id": 30 },
    { "site_id": 14, "position_id": null }
  ],
  "external_reference": "E-123",
  "external_metadata": { "cost_center": "4410" },
  "created_at": "2026-04-02T12:00:00Z",
  "updated_at": "2026-10-20T15:42:10Z"
}
CampoTipoQué contiene
identeroIdentificador del empleado. Es el único identificador que acepta /employees/:id.
dnitextoDocumento del empleado, sin puntos ni guiones.
first_name, last_nametextoNombre y apellido.
personnel_numbertexto o nullNúmero de legajo.
emailtexto o nullEmail del empleado, o null si no tiene uno (ver abajo).
statustextoactive, inactive o deleted.
legal_entity_identeroLa razón social que lo emplea. Siempre tiene una. Se lee en Razones sociales.
siteslista de objetosLos sitios a los que está asignado, ordenados por site_id. Cada uno trae el site_id y el position_id del puesto que ocupa en ese sitio, o null si no tiene puesto ahí. Es una lista vacía si no está asignado a ningún sitio.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

sites lista los sitios en cualquier estado: el estado de cada uno está en los sitios. Funciona igual en las cuentas de consultora y de empresa. En una empresa con un solo sitio, cada empleado nuevo queda asignado a ese sitio automáticamente.

El email puede venir vacío ​

Muchos empleados no tienen email: firman con su DNI. Cuando no se le carga uno, el panel le asigna una dirección de relleno que no recibe correo. La API no la muestra: en ese caso email viene en null, para que tu sistema no la guarde como un dato real.

Estados ​

statusQué significa
activeActivo en el panel. Es el único estado que devuelve el listado por defecto.
inactiveInactivo en el panel: sigue visible y puede iniciar sesión, pero deja de contarse en las tasas de capacitación.
deletedEliminado en el panel: dado de baja. Se conserva con todo su historial (capacitaciones, entregas de EPP firmadas) y puede reactivarse.

Un empleado nunca se borra. Para enterarte de las bajas al sincronizar, pedí también status=deleted junto con updated_since.

Dar de alta ​

POST /api/v1/employees crea un empleado en la cuenta con los campos que se envíen en JSON. Exige el encabezado Idempotency-Key: si la llamada se corta, reintentala con la misma clave y el empleado no se crea dos veces.

sh
curl -X POST "https://tuempresa.safetypanel.com.ar/api/v1/employees" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a4e-8b0d-4d5e-9a3f-2c7b1e9d0a64" \
  -d '{"dni": "30123456", "first_name": "Juan", "last_name": "Gómez", "personnel_number": "L-0042", "legal_entity_id": 7, "external_reference": "E-123"}'
CampoObligatorioQué acepta
dniSíTexto. Se guarda sin puntos ni guiones.
first_name, last_nameSíTexto.
legal_entity_idSíEl id de una razón social vigente de la cuenta: la que lo emplea.
personnel_numberNoTexto: el número de legajo.
emailNoUna dirección de email válida que reciba correo: una de relleno, como @noemail.com, responde 422. Si no se envía, queda vacío y GET lo devuelve en null.
external_reference, external_metadataNoLos campos externos de tu sistema.

Responde 201 con el empleado, igual que GET, y el encabezado Location con su dirección. El empleado nace activo, igual que uno cargado en el panel:

  • Sin sitios. Sus sitios y puestos no se envían en el alta ni en el PATCH: un campo sites responde 422. Se asignan uno por uno, después del alta. En una empresa con un solo sitio, igual que en el panel, queda asignado a ese sitio automáticamente.
  • Sin contraseña. La API no maneja credenciales: hasta que un administrador le asigne una contraseña desde el panel, el empleado no puede entrar al portal.

Cualquier otro campo, incluido status, responde 422.

Modificar ​

PATCH /api/v1/employees/:id cambia los campos que se envíen, los mismos del alta más status. Un campo que no se envía no cambia, y uno que no se puede escribir responde 422. La respuesta es el empleado completo, como lo devuelve GET.

Un PATCH que envía status o legal_entity_id, aunque sea con el valor que ya tiene, exige el encabezado Idempotency-Key, porque sus efectos van más allá del propio empleado (sus documentos para tomar conocimiento, la relación del empleador con sus sitios). Uno que solo envía los demás datos lo acepta, pero no lo exige.

Dar de baja y reactivar ​

No hay DELETE: un empleado se da de baja y se reactiva cambiando su status con PATCH.

sh
curl -X PATCH "https://tuempresa.safetypanel.com.ar/api/v1/employees/81" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b7e4c1d-5a2f-4e8b-9c3d-1f6a2b8e7d40" \
  -d '{"status": "deleted"}'
  • deleted lo da de baja, inactive lo pasa a inactivo y active lo reactiva. Tiene exactamente los mismos efectos que hacerlo desde el panel: por ejemplo, sus documentos pendientes de tomar conocimiento dejan de corresponderle al darlo de baja y vuelven a quedar pendientes al reactivarlo.
  • Reactivar es la forma de recontratar. Un alta con el DNI de un empleado dado de baja responde 422 con el código employee_deactivated y el employee_id del existente: reactivalo con PATCH en lugar de crearlo de nuevo, así conserva todo su historial. Si el DNI es de un empleado activo o inactivo, el alta responde 422 con el código invalid_parameter.
  • Reactivar a alguien cuyo DNI ya tiene otro empleado activo o inactivo responde 422.

Asignar a un sitio ​

PUT /api/v1/employees/:id/sites/:site_id asigna el empleado al sitio, o cambia el puesto que ocupa ahí si ya estaba asignado. Exige el encabezado Idempotency-Key.

sh
curl -X PUT "https://tuempresa.safetypanel.com.ar/api/v1/employees/81/sites/12" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3d9a7f2e-1c4b-4e6a-8f0d-5b2c9e7a1d36" \
  -d '{"position_id": 30}'
CampoObligatorioQué acepta
position_idNoEl id de un puesto de ese sitio, o null para dejarlo sin puesto.
  • Si no estaba asignado, lo asigna y responde 201. Sin position_id, queda en el sitio sin puesto.
  • Si ya estaba asignado, responde 200. Con position_id cambia su puesto, y con null se lo quita. Sin position_id, el puesto no cambia.

Las dos respuestas traen el empleado completo, como lo devuelve GET, con el sitio ya en sites. Repetir el mismo pedido no cambia nada, así que un sistema puede enviar la asignación que tiene registrada sin preguntar antes si ya existe.

Tiene los mismos efectos que asignarlo desde el panel: al darle un puesto se le agrega el EPP que ese puesto requiere, y se actualizan los documentos para tomar conocimiento que le corresponden en el sitio. Cambiar de puesto nunca le quita EPP requerido: revisalo desde el panel.

No se puede asignar un empleado dado de baja (422 employee_deactivated) ni asignar a un sitio archivado (422 site_deactivated): los dos tienen status: deleted. Mientras alguno de los dos esté así, cualquier PUT responde ese 422, aunque la asignación ya exista y el pedido no cambie nada: si hace falta, quitala con DELETE, que funciona en cualquier estado. Los inactivos sí, igual que en el panel.

Quitar de un sitio ​

DELETE /api/v1/employees/:id/sites/:site_id quita al empleado del sitio y responde 204, sin cuerpo. Exige el encabezado Idempotency-Key. Si el empleado no estaba asignado a ese sitio, también responde 204: el resultado es el mismo.

Quitar a alguien de un sitio no borra nada de su historial: sus entregas de EPP, certificados y documentos firmados en ese sitio se conservan y se siguen leyendo, por ejemplo en las entregas de EPP. Los documentos que tenía pendientes de tomar conocimiento en el sitio dejan de corresponderle, igual que al quitarlo desde el panel. Funciona con el empleado y el sitio en cualquier estado.

Errores de escritura ​

SituaciónRespuesta
Falta un campo obligatorio, o un campo tiene un tipo o un valor inválido422 invalid_parameter, con el campo en el mensaje.
legal_entity_id no es una razón social de esta cuenta422 invalid_parameter.
legal_entity_id es una razón social fusionada422 legal_entity_merged, con survivor_id: la razón social vigente que la reemplaza.
El DNI de un alta, o el DNI nuevo en un PATCH, es de un empleado dado de baja422 employee_deactivated, con employee_id.
Se asigna a un sitio, o se le cambia el puesto, a un empleado dado de baja422 employee_deactivated, con su employee_id.
Se asigna a un sitio archivado (status: deleted), o se cambia un puesto en él422 site_deactivated, con site_id.
position_id no es un puesto de ese sitio422 invalid_parameter, con position_id en el mensaje.
El empleado o el sitio de la ruta no existen en esta cuenta404 not_found.

Una escritura que responde un error no guarda nada.

Qué mueve updated_at ​

Además de cualquier cambio en los datos del propio empleado, su updated_at cambia cuando:

  • se lo asigna a un sitio o se lo quita de uno;
  • cambia su puesto en un sitio, o se elimina el puesto que ocupaba;
  • su razón social empleadora se fusiona con otra.

Así, updated_since alcanza para enterarse de todo lo que cambió en sites y en legal_entity_id. Un cambio de nombre del sitio, del puesto o de la razón social no lo mueve, porque el empleado solo trae sus identificadores.

Razones sociales ​

GET /api/v1/legal_entities
GET /api/v1/legal_entities/:id
PATCH /api/v1/legal_entities/:id

Permisos: legal_entities:read para leer, legal_entities:write para leer y modificar.

Las razones sociales de la cuenta: las empresas responsables de sus sitios, las contratistas y los empleadores de su personal. Sirve, por ejemplo, para que tu sistema asocie cada empresa propia con la de Safety Panel antes de cargar empleados.

El listado se pagina y acepta los filtros updated_since, external_reference, tax_id y merged (ver abajo). Las razones sociales no tienen estado, así que no aceptan status. Una razón social pedida por su id se devuelve siempre, aunque se haya fusionado.

json
{
  "id": 7,
  "name": "Metalúrgica Norte SA",
  "tax_id": "30-71234567-8",
  "economic_activities": [
    { "code": "251101", "name": "Fabricación de carpintería metálica" }
  ],
  "merged_into_id": null,
  "merged_at": null,
  "external_reference": "PROV-118",
  "external_metadata": { "cuenta_contable": "2.1.04" },
  "created_at": "2026-10-01T12:00:00Z",
  "updated_at": "2026-10-15T09:41:27Z"
}
CampoTipoQué contiene
identeroIdentificador de la razón social. Es el que aparece en responsible_entities de los sitios.
nametextoNombre de la razón social.
tax_idtexto o nullEl identificador fiscal, o null si no lo tiene. En Argentina es el CUIT, siempre con guiones.
economic_activitieslista de objetosSus actividades económicas, ordenadas por código, cada una con su code y su name. Una lista vacía si no tiene ninguna.
merged_into_identero o nullSi se fusionó, la razón social que la absorbió (ver abajo). null si sigue vigente.
merged_atinstante o nullCuándo se fusionó.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

id, name, tax_id y economic_activities tienen exactamente la misma forma que cada objeto de responsible_entities en los sitios, así que una razón social se lee igual en los dos recursos.

Buscar por identificador fiscal ​

tax_id devuelve la razón social con ese identificador fiscal. En Argentina, el CUIT se puede escribir con o sin guiones: 30712345678 encuentra 30-71234567-8. Un identificador fiscal pertenece a una sola razón social de la cuenta, así que la respuesta trae una o ninguna. Un tax_id vacío no encuentra ninguna.

Fusiones ​

Cuando la misma empresa quedó cargada dos veces, el panel permite fusionarlas: una queda y absorbe a la otra. La absorbida no se borra. Se conserva con merged_into_id apuntando a la que la absorbió y con la fecha en merged_at.

  • El listado devuelve por defecto solo las razones sociales vigentes, las mismas que muestra el panel.
  • merged=true devuelve solo las fusionadas y merged=false solo las vigentes. Otro valor responde 422.
  • Una búsqueda por external_reference o por tax_id sin merged devuelve también las fusionadas. Así, si tu sistema había asociado una razón social que después se fusionó, la encuentra y sabe cuál la reemplaza.
  • Al fusionar, el identificador fiscal pasa a la que queda. Por eso una búsqueda por el identificador fiscal de una absorbida devuelve la razón social que la absorbió.

merged_into_id apunta a la razón social que absorbió a esta, en el momento de la fusión. Si esa también se fusiona más adelante, su propio merged_into_id apunta a la siguiente: para llegar a la vigente, pedí GET /legal_entities/:id con cada merged_into_id hasta que venga en null.

Los empleados y los sitios de una absorbida pasan a la que queda, así que nunca apuntan a una razón social fusionada.

Qué mueve updated_at ​

El updated_at de una razón social cambia cuando:

  • cambia su nombre o su identificador fiscal;
  • se agregan o se quitan actividades económicas, también cuando las recibe al absorber a otra en una fusión;
  • se fusiona en otra;
  • se modifican sus campos externos.

Para enterarte de las fusiones al sincronizar, pedí también merged=true junto con updated_since.

Vincularla a un sitio o asignarle empleados no cambia su updated_at: esos vínculos están en los sitios (responsible_entities) y en los empleados (legal_entity_id).

Entregas de EPP ​

GET   /api/v1/ppe_deliveries
GET   /api/v1/ppe_deliveries/:id
POST  /api/v1/ppe_deliveries
PATCH /api/v1/ppe_deliveries/:id

Permisos: ppe_deliveries:read para leer, ppe_deliveries:write para crear, modificar y cancelar.

Las entregas de EPP de la cuenta, con lo que el empleado firmó, sus devoluciones y la constancia en PDF. Es el recurso que un ERP lee para descontar stock, imputar costos y archivar la constancia en el legajo, y el que usa para registrar lo que despachó y que el empleado lo firme en Safety Panel.

Las entregas se leen aunque el módulo de EPP esté apagado: son registros que se conservan.

El listado se pagina y acepta los filtros updated_since y external_reference, más estos:

FiltroDevuelve
statusLas entregas en ese estado: draft, ready_to_sign, signed o cancelled. Sin este filtro, el listado trae todos los estados, canceladas incluidas.
employee_idLas entregas de ese empleado.
site_idLas entregas de ese sitio.
signed_sinceLas entregas firmadas en ese instante o después. Se escribe igual que updated_since.

Un employee_id o un site_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422.

json
{
  "id": 412,
  "status": "signed",
  "employee_id": 81,
  "site_id": 12,
  "device_id": 3,
  "delivery_date": "2026-10-20",
  "observations": null,
  "delivery_address": "Av. Siempreviva 742",
  "delivery_city": "Martínez",
  "delivery_state": "Buenos Aires",
  "delivery_postal_code": "1640",
  "signed_at": "2026-10-20T13:05:11Z",
  "cancelled_at": null,
  "cancel_reason": null,
  "employer_name": "Limpieza Integral S.A.",
  "employer_cuit": "30-12345678-9",
  "signed_content_digest": "9f2c…e41a",
  "signature_verification": { "method": "email", "verified_at": "2026-10-20T13:04:50Z" },
  "verification_url": "https://safetypanel.com.ar/verify/Xk3…",
  "constancia_pdf": {
    "url": "https://<subdominio>.safetypanel.com.ar/rails/active_storage/blobs/redirect/…/constancia.pdf?disposition=attachment",
    "expires_at": "2026-10-21T15:05:00Z"
  },
  "items": [
    {
      "id": 901,
      "ppe_product_id": 55,
      "ppe_category_id": 7,
      "product_name": "Guantes de nitrilo",
      "brand": "Ansell",
      "product_model": "Sol-Vex 37-675",
      "certified": true,
      "quantity": 2,
      "delivery_reason": "initial",
      "returned_quantity": 1,
      "returns": [
        { "id": 33, "quantity": 1, "returned_at": "2026-10-25T18:20:00Z", "reason": "Rotura" }
      ]
    }
  ],
  "api_key_id": 4,
  "external_reference": "REM-0001-00012345",
  "external_metadata": { "deposito": "Central" },
  "created_at": "2026-10-20T12:40:02Z",
  "updated_at": "2026-10-25T18:20:00Z"
}
CampoTipoQué contiene
identeroIdentificador de la entrega.
statustextodraft, ready_to_sign, signed o cancelled (ver abajo).
employee_identeroEl empleado que recibe los elementos.
site_identero o nullEl sitio de la entrega. Es null solo en entregas antiguas, anteriores a que la entrega nombrara su sitio.
device_identero o nullEl tótem en el que se firmó, o null si se firmó en el portal del empleado.
delivery_datefechaLa fecha de entrega cargada, sin hora.
observationstexto o nullLas observaciones que el empleado lee antes de firmar y que se imprimen en la constancia.
delivery_address, delivery_city, delivery_state, delivery_postal_codetexto o nullEl domicilio donde se entregaron los elementos, el que figura en la constancia.
signed_atinstante o nullCuándo la firmó el empleado.
cancelled_at, cancel_reasoninstante y texto, o nullCuándo se canceló y con qué motivo.
employer_name, employer_cuittexto o nullEl empleador que figura en la constancia, tomado al marcar la entrega lista para firmar.
signed_content_digesttexto o nullLa huella del contenido firmado, la misma que se imprime en la constancia. null antes de la firma y en firmas anteriores a la huella.
signature_verificationobjeto o nullSi la firma se confirmó con un código: method (email) y verified_at, cuándo se aceptó el código. null si la firma no llevó código.
verification_urltexto o nullLa página pública de verificación, la misma del código QR de la constancia. null antes de la firma.
constancia_pdfobjeto o nullEl enlace para descargar la constancia (ver abajo). null mientras no exista.
itemslista de objetosLos elementos entregados, ordenados por id (ver abajo).
api_key_identero o nullLa key de API que creó la entrega. null si se registró en el panel.
external_reference, external_metadataLos campos externos de tu sistema, por ejemplo el número de remito.
created_at, updated_atinstanteCuándo se registró y cuándo cambió por última vez.

La firma dibujada del empleado no se expone nunca.

Los elementos ​

Cada elemento trae lo que el empleado firmó, copiado del catálogo al registrar la entrega, y los identificadores del catálogo para que tu sistema lo asocie con su propio artículo:

CampoTipoQué contiene
identeroIdentificador del elemento dentro de la entrega.
ppe_product_id, ppe_category_identero o nullEl producto y la categoría del catálogo. null si el elemento se cargó a mano, sin elegirlo del catálogo.
product_name, brand, product_model, certifiedtexto y booleanoProducto, marca, modelo y si está certificado, tal como se firmaron. Si el catálogo cambia después, estos valores no cambian.
quantityenteroCantidad entregada.
delivery_reasontextoinitial (entrega inicial), replacement_wear (reposición por desgaste), replacement_damage (reposición por rotura), replacement_loss (reposición por extravío) o position_change (cambio de puesto).
returned_quantityenteroCuántos se devolvieron en total.
returnslista de objetosCada devolución, de la más antigua a la más nueva: id, quantity, returned_at y reason (texto o null).

La constancia en PDF ​

constancia_pdf.url descarga el PDF sin key y sin sesión, así que es temporal: deja de aceptarse a los 5 minutos, en el instante que indica constancia_pdf.expires_at. Abrirlo antes de ese instante redirige al archivo con otro enlace que también vence en pocos minutos. Descargalo en ese momento y guardalo en tu sistema; si necesitás el enlace de nuevo, volvé a pedir la entrega.

La constancia es la evidencia firmada: muestra el nombre y el DNI del empleado y su firma dibujada. Guardala en tu sistema como un documento confidencial, con acceso restringido a quien la necesita.

La constancia se genera unos segundos después de la firma. Hasta entonces constancia_pdf viene en null, y su llegada mueve el updated_at de la entrega (ver abajo). Las entregas que no están firmadas no tienen constancia.

Estados ​

statusQué significa
draftBorrador: recién registrada, todavía se edita.
ready_to_signLista para firmar: el empleado la ve en su portal y puede firmarla.
signedFirmada por el empleado. Ya no cambia, salvo por las devoluciones.
cancelledCancelada antes de la firma, con su motivo.

Solo una entrega signed es evidencia de que el empleado recibió los elementos. Una entrega draft o ready_to_sign todavía puede cambiar o cancelarse: no la tomes como entregada ni descuentes stock por ella. Ver los estados de una entrega.

Crear una entrega ​

POST /api/v1/ppe_deliveries registra lo que tu sistema despachó para que el empleado lo firme en Safety Panel, en el tótem o en su portal. Exige el encabezado Idempotency-Key: si la llamada se corta, reintentala con la misma clave y la entrega no se crea dos veces.

sh
curl -X POST "https://tuempresa.safetypanel.com.ar/api/v1/ppe_deliveries" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c1e2f4a-6b3d-4a5e-9f0c-7d2b1a3e5c48" \
  -d '{"employee_id": 81, "site_id": 12, "status": "ready_to_sign", "external_reference": "REM-0001-00012345",
       "items": [{"external_reference": "GUA-NIT-09", "quantity": 2, "delivery_reason": "initial"}]}'
CampoObligatorioQué acepta
employee_idSíUn empleado de la cuenta, asignado al sitio.
site_idSíUn sitio de la cuenta con las entregas de EPP habilitadas.
itemsSíAl menos un elemento (ver abajo).
statusNodraft (por defecto) o ready_to_sign.
delivery_dateNoFecha AAAA-MM-DD. Si no se envía, la de hoy en la zona horaria de la cuenta.
delivery_address, delivery_city, delivery_state, delivery_postal_codeNoTexto. Si no se envían, se toman del sitio, igual que en el panel. Si el sitio no tiene dirección cargada, envialos.
observationsNoTexto que el empleado lee antes de firmar.
external_reference, external_metadataNoLos campos externos. Guardá ahí el número de remito o de despacho de tu sistema al crearla: es lo que te permite encontrarla después con el filtro external_reference.

Cada elemento de items nombra un producto del catálogo habilitado en el sitio, de una de dos formas, nunca las dos:

CampoQué acepta
ppe_product_idEl id del producto en Safety Panel.
external_referenceEl código del producto en tu sistema (su external_reference en el catálogo). Tiene que coincidir con un solo producto.
quantityObligatorio. Entero, al menos 1.
delivery_reasonObligatorio. initial, replacement_wear, replacement_damage, replacement_loss o position_change.
notesOpcional. Texto.

Producto, marca, modelo y certificación se copian del catálogo, igual que al elegir el producto en el panel.

  • draft deja la entrega en borrador: todavía se puede modificar.
  • ready_to_sign la deja lista para firmar en el mismo paso, con los mismos controles que en el panel: por ejemplo, cada elemento necesita producto, marca y modelo. Si alguno no se cumple, responde 422 y no se crea nada, ni siquiera el borrador. Ya lista, el empleado la ve en su portal y en el tótem, igual que una cargada en el panel.
  • La firma ocurre siempre en Safety Panel. Un status signed o cancelled responde 422.

Responde 201 con la entrega, igual que GET, y su dirección en el encabezado Location. En el panel, la entrega muestra en Registrado por el nombre de la key que la creó, y api_key_id dice cuál fue. Al firmarse descuenta el stock igual que cualquier otra entrega: ver Quién descuenta.

Modificar o cancelar una entrega ​

PATCH /api/v1/ppe_deliveries/:id cambia los campos que se envíen y responde 200 con la entrega. Lo que se puede cambiar depende de su estado:

EstadoQué admite
draftLos campos del alta salvo employee_id y site_id. Un items reemplaza todos los elementos. status: ready_to_sign la deja lista para firmar; status: cancelled la cancela.
ready_to_signSolo status: cancelled y los campos externos. Para corregir un elemento, cancelala y creá otra.
signed, cancelledNada, ni siquiera los campos externos: responde 409 con el código ppe_delivery_not_editable.
  • Cancelar se hace con {"status": "cancelled", "cancel_reason": "…"}. El motivo es obligatorio, igual que en el panel. cancel_reason sin status: cancelled responde 422.
  • El empleado y el sitio no se cambian: para otra persona u otro sitio, cancelá la entrega y creá otra.
  • Un PATCH que envía status exige el encabezado Idempotency-Key, porque lo que provoca (aparecer para firmar, cancelarse) llega al empleado. Uno que solo edita campos o elementos de un borrador lo acepta, pero no lo exige.
  • El 409 trae status, el estado en el que está la entrega, para que tu sistema sepa si ya se firmó o se canceló.

Una entrega nunca se borra por la API: se cancela.

Errores al crear o modificar una entrega ​

SituaciónRespuesta
Falta un campo obligatorio, o un campo tiene un tipo o un valor inválido422 invalid_parameter. El mensaje nombra el campo, y para un elemento su posición: items[1].quantity.
employee_id, site_id o un ppe_product_id no existen en esta cuenta422 invalid_parameter, con el campo en el mensaje.
El código de un elemento está vacío o no coincide con ningún producto422 invalid_parameter, con el elemento en el mensaje.
El código de un elemento coincide con varios productos422 ambiguous_external_reference, con matching_ids: los productos que lo comparten. Nombrá el elemento con ppe_product_id, o corregí el código en tu catálogo.
Un producto no está habilitado en el sitio, o el empleado no está asignado al sitio422 invalid_parameter.
El empleado está dado de baja422 employee_deactivated, con employee_id.
El sitio está archivado422 site_deactivated, con site_id.
La cuenta o el sitio no tienen el módulo de EPP habilitado403 module_disabled. En un sitio que lo apagó, una entrega abierta todavía se puede cancelar, con un PATCH que solo envíe status y cancel_reason.
La entrega ya está firmada o cancelada, o se edita una lista para firmar409 ppe_delivery_not_editable, con status.
La entrega de la ruta no existe en esta cuenta404 not_found.

Una escritura que responde un error no guarda nada. En un PATCH, el estado de la entrega se revisa primero: una entrega firmada o cancelada responde 409 aunque su sitio tenga el EPP apagado o el pedido traiga otros errores.

Qué mueve updated_at ​

El updated_at de una entrega cambia cuando:

  • cambia un dato de la propia entrega mientras es borrador (la fecha, la dirección, las observaciones), o pasa a lista para firmar;
  • cambian sus campos externos mientras no está firmada ni cancelada;
  • el empleado la firma, o se cancela;
  • se genera su constancia en PDF;
  • se registra una devolución de cualquiera de sus elementos.

Así, updated_since alcanza para enterarse de las firmas, las cancelaciones, las constancias nuevas y las devoluciones.

Editar solo los elementos de un borrador no mueve su updated_at. Los elementos quedan fijos al pasar a lista para firmar, y ese cambio sí lo mueve: a partir de ahí, lo que trae la entrega es lo que se va a firmar.

Puestos ​

GET /api/v1/positions
GET /api/v1/positions/:id
PATCH /api/v1/positions/:id

Permisos: positions:read para leer, positions:write para leer y modificar.

Los puestos de cada sitio, con las categorías de EPP que exigen. Es el recurso con el que un ERP asocia sus códigos de puesto con los de Safety Panel. Un puesto pertenece a un solo sitio: el mismo puesto en dos sitios son dos registros, cada uno con su id. El catálogo de puestos de la cuenta no se expone, solo los puestos de los sitios.

El listado se pagina y acepta los filtros updated_since y external_reference, más este:

FiltroDevuelve
site_idLos puestos de ese sitio. Un sitio que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422.

Los puestos no tienen estado, así que no aceptan status. El listado incluye los puestos de los sitios en cualquier estado: el estado de cada sitio está en los sitios.

json
{
  "id": 30,
  "name": "Soldador",
  "site_id": 12,
  "sector": {
    "id": 4,
    "name": "Mantenimiento",
    "area": { "id": 2, "name": "Planta" }
  },
  "position_template_id": 9,
  "required_ppe_categories": [
    { "id": 3, "name": "Careta de soldar" },
    { "id": 5, "name": "Guantes de cuero" }
  ],
  "external_reference": "PU-SOLD",
  "external_metadata": { "convenio": "UOM" },
  "created_at": "2026-05-04T13:00:00Z",
  "updated_at": "2026-10-18T10:12:45Z"
}
CampoTipoQué contiene
identeroIdentificador del puesto. Es el position_id que aparece en sites de los empleados.
nametextoNombre del puesto.
site_identeroEl sitio al que pertenece.
sectorobjeto o nullEl sector del puesto, con su id, su name y su area (id y name). null si el puesto no tiene sector, y siempre null en las cuentas de consultora (ver abajo).
position_template_identero o nullEl puesto del catálogo del que se copió, o null si se creó directamente en el sitio.
required_ppe_categorieslista de objetosLas categorías de EPP que el puesto exige, ordenadas por nombre, cada una con su id y su name. Una lista vacía si no exige ninguna.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

required_ppe_categories viene aunque la cuenta no tenga habilitada la entrega de EPP. Las capacitaciones que exige el puesto no se exponen.

Áreas y sectores ​

En las cuentas de empresa, los puestos se ordenan con la estructura organizacional: áreas que agrupan sectores. Las consultoras no usan áreas ni sectores en los puestos de un cliente: las suyas describen a la propia consultora, no a la empresa del sitio. Por eso, en una cuenta de consultora, sector viene siempre en null, igual que el panel no lo muestra.

Qué mueve updated_at ​

Además de cualquier cambio en los datos del propio puesto, su updated_at cambia cuando:

  • se agrega o se quita una categoría de EPP exigida;
  • cambia el nombre de una de sus categorías de EPP;
  • cambia el nombre de su sector, o el sector pasa a otra área;
  • cambia el nombre del área de su sector;
  • se elimina su sector o el área de su sector, y el puesto queda sin sector;
  • se modifican sus campos externos.

Así, updated_since alcanza para enterarse de todo lo que cambió en sector y en required_ppe_categories.

Un puesto eliminado en el panel deja de aparecer en la API. Los empleados que lo ocupaban quedan sin puesto en ese sitio: su position_id pasa a null y su updated_at cambia, así que una sincronización con updated_since sobre los empleados se entera. Para saber qué puestos se eliminaron, compará con una lectura completa.

Categorías de EPP ​

GET /api/v1/ppe_categories
GET /api/v1/ppe_categories/:id

Permisos: ppe_categories:read. Es un recurso de solo lectura.

Las categorías del catálogo de EPP de la cuenta, como "Casco" o "Guantes de nitrilo". Son las que pide el EPP requerido de cada puesto, por eso se crean y se editan en el panel, no por la API. Un ERP las lee para asignarle a cada producto su ppe_category_id.

El listado se pagina y acepta el filtro updated_since. Las categorías se leen aunque el módulo de EPP esté apagado.

json
{
  "id": 7,
  "name": "Guantes de nitrilo",
  "created_at": "2026-03-10T14:00:00Z",
  "updated_at": "2026-03-10T14:00:00Z"
}
CampoTipoQué contiene
identeroIdentificador de la categoría.
nametextoNombre de la categoría. Es único en la cuenta.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

Productos de EPP ​

GET    /api/v1/ppe_products
GET    /api/v1/ppe_products/:id
POST   /api/v1/ppe_products
PATCH  /api/v1/ppe_products/:id
PUT    /api/v1/ppe_products/:id/sites/:site_id
DELETE /api/v1/ppe_products/:id/sites/:site_id

Permisos: ppe_products:read para leer, ppe_products:write para leer, crear, modificar y habilitar en sitios.

Los productos del catálogo de EPP de la cuenta, con los sitios donde están habilitados. Es el recurso con el que un ERP que ya tiene el catálogo maestro lo carga en Safety Panel y lo mantiene al día, y con el que traduce cada producto a su propio código.

El listado se pagina y acepta los filtros updated_since y external_reference, más estos:

FiltroDevuelve
ppe_category_idLos productos de esa categoría.
site_idLos productos habilitados en ese sitio.

Un ppe_category_id o un site_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422. Los productos no tienen estado, así que no aceptan status.

json
{
  "id": 55,
  "name": "Guantes de nitrilo talle 9",
  "brand": "Ansell",
  "model": "TouchNTuff 92-600",
  "certified": true,
  "ppe_category_id": 7,
  "site_ids": [12, 14],
  "external_reference": "GUA-NIT-09",
  "external_metadata": { "unit": "par" },
  "created_at": "2026-03-10T14:05:00Z",
  "updated_at": "2026-10-20T15:42:10Z"
}
CampoTipoQué contiene
identeroIdentificador del producto. Es el único identificador que acepta /ppe_products/:id.
nametextoNombre del producto. Es único en la cuenta.
brand, modeltexto o nullMarca y modelo.
certifiedbooleanoSi el producto posee certificación.
ppe_category_identero o nullSu categoría. Un producto sin categoría se puede entregar, pero no cubre ningún EPP requerido.
site_idslista de enterosLos sitios donde está habilitado, ordenados. Es una lista vacía si no está habilitado en ninguno.
external_reference, external_metadatatexto o null, objetoLos campos externos de tu sistema. En un ERP, la referencia suele ser el código (SKU) del producto.
created_at, updated_atinstanteCuándo se creó y cuándo cambió por última vez.

La foto del producto no se lee ni se carga por la API: se carga en el panel.

Buscar un producto por su código ​

GET /api/v1/ppe_products?external_reference=GUA-NIT-09 devuelve los productos con ese código. Safety Panel no exige que el código sea único, igual que en todos los recursos: si tu ERP le dio el mismo código a dos productos, la búsqueda devuelve los dos, en lugar de elegir uno en silencio. Corregí el código de uno de ellos con PATCH, o usá el id.

Crear y modificar un producto ​

POST crea un producto y PATCH modifica uno existente. Los dos aceptan los mismos campos en JSON:

CampoTipo
nametextoObligatorio al crear. No puede repetir el de otro producto de la cuenta.
brand, modeltexto o null
certifiedtrue o falsePor defecto, false.
ppe_category_identero o nullUna categoría de la cuenta.
external_reference, external_metadataSe escriben como en todos los campos externos.
sh
curl -X POST "https://tuempresa.safetypanel.com.ar/api/v1/ppe_products" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0b8e5f3c-1d2a-4c6b-9e7f-5a4d3c2b1a09" \
  -d '{"name": "Guantes de nitrilo talle 9", "brand": "Ansell", "ppe_category_id": 7, "external_reference": "GUA-NIT-09"}'
  • POST exige el encabezado Idempotency-Key, así un reintento nunca crea el producto dos veces. Responde 201 con el producto y su dirección en el encabezado Location.
  • PATCH modifica solo los campos que se envían y responde 200 con el producto. Acepta Idempotency-Key sin exigirlo.
  • Un campo que no está en la tabla, como site_ids o una foto, responde 422. Un valor de otro tipo también: certified es true o false, no "sí", y ppe_category_id es un número, no un texto.
  • Un nombre vacío o repetido, o una categoría que no existe en la cuenta, responde 422 con el código invalid_parameter y un mensaje que nombra el campo. No se escribe nada.
  • Escribir en el catálogo requiere el módulo de EPP habilitado. Si está apagado, la escritura responde 403 con el código module_disabled. La lectura sigue funcionando.

Un producto nunca se borra por la API, tenga o no entregas. Si deja de usarse, deshabilitalo en sus sitios.

Habilitar un producto en un sitio ​

Un producto se entrega solo en los sitios donde está habilitado. Por la API se habilita y se deshabilita de a un sitio:

LlamadaQué haceResponde
PUT /api/v1/ppe_products/:id/sites/:site_idHabilita el producto en el sitio.200 con el producto.
DELETE /api/v1/ppe_products/:id/sites/:site_idLo deshabilita en el sitio.204, sin cuerpo.

Las dos se pueden repetir sin efecto: habilitar un producto ya habilitado responde 200 igual, y deshabilitar uno que no está habilitado responde 204. Aceptan Idempotency-Key sin exigirlo.

Deshabilitar un producto en un sitio no borra nada: su stock en el sitio y sus entregas se conservan y reaparecen si se lo vuelve a habilitar, igual que al quitarlo en el panel.

Un producto o un sitio que no existe en la cuenta responde 404. En un sitio con las entregas de EPP deshabilitadas, habilitar responde 403 con el código module_disabled; deshabilitar sigue funcionando, para quitar lo que quedó habilitado.

Qué mueve updated_at ​

Además de cualquier cambio en los datos del propio producto, su updated_at cambia cuando se lo habilita o se lo deshabilita en un sitio. Así, updated_since alcanza para enterarse de todo lo que cambió en site_ids. Un cambio de nombre de la categoría no lo mueve, porque el producto solo trae su identificador.

Constancias de capacitación ​

GET /api/v1/certifications
GET /api/v1/certifications/:id
GET /api/v1/certifications/:id/certificate

Permisos: certifications:read. Es un recurso de solo lectura.

Las constancias de las capacitaciones e-learning: quién hizo qué curso, en qué sitio, si sigue vigente y hasta cuándo. Es el recurso con el que un ERP o un sistema de RRHH sabe quién está habilitado para entrar a una planta y a quién le está por vencer una capacitación.

Una constancia puede ser de un empleado, de un profesional o de un visitante, y también de un administrador o de un representante del cliente que hizo el curso. En el JSON, de la persona solo se exponen su identificador y su tipo, nunca su nombre ni su documento: los datos de empleados y profesionales se leen en sus propios recursos, y las demás personas no se exponen.

El listado se pagina y acepta el filtro updated_since, más estos:

FiltroDevuelve
statusLas constancias en ese estado: active, cancelled, expired o pending_verification. Sin este filtro, el listado trae todos los estados, vencidas y anuladas incluidas.
user_idLas constancias de esa persona. Para un empleado, es el id de los empleados.
user_typeLas constancias de ese tipo de persona: employee, professional, visitor, admin o client_representative.
site_idLas constancias de ese sitio.
expires_beforeLas constancias que vencen antes de esa fecha, en formato AAAA-MM-DD. Las que no vencen nunca no aparecen. Combinado con status=active, son las que están por vencer.

Un user_id o un site_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422.

json
{
  "id": 5120,
  "user_id": 81,
  "user_type": "employee",
  "training_id": 14,
  "training_title": "Uso de extintores",
  "site_id": 12,
  "device_id": null,
  "status": "active",
  "issued_on": "2026-10-20",
  "expiration_date": "2027-10-20",
  "trainer_name": "Ana Gómez",
  "modality": { "presence": "virtual", "timing": "asynchronous", "assistance": "unassisted" },
  "signed_content_digest": "4b1d…9a07",
  "signature_verification": { "method": "email", "verified_at": "2026-10-20T13:04:50Z" },
  "certificate_pdf_url": "https://<subdominio>.safetypanel.com.ar/api/v1/certifications/5120/certificate",
  "created_at": "2026-10-20T13:05:11Z",
  "updated_at": "2026-10-20T13:05:11Z"
}
CampoTipoQué contiene
identeroIdentificador de la constancia.
user_identeroLa persona que hizo el curso.
user_typetextoQué es esa persona: employee (un empleado), professional (un profesional), visitor (un visitante), admin o client_representative.
training_id, training_titleentero y textoLa capacitación y su título actual.
site_identero o nullEl sitio para el que se hizo. null si se hizo sin sitio.
device_identero o nullEl tótem en el que se firmó, o null si se firmó en un portal.
statustextoactive, cancelled, expired o pending_verification (ver abajo).
issued_onfechaEl día en que se hizo, el mismo que imprime el certificado, en la zona horaria de la cuenta.
expiration_datefecha o nullHasta qué día es válida, según la vigencia del certificado de la capacitación. null si no vence.
trainer_nametexto o nullEl capacitador del curso, tal como figuraba al firmar: el nombre de un usuario de la cuenta o de un capacitador externo. Cambiar después el capacitador del curso no lo modifica. null si el curso no tenía capacitador o la constancia es anterior a este dato.
modalityobjeto o nullLa modalidad de la capacitación, en sus tres ejes: presence (virtual o in_person), timing (asynchronous o synchronous) y assistance (unassisted o assisted). Un curso hecho en el portal o en el tótem es virtual, asynchronous, unassisted. null en constancias anteriores a este dato.
signed_content_digesttexto o nullLa huella del contenido firmado, la misma que se imprime en el certificado. null en firmas anteriores a la huella.
signature_verificationobjeto o nullSi la firma se confirmó con un código: method (email) y verified_at, cuándo se aceptó el código. null si la firma no llevó código o todavía no se confirmó.
certificate_pdf_urltexto o nullDónde descargar el certificado en PDF (ver abajo). null si la persona no es un empleado ni un profesional, y mientras la constancia está pending_verification.
created_at, updated_atinstanteCuándo se firmó y cuándo cambió por última vez.

El JSON no trae nunca la firma dibujada de la persona.

El certificado en PDF ​

GET /api/v1/certifications/:id/certificate devuelve el certificado como archivo PDF (Content-Type: application/pdf), el mismo que se descarga desde el panel. Como ese certificado, muestra el nombre de la persona, su firma dibujada y, si firmó con código, cuándo se aceptó y desde qué dirección IP. Quien tiene una key con certifications:read puede leer esos datos de los empleados y profesionales con constancia, aunque la key no tenga permiso sobre empleados ni profesionales.

El certificado es la evidencia firmada, por eso trae esos datos tal como los imprime el panel. Guardalo en tu sistema como un documento confidencial, con acceso restringido a quien lo necesita.

A diferencia de la constancia de una entrega de EPP, este enlace pide la key en el encabezado Authorization, con el mismo permiso certifications:read, y no vence. El certificado no se guarda como archivo: se arma en el momento a partir de la constancia, así que no hay un archivo al que dar un enlace temporal sin key. Cada descarga cuenta como una llamada dentro del límite de uso de la key y, además, dentro de un cupo propio de 30 descargas de certificados por minuto: cada certificado se imprime en el momento.

Solo se descargan los certificados de empleados y profesionales, las personas que la API ya identifica. Para cualquier otra persona (visitantes, administradores, representantes del cliente), y para las constancias pending_verification, la descarga responde 404 con el código certificate_unavailable: su certificado mostraría un nombre que la API no expone, y una constancia pendiente todavía no tiene la firma confirmada.

Estados ​

statusQué significa
activeEn vigencia: la persona está capacitada.
pending_verificationPendiente de validación: firmó, pero falta confirmar la firma con el código que le llegó por mail. Todavía no la cuentes como capacitada.
expiredVencida: pasó su expiration_date.
cancelledAnulada por un administrador. Ya no cuenta como capacitación.

Una constancia pasa a expired por un proceso automático que corre cada hora: el día siguiente a su expiration_date, dentro de la primera hora después de la medianoche en la zona horaria de la cuenta. En ese lapso puede figurar active con una expiration_date ya pasada; si necesitás la respuesta exacta, compará expiration_date con la fecha de hoy en esa zona. Ver los estados de una constancia.

Qué mueve updated_at ​

El updated_at de una constancia cambia cuando:

  • se confirma la firma con el código y pasa de pending_verification a active;
  • pasa a expired, por el proceso automático o porque un administrador la marcó vencida;
  • un administrador la anula.

Así, updated_since alcanza para enterarse de las constancias nuevas, los vencimientos y las anulaciones. Cambiar el título de la capacitación no mueve el updated_at de sus constancias.

Registros de capacitación ​

GET /api/v1/training_records
GET /api/v1/training_records/:id

Permisos: training_records:read. Es un recurso de solo lectura.

Los registros presenciales: la evidencia de una capacitación dictada en persona en un sitio, con quiénes asistieron.

El listado se pagina y acepta el filtro updated_since, más estos:

FiltroDevuelve
site_idLos registros de ese sitio.
user_idLos registros a los que asistió esa persona. Para un empleado, es el id de los empleados.

Un site_id o un user_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422. Los registros no tienen estado, así que no aceptan status.

json
{
  "id": 77,
  "site_id": 12,
  "date": "2026-10-15",
  "start_time": "09:00",
  "end_time": "12:00",
  "time_zone": "America/Argentina/Buenos_Aires",
  "description": "Protección contra incendios y uso de EPP",
  "people_trained": 18,
  "trainer_name": "Ana Gómez",
  "modality": { "presence": "in_person", "timing": "synchronous", "assistance": "assisted" },
  "voided_at": null,
  "void_reason": null,
  "attendees": [
    { "user_id": 81, "user_type": "employee", "confirmation": "confirmed", "answered_at": "2026-10-16T11:05:00Z" },
    { "user_id": 95, "user_type": "employee", "confirmation": "pending", "answered_at": null }
  ],
  "created_at": "2026-10-15T16:20:00Z",
  "updated_at": "2026-10-15T16:20:00Z"
}
CampoTipoQué contiene
identeroIdentificador del registro.
site_identeroEl sitio donde se dictó.
datefechaEl día de la sesión.
start_time, end_timetextoLa hora de inicio y de fin del día date, HH:MM, tal como se cargaron en el panel. Son horas locales de la cuenta, no instantes en UTC (ver Fechas y horas).
time_zonetextoLa zona horaria de la cuenta en formato IANA, por ejemplo America/Argentina/Buenos_Aires. Con date, start_time y time_zone se obtiene el instante exacto de la sesión. Es la misma zona que GET /account, que la nombra como el panel (Buenos Aires).
descriptiontextoLo que se dictó.
people_trainedentero o nullCuántas personas se capacitaron, según lo cargado. Puede ser mayor que la cantidad de attendees.
trainer_nametexto o nullQuién dictó la sesión: el nombre de un usuario de la cuenta o de un capacitador externo. null si no se cargó.
modalityobjetoLa modalidad, con los mismos tres ejes que en las constancias. Un registro presencial es siempre in_person, synchronous, assisted.
voided_at, void_reasoninstante y texto, o nullCuándo se anuló y con qué motivo (ver abajo).
attendeeslista de objetosLos asistentes identificados que siguen en el registro, ordenados por user_id, cada uno con su user_id, su user_type (los mismos valores que en las constancias), su confirmation y su answered_at. Nunca su nombre ni su documento.
confirmationtextoLa respuesta del asistente desde su portal: pending mientras no respondió, confirmed si confirmó con su firma que estuvo, declined si respondió «No estuve». Un asistente cuenta recién cuando es confirmed.
answered_atinstante o nullCuándo respondió. null mientras está pendiente.
created_at, updated_atinstanteCuándo se registró y cuándo cambió por última vez.

El archivo de evidencia y las categorías del registro no se exponen.

Registros anulados ​

Un registro no se borra: si se cargó por error, se anula. El listado trae los anulados junto con los demás. Un registro anulado tiene voided_at con el instante de la anulación y void_reason con el motivo; uno vigente tiene los dos en null. Un registro anulado ya no es evidencia de la capacitación: no lo cuentes.

Qué mueve updated_at ​

El updated_at de un registro cambia cuando se edita, cuando se anula y cuando se le agrega o se le quita un asistente. Así, updated_since alcanza para enterarse de las anulaciones.

Stock de EPP ​

GET /api/v1/sites/:site_id/ppe_stocks
GET /api/v1/sites/:site_id/ppe_stocks/:ppe_product_id
PUT /api/v1/sites/:site_id/ppe_stocks/:ppe_product_id

Permisos: ppe_stocks:read para leer, ppe_stocks:write para leer y cargar.

El stock de cada producto en un sitio: la cantidad actual y el mínimo. Si tu ERP ya lleva el stock de EPP, el dueño del número es el ERP: lo empuja a Safety Panel con PUT y Safety Panel lo refleja, para que el sitio vea cuánto tiene y avise cuando un producto llega a su mínimo. Si no querés ni ese reflejo, pedí que se apague la gestión de stock en la cuenta.

Cada registro es un producto en un sitio, y se identifica por los dos: no tiene un id propio. El listado devuelve el stock de un sitio, se pagina y acepta el filtro updated_since.

json
{
  "site_id": 12,
  "ppe_product_id": 55,
  "quantity": 40,
  "minimum_quantity": 10,
  "low_stock": false,
  "created_at": "2026-03-10T14:05:00Z",
  "updated_at": "2026-10-20T15:42:10Z"
}
CampoTipoQué contiene
site_identeroEl sitio.
ppe_product_identeroEl producto.
quantityenteroLa cantidad actual. Nunca es negativa.
minimum_quantityenteroEl stock mínimo.
low_stockbooleanotrue si la cantidad llegó al mínimo o está por debajo: es lo que el panel muestra como Stock bajo.
created_at, updated_atinstanteCuándo se cargó por primera vez y cuándo cambió por última vez.

El listado incluye el stock de productos que ya no están habilitados en el sitio: deshabilitar un producto no borra su stock. Un producto que nunca tuvo stock cargado en el sitio no aparece, y su GET responde 404. El stock no tiene campos externos: tu sistema lo encuentra por el sitio y el producto, que sí los tienen.

Cargar el stock ​

PUT fija el stock de un producto en un sitio a los valores que envías. No suma ni resta: es la cantidad que tu ERP tiene en ese momento.

CampoTipo
quantityenteroObligatorio. Cero o más.
minimum_quantityenteroCero o más. Si no lo envías, queda el que estaba, o 0 la primera vez. Enviarlo como null responde 422.
sh
curl -X PUT "https://tuempresa.safetypanel.com.ar/api/v1/sites/12/ppe_stocks/55" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 40, "minimum_quantity": 10}'
  • Si el producto no tenía stock en el sitio, lo crea y responde 201 con el stock y su dirección en el encabezado Location. Si ya tenía, lo reemplaza y responde 200.
  • Repetir el mismo PUT deja el mismo stock, así que reintentarlo es seguro: acepta Idempotency-Key sin exigirlo.
  • Solo se crea stock de un producto habilitado en el sitio. Si no lo está, responde 422 con el código invalid_parameter. El stock que quedó de un producto que después se deshabilitó se puede seguir cargando.
  • Una cantidad faltante, negativa o que no es un número entero, o un campo que no está en la tabla, responde 422 con el código invalid_parameter y un mensaje que nombra el campo. No se escribe nada.
  • Un sitio o un producto que no existe en la cuenta responde 404. Un sitio archivado (status: deleted) sigue aceptando stock, igual que conserva sus productos habilitados.
  • Cargar stock requiere el módulo de EPP habilitado en la cuenta y en el sitio. Si no lo está, responde 403 con el código module_disabled.
  • Si la cuenta tiene la gestión de stock apagada, responde 409 con el código ppe_stock_disabled y no escribe nada: tu integración está empujando stock a una cuenta que no lo lleva. La lectura sigue respondiendo con lo último que se cargó.

El stock nunca se borra por la API.

Quién descuenta ​

Con la gestión de stock prendida, Safety Panel sigue moviendo el stock por su cuenta: descuenta al firmarse una entrega y suma al registrarse una devolución. Tu PUT reemplaza ese número con el tuyo.

La regla es esta: el último PUT de tu ERP es el que vale. El número de Safety Panel se pone al día con él, pero entre una firma y tu siguiente PUT puede quedar distinto:

  • Más bajo, si Safety Panel ya descontó una entrega que tu ERP todavía no procesó.
  • Más alto, si tu ERP envía una cantidad calculada antes de procesar la firma: ese PUT pisa el descuento de Safety Panel hasta el siguiente.

El próximo PUT que ya contempla la entrega los vuelve a igualar. Si necesitás que el número de Safety Panel sea exacto, recibí el webhook ppe_delivery.signed y enviá el PUT en cuanto tu ERP procese esa entrega; para las devoluciones, lo mismo con ppe_delivery_return.created.

Qué mueve updated_at ​

Cambia con cada PUT, y también cuando Safety Panel descuenta stock al firmarse una entrega o lo suma al registrarse una devolución. Así, updated_since alcanza para enterarse de todo lo que cambió.

Incidentes ​

GET /api/v1/incidents
GET /api/v1/incidents/:id

Permisos: incidents:read. Es un recurso de solo lectura.

Los incidentes de la cuenta: dónde y cuándo ocurrieron, de qué tipo y gravedad, a quién afectaron, en qué estado está cada etapa y si tienen la denuncia SRT enviada. Es el recurso que un sistema de RRHH lee para cruzar los accidentes con el ausentismo.

Un incidente puede contener datos de salud de una persona, así que el permiso incidents:read no se da nunca solo: ni las keys anteriores a los permisos ni ninguna key existente lo tienen. Para leer incidentes, emití una key que lo incluya.

Los incidentes se leen aunque el módulo de incidentes esté apagado: son registros que se conservan.

El listado se pagina y acepta el filtro updated_since, más estos:

FiltroDevuelve
site_idLos incidentes de ese sitio.
employee_idLos incidentes cuyo afectado es ese empleado.
report_statusLos incidentes con el reporte en ese estado: filed, accepted o rejected.
investigation_statusLos incidentes con la investigación en ese estado: not_started, in_progress, completed o not_required.
record_statusLos incidentes con el registro de consecuencias en ese estado: not_applicable, open o complete.

Sin filtros de estado, el listado trae todos los incidentes, rechazados y archivados incluidos. Un incidente tiene un estado por etapa, así que no hay un filtro status: cada filtro lleva el nombre del campo que filtra, y se pueden combinar. Un site_id o un employee_id que no existe en la cuenta devuelve una lista vacía; un valor que no es un número entero, o un estado que no está en la lista, responde 422.

json
{
  "id": 318,
  "incident_number": "27",
  "site_id": 12,
  "incident_type": "lost_time_injury",
  "occurred_at": "2026-09-14T11:30:00Z",
  "reported_at": "2026-09-14T12:00:00Z",
  "actual_severity": "moderate",
  "potential_severity": "serious",
  "work_related": true,
  "in_transit": false,
  "injury_occurred": true,
  "report_status": "accepted",
  "investigation_status": "completed",
  "record_status": "open",
  "finalized_at": null,
  "archived_at": null,
  "affected_employee_id": 81,
  "art_report_filed": true,
  "art_reported_at": "2026-09-15T09:00:00Z",
  "created_at": "2026-09-14T12:00:02Z",
  "updated_at": "2026-09-22T15:41:10Z"
}
CampoTipoQué contiene
identeroIdentificador del incidente.
incident_numbertexto o nullEl número correlativo de la cuenta que muestra el panel (N° 27). null en incidentes anteriores a la numeración.
site_identero o nullEl sitio del incidente. null si se reportó sin sitio y todavía no se le asignó uno.
incident_typetexto o nullEl tipo de evento: near_miss, first_aid, medical_treatment, restricted_work, lost_time_injury, serious_injury, fatality, occupational_illness, unsafe_act, property_damage o environmental_release. null mientras nadie lo clasificó.
occurred_at, reported_atinstante o nullCuándo ocurrió y cuándo se reportó.
actual_severity, potential_severitytexto o nullSeveridad real y potencial: negligible, minor, moderate, serious o fatal.
work_related, in_transitbooleanoSi es laboral y si ocurrió en el trayecto (in itínere).
injury_occurredbooleanoSi hubo lesión. Sin detalle de la lesión (ver abajo).
report_status, investigation_status, record_statustextoEl estado de cada etapa (ver abajo).
finalized_atinstante o nullCuándo se finalizó. Vuelve a null si se reabre para corregirlo, así que un incidente finalizado puede volver a cambiar.
archived_atinstante o nullCuándo se archivó.
affected_employee_identero o nullEl empleado afectado, solo su identificador. null si el afectado no es un empleado registrado.
art_report_filedbooleano o nullSi la denuncia SRT del incidente (la denuncia a la ART) figura como enviada. null donde la denuncia no aplica (en cuentas fuera de Argentina, o si el incidente no es laboral), para no confundirlo con una denuncia pendiente.
art_reported_atinstante o nullCuándo se envió esa denuncia, si se cargó la fecha. null también donde no aplica.
created_at, updated_atinstanteCuándo se registró y cuándo cambió por última vez.

Estados ​

Un incidente avanza en tres etapas independientes, las mismas de sus estados en el panel:

CampoValores
report_statusfiled (reportado), accepted (aceptado) o rejected (rechazado).
investigation_statusnot_started (sin iniciar), in_progress (en investigación), completed (terminada) o not_required (no requiere investigación).
record_statusnot_applicable (no aplica, sin lesión), open (abierto) o complete (completo).

Un incidente rechazado o archivado sigue apareciendo, con su report_status o su archived_at, para que tu sistema vea que salió del flujo. Un incidente eliminado desaparece: responde 404 y no vuelve en updated_since. Solo se elimina un reporte cargado por error, mientras no esté finalizado, archivado ni rechazado.

Qué no expone la API y por qué ​

Un incidente guarda datos de salud de la persona afectada y relatos escritos a mano que pueden nombrar a otras personas. Nada de eso sale por la API, con ningún permiso:

  • Datos de salud: la naturaleza de la lesión, la parte del cuerpo, el mecanismo, el agente material, la descripción de la lesión, la atención médica, los días perdidos y con tareas restringidas, y la fecha de vuelta al trabajo.
  • Texto libre: el relato del evento, el lugar, las causas y el análisis de causa raíz, la respuesta a la emergencia, los motivos de rechazo o archivo y cualquier nota.
  • Campos de las plantillas de investigación, los adjuntos y el informe en PDF.
  • Nombres de personas: el afectado llega solo como affected_employee_id, y los testigos no se exponen.
  • Los datos de la denuncia SRT más allá de si se envió y cuándo.

Si tu sistema necesita alguno de estos datos, cargalo desde el panel o pedilo a quien gestiona los incidentes.

Qué mueve updated_at ​

El updated_at de un incidente cambia con cualquier cambio en el propio incidente, incluidos los que no expone la API, y cuando se guarda un cambio en su denuncia SRT. Así, updated_since alcanza para enterarse de una denuncia enviada, de un cambio de estado o de un archivo. Puede traer un incidente sin ningún cambio visible: el cambio estuvo en un dato que la API no expone. Al revés, si cambia el país de la cuenta, art_report_filed y art_reported_at pueden pasar a null (o dejar de serlo) en todos sus incidentes sin mover su updated_at: después de un cambio así, volvé a leer los incidentes completos.

Necesidades de EPP ​

GET /api/v1/ppe_needs

Permisos: ppe_needs:read. Es un recurso de solo lectura.

Lo que cada empleado tiene que recibir según su EPP requerido, y si ya lo tiene. Es el recurso que un ERP lee para planificar compras y despachos: quién necesita qué y todavía no lo tiene, con la misma regla que usa el panel en la pestaña Entregas de EPP del empleado, sin recalcularla por su cuenta.

Cada registro es una categoría requerida de un empleado. El listado se pagina y acepta estos filtros:

FiltroDevuelve
statusLas necesidades en ese estado: covered, pending_signature o missing (ver abajo). status=missing son solo las faltantes. Sin este filtro, el listado trae los tres.
site_idLas necesidades de los empleados asignados a ese sitio.
employee_idLas necesidades de ese empleado.
ppe_category_idLas necesidades de esa categoría.
employee_statusLas necesidades de los empleados en ese estado: active, inactive o deleted. Sin este filtro, solo las de los empleados activos, como el status de los empleados.

Un site_id, employee_id o ppe_category_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero, o un estado que no está en la lista, responde 422.

Las necesidades se calculan en el momento: no tienen updated_at ni aceptan updated_since. Para planificar, pedí de nuevo el sitio completo, por ejemplo ?site_id=12&status=missing. Para enterarte de cada firma apenas ocurre, leé las entregas de EPP con signed_since.

json
{
  "id": 501,
  "employee_id": 81,
  "ppe_category_id": 3,
  "ppe_category_name": "Casco",
  "status": "covered",
  "source": "ppe_delivery",
  "ppe_delivery_id": 912,
  "delivered_on": "2026-09-14"
}
CampoTipoQué contiene
identeroIdentificador de la necesidad. Cambia si la categoría se quita y se vuelve a agregar, o si el EPP requerido del empleado se reemplaza con el del puesto: para reconocer una necesidad entre dos lecturas, usá employee_id y ppe_category_id.
employee_identeroEl empleado.
ppe_category_id, ppe_category_nameentero, textoLa categoría requerida.
statustextocovered, pending_signature o missing (ver abajo).
sourcetextoQué la respalda: ppe_delivery, una entrega de Safety Panel, o historical_record, una entrega en papel. null si falta.
ppe_delivery_identeroLa entrega que la cubre o que espera la firma. null si falta o si la cubre una entrega en papel.
delivered_onfechaSi está cubierta, la de la Última entrega que muestra el panel: el día de la firma, o el de la entrega en papel. Si espera la firma, la fecha de esa entrega. null si falta.
statusQué significa
coveredEl empleado tiene una entrega firmada de esa categoría y conserva al menos una unidad, o una entrega en papel. Es Entregado en el panel. Si hay más de una, se informa la más reciente.
pending_signatureNo está cubierta, pero hay una entrega lista para firmar con esa categoría: ya se despachó y falta la firma del empleado. En el panel sigue como Sin entregar hasta que la firma.
missingNi cubierta ni esperando firma. Una entrega cancelada o en borrador no cuenta, y una que el empleado devolvió por completo deja de cubrirla.

Una categoría requerida es del empleado, no de un sitio: una entrega firmada en cualquier sitio la cubre. El filtro site_id elige a quién mirar, no qué entregas cuentan.

Las necesidades requieren el módulo de EPP habilitado en la cuenta. Si no lo está, responden 403 con el código module_disabled.

Historial de entregas de EPP ​

GET  /api/v1/ppe_historical_deliveries
GET  /api/v1/ppe_historical_deliveries/:id
GET  /api/v1/employees/:employee_id/ppe_historical_deliveries
POST /api/v1/employees/:employee_id/ppe_historical_deliveries

Permisos: ppe_historical_deliveries:read para leer, ppe_historical_deliveries:write para cargar.

Las entregas en papel de la cuenta: entregas que pasaron antes de usar Safety Panel, o que quedaron documentadas solo en la planilla física. Es el recurso que un ERP usa en la puesta en marcha para cargar el historial, así los vencimientos y las reposiciones parten de la última entrega real y el EPP ya entregado no figura como faltante en las necesidades.

No son evidencia de firma. Una entrega del historial no tiene firma, no genera constancia, no descuenta stock y no se ve en el portal del empleado. Tampoco aparece nunca en las entregas de EPP: son dos recursos distintos, y todas traen kind: "historical" para que tu sistema no las confunda. Lo único que hacen es cubrir la categoría, igual que una cargada en el panel.

GET /api/v1/employees/:employee_id/ppe_historical_deliveries trae las de un empleado, aunque esté dado de baja, y responde 404 si el empleado no existe en la cuenta. GET /api/v1/ppe_historical_deliveries trae las de toda la cuenta, las cargadas en el panel incluidas. Los dos se paginan y aceptan los filtros updated_since y external_reference, más estos:

FiltroDevuelve
employee_idLas del empleado.
ppe_category_idLas de esa categoría.

Un employee_id o un ppe_category_id que no existe en la cuenta devuelve una lista vacía, y un valor que no es un número entero responde 422. Las entregas del historial se leen aunque el módulo de EPP esté apagado: son registros que se conservan.

json
{
  "id": 77,
  "kind": "historical",
  "employee_id": 81,
  "ppe_category_id": 7,
  "ppe_category_name": "Guantes",
  "delivered_on": "2019-03-15",
  "quantity": 2,
  "product_name": "Guantes de nitrilo",
  "brand": "Ansell",
  "product_model": "Sol-Vex 37-675",
  "notes": "Planilla 2019",
  "api_key_id": 4,
  "external_reference": "HIST-0042",
  "external_metadata": { "planilla": "2019-A" },
  "created_at": "2026-10-23T12:40:02Z",
  "updated_at": "2026-10-23T12:40:02Z"
}
CampoTipoQué contiene
identeroIdentificador de la entrega del historial. No es el id de una entrega de EPP.
kindtextoSiempre historical.
employee_identeroEl empleado que recibió los elementos.
ppe_category_id, ppe_category_nameentero, textoLa categoría que cubre.
delivered_onfechaEl día de la entrega, sin hora.
quantityenteroCantidad entregada.
product_name, brand, product_modeltexto o nullProducto, marca y modelo, tal como se cargaron.
notestexto o nullNotas.
api_key_identero o nullLa key de API que la cargó. null si se cargó en el panel o desde un CSV.
external_reference, external_metadataLos campos externos de tu sistema, por ejemplo el número del registro en tu ERP.
created_at, updated_atinstanteCuándo se cargó y cuándo cambió por última vez.

Cargar una entrega del historial ​

POST /api/v1/employees/:employee_id/ppe_historical_deliveries carga una entrega por llamada: no hay carga masiva. Exige el encabezado Idempotency-Key: si la llamada se corta, reintentala con la misma clave y la entrega no se carga dos veces.

sh
curl -X POST "https://tuempresa.safetypanel.com.ar/api/v1/employees/81/ppe_historical_deliveries" \
  -H "Authorization: Bearer spk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ppe_historical_delivery-HIST-0042" \
  -d '{"ppe_product_external_reference": "GUA-NIT-09", "delivered_on": "2019-03-15", "quantity": 2,
       "external_reference": "HIST-0042"}'
CampoObligatorioQué acepta
delivered_onSíFecha AAAA-MM-DD, anterior a hoy y desde 1950. Una entrega de hoy no es historial: registrala como entrega para que el empleado la firme.
quantityNoEntero, de 1 a 2147483647. Por defecto, 1.
product_name, brand, product_modelNoTexto.
notesNoTexto.
external_reference, external_metadataNoLos campos externos. Guardá ahí el identificador del registro en tu ERP: es lo que te permite encontrarlo después con el filtro external_reference.

La categoría se nombra con uno solo de estos campos:

CampoQué acepta
ppe_category_idEl id de la categoría.
ppe_product_idEl id de un producto del catálogo.
ppe_product_external_referenceEl código del producto en tu sistema (su external_reference en el catálogo). Tiene que coincidir con un solo producto.

Con un producto, la categoría es la del producto en el catálogo, y su nombre, marca y modelo completan los que no envíes. La entrega del historial guarda esos textos, no el producto: si el catálogo cambia después, no cambia.

Responde 201 con la entrega del historial, igual que GET, y su dirección en el encabezado Location. En la ficha del empleado aparece en Entregas registradas con origen Planilla en papel, la marca Sin firma digital y API · más el nombre de la key donde dice quién la cargó.

Una entrega del historial no se modifica ni se borra por la API. Si se cargó con un error, corregila en el panel: eliminala y cargala de nuevo.

Errores al cargar una entrega del historial ​

SituaciónRespuesta
Falta un campo obligatorio, o un campo tiene un tipo o un valor inválido422 invalid_parameter. El mensaje nombra el campo.
La categoría no se nombra, o se nombra con más de un campo422 invalid_parameter.
ppe_category_id o ppe_product_id no existen en esta cuenta, o el código del producto está vacío o no coincide con ninguno422 invalid_parameter, con el campo en el mensaje.
El código del producto coincide con varios productos422 ambiguous_external_reference, con matching_ids: los productos que lo comparten. Nombralo con ppe_product_id, o corregí el código en tu catálogo.
El producto no tiene categoría en el catálogo422 invalid_parameter. Asignale una en el panel, o enviá ppe_category_id.
El empleado está dado de baja422 employee_deactivated, con employee_id. Si volvió a trabajar, reactivalo primero.
La cuenta no tiene el módulo de EPP habilitado403 module_disabled.
El empleado de la ruta no existe en esta cuenta404 not_found.

Una carga que responde un error no guarda nada.

Documentación de Safety Panel, software de gestión de seguridad e higiene.