Apariencia
Convenciones
Lo que se describe en esta página vale para todos los recursos.
Dirección
La API responde en el subdominio de la cuenta, bajo /api/v1/:
https://<subdominio>.safetypanel.com.ar/api/v1/El subdominio es la parte inicial de la dirección con la que se ingresa al panel (por ejemplo, para tuempresa.safetypanel.com.ar es tuempresa). La dirección exacta de la cuenta aparece en Configuración → API.
Todas las respuestas son JSON, salvo la descarga del certificado de una constancia, que es un PDF, y la especificación OpenAPI, que es YAML. Los recursos se leen con GET. Con PATCH se modifican sus campos externos, y los recursos que lo admiten se escriben además con POST, PATCH, PUT o DELETE, como indica cada uno en Recursos; toda escritura necesita el permiso del recurso. Un método que la ruta no admite, o una ruta que no existe, responde 404 con el código not_found, siempre que la llamada traiga una key válida: sin ella responde 401 (ver Errores).
Especificación OpenAPI
La API se describe también en un documento OpenAPI 3.1, para generar un cliente en tu lenguaje o validar tus llamadas contra el contrato:
https://<subdominio>.safetypanel.com.ar/api/v1/openapi.yamlTrae cada ruta con sus parámetros, sus cuerpos, sus respuestas y sus errores, el permiso que necesita cada operación, si exige o acepta Idempotency-Key (en x-idempotency, y en x-idempotency-fields los campos que la exigen cuando depende de lo que se envía) y los webhooks que Safety Panel envía, en la sección webhooks.
Es documentación: se descarga sin key, con la API habilitada o no, y no cuenta en el límite de uso. Es el mismo para todas las cuentas: solo cambia el subdominio, que en el documento es la variable subdomain de servers. Cuando la API cambia, el documento cambia con ella; se puede guardar en caché 5 minutos.
Autenticación
Cada llamada lleva la key en el encabezado Authorization, con el esquema Bearer:
Authorization: Bearer spk_…No se acepta la key en la dirección ni en otro esquema. Una llamada sin key, con una key revocada, con una key de otra cuenta o con una key que nunca existió responde lo mismo: 401 con el código unauthorized. La respuesta no distingue entre esos casos a propósito.
Una cuenta desactivada también responde 401.
Permisos
Cada key tiene permisos por recurso, que se eligen al emitirla y no cambian después. Para cada recurso, la key tiene uno de tres niveles:
| Nivel | Permiso | Qué deja hacer |
|---|---|---|
| Sin acceso | — | Nada: toda llamada al recurso responde 403. |
| Lectura | <recurso>:read, por ejemplo sites:read | Leerlo con GET. |
| Lectura y escritura | <recurso>:write, por ejemplo sites:write | Leerlo y modificarlo. La escritura incluye la lectura. |
Cada recurso indica en Recursos qué permiso lo lee y cuál lo modifica. Un recurso de solo lectura, como las categorías de EPP, tiene solo el nivel de lectura. Una llamada sin el permiso que necesita responde 403 con el código insufficient_scope, y el mensaje dice qué permiso falta:
json
{
"error": {
"code": "insufficient_scope",
"message": "Esta key no tiene el permiso sites:write."
}
}Ningún permiso se da solo: una key nueva tiene únicamente lo que se le eligió, y un recurso que se agregue a la API más adelante no le llega a ninguna key existente.
Keys anteriores a los permisos
Una key emitida antes de que existieran los permisos conserva exactamente el acceso que tenía, nunca más: lee account, sites, site_groups y professionals, y con PATCH solo modifica sus campos externos. Cualquier otra escritura, aunque el recurso la admita, responde 403 con el código insufficient_scope. Para elegirle otros permisos, emití una key nueva y revocá la anterior.
Fechas y horas
Todos los instantes van en UTC y en formato ISO 8601, por ejemplo 2026-09-23T17:41:48Z, aunque la cuenta opere en otra zona horaria.
La única excepción son los horarios de una capacitación presencial (start_time y end_time de los registros de capacitación): son horas locales de la cuenta, HH:MM, no instantes. Vienen junto con su date y con la zona horaria de la cuenta en time_zone, en formato IANA (por ejemplo America/Argentina/Buenos_Aires). Todo lo demás va en UTC.
Las fechas sin hora (como date, issued_on, expiration_date o delivery_date) son días del calendario de la cuenta, los mismos que muestra el panel. Un filtro que recibe una fecha sola la compara así, día contra día: expires_before=2026-12-01 trae lo que vence hasta el 30 de noviembre inclusive. La excepción es updated_since y los demás filtros de instantes, que comparan instantes: ahí una fecha sola es la medianoche UTC de ese día.
Errores
Todo error responde con el mismo formato: un objeto error con un code en inglés, pensado para que lo lea el sistema, y un message en español, pensado para que lo lea una persona.
json
{
"error": {
"code": "invalid_parameter",
"message": "per_page debe ser un entero entre 1 y 100."
}
}| Estado HTTP | code | Cuándo |
|---|---|---|
400 | idempotency_key_missing | La escritura exige el encabezado Idempotency-Key y no llegó. |
400 | idempotency_key_invalid | El encabezado Idempotency-Key está vacío, supera los 255 caracteres o tiene caracteres no admitidos. |
401 | unauthorized | Falta la key, no es válida para esta cuenta o la cuenta está desactivada. |
403 | module_disabled | La key es válida, pero la cuenta no tiene la API habilitada, o la llamada necesita un módulo que la cuenta o el sitio no tiene habilitado (por ejemplo, escribir en el catálogo de EPP o leer las necesidades de EPP). El mensaje dice cuál. |
403 | insufficient_scope | La key es válida, pero no tiene el permiso que la llamada necesita. El mensaje dice cuál. |
404 | not_found | El registro no existe en esta cuenta, o la ruta no existe. |
404 | certificate_unavailable | La constancia existe, pero su certificado no se descarga por la API: la persona no es un empleado ni un profesional, o su firma está pendiente de validación. |
409 | idempotency_key_in_progress | Otro pedido con la misma Idempotency-Key todavía está en curso. |
409 | ppe_stock_disabled | Se quiso cargar stock de EPP en una cuenta con la gestión de stock apagada. |
409 | ppe_delivery_not_editable | Se quiso modificar una entrega de EPP firmada o cancelada, o editar una lista para firmar. Trae status, el estado en el que está. |
422 | invalid_parameter | Un parámetro, o un campo enviado con POST, PATCH o PUT, falta o tiene un valor inválido. El mensaje dice cuál y qué valores acepta. |
422 | idempotency_key_reused | La Idempotency-Key ya se usó con un pedido distinto. |
422 | employee_deactivated | Se quiso dar de alta un empleado, o cambiarle el DNI, con el DNI de uno dado de baja, o se quiso asignar a un sitio o registrarle una entrega de EPP a un empleado dado de baja. Trae employee_id, el empleado a reactivar. |
422 | site_deactivated | Se quiso asignar un empleado o registrar una entrega de EPP en un sitio archivado. Trae site_id. |
422 | ambiguous_external_reference | El código de un elemento de una entrega de EPP coincide con varios productos del catálogo. Trae matching_ids, los productos que lo comparten. |
422 | legal_entity_merged | La razón social indicada se fusionó con otra. Trae survivor_id, la razón social vigente que la reemplaza. |
429 | rate_limited | La key superó su límite de uso. |
Algunos errores traen, además de code y message, otros campos dentro de error con los datos que tu sistema necesita para resolverlos. La fila de cada código en esta tabla dice cuáles. Por ejemplo:
json
{
"error": {
"code": "employee_deactivated",
"message": "El dni pertenece al empleado 81, dado de baja: reactivalo con PATCH status: active.",
"employee_id": 81
}
}La key se valida antes que todo lo demás: una llamada sin key válida recibe 401 aunque la ruta no exista o la cuenta no tenga el módulo habilitado. Después se revisa el módulo (module_disabled) y luego el permiso (insufficient_scope): una key sin permiso sobre un recurso recibe 403 aunque el registro pedido no exista. Si la llamada necesita otro módulo, como el de EPP, ese módulo se revisa después del permiso.
Un registro de otra cuenta responde 404, igual que uno que no existe.
Paginación
Los listados se entregan por páginas, ordenados por id de menor a mayor. Así una página no cambia entre dos llamadas seguidas.
| Parámetro | Valor por defecto | Valores válidos |
|---|---|---|
page | 1 | Un entero desde 1. |
per_page | 25 | Un entero entre 1 y 100. |
La respuesta trae los registros en data y la información para recorrer el resto en meta:
json
{
"data": [ … ],
"meta": {
"page": 1,
"per_page": 25,
"total": 42,
"next_page": 2
}
}totales la cantidad de registros que cumplen los filtros, sumando todas las páginas.next_pagees el número de la página siguiente, onullen la última. Para recorrer un listado completo, pedí páginas hasta quenext_pageseanull.- Una página más allá de la última responde con
datavacío, no con un error.
Filtros
Los filtros se pasan como parámetros en la dirección y se combinan con la paginación. Cada recurso indica cuáles acepta.
updated_since
Devuelve solo los registros que cambiaron en o después del instante indicado. Es la forma de sincronizar sin volver a leer todo: guardá el momento de la última lectura y pedí lo que cambió desde entonces.
- Acepta un instante ISO 8601 (
2026-09-01T12:00:00Z) o una fecha sola (2026-09-01), que se toma como la medianoche UTC de ese día. - Un instante sin zona horaria se interpreta en UTC.
- Cualquier otro valor responde
422.
Un registro también cuenta como cambiado cuando cambia algo que la API muestra dentro de él, por ejemplo, un profesional que se asigna a un sitio. Cada recurso detalla qué cambios lo mueven.
status
Filtra por estado. Si no se indica, devuelve solo los registros activos, tal como los muestra el panel. Un valor que el recurso no admite responde 422 y el mensaje lista los válidos.
Una búsqueda por external_reference, o por dni en los empleados, devuelve todos los estados salvo que se indique status. Las entregas de EPP no tienen un estado activo: sin status, el listado las trae en todos los estados. En las necesidades de EPP, status es si la categoría está cubierta, y el estado del empleado se filtra con employee_status, que funciona como este.
El filtro solo afecta a los listados: un registro pedido por su id se devuelve en cualquier estado, y el campo status indica en cuál está.
external_reference
Devuelve los registros cuya referencia externa es exactamente el valor indicado. Puede haber cero, uno o varios: Safety Panel no exige que la referencia sea única. external_reference= vacío devuelve los registros sin referencia, en cualquier estado: sirve para encontrar los que tu sistema todavía no asoció.
Cuando se busca por referencia, el listado incluye los registros en cualquier estado, no solo los activos, para que un sistema encuentre también a quien está dado de baja. Si se indica status además, se respeta.
Campos externos
Todos los recursos tienen dos campos que pertenecen al sistema que se integra, no a Safety Panel. Safety Panel los guarda y los devuelve, pero nunca los interpreta ni los muestra, salvo la referencia externa, que se ve en el panel en solo lectura.
| Campo | Tipo | Qué contiene |
|---|---|---|
external_reference | texto o null | El identificador que tu sistema le da al registro. Hasta 255 caracteres. No tiene que ser único. |
external_metadata | objeto | Pares clave–valor de tu sistema. Por defecto, {}. |
Se modifican con PATCH sobre el registro, enviando solo estos campos en JSON. Cualquier otro campo responde 422, salvo en los recursos que admiten escribir más campos, como los sitios, los empleados, los productos de EPP o las entregas de EPP. Un campo que no se envía no cambia. Una entrega de EPP firmada o cancelada no se modifica, ni siquiera en estos campos.
sh
curl -X PATCH "https://tuempresa.safetypanel.com.ar/api/v1/professionals/45" \
-H "Authorization: Bearer spk_…" \
-H "Content-Type: application/json" \
-d '{"external_reference": "E-123", "external_metadata": {"cost_center": "4410"}}'La respuesta es el registro completo, como lo devuelve GET. Un cambio en estos campos mueve el updated_at del registro.
- Referencia externa: un texto la reemplaza, y
""onullla quitan. - Metadatos: se actualizan por clave. Una clave enviada reemplaza su valor y las demás no cambian. Una clave con
""onullse borra, y"external_metadata": ""los borra todos.
Los metadatos admiten hasta 50 claves. Cada clave tiene hasta 40 caracteres y no lleva [ ni ], y cada valor es un texto de hasta 500 caracteres. Un número, un booleano o un objeto como valor responde 422: guardalo como texto.
No guardes datos sensibles en los metadatos
Los metadatos no se cifran y los lee cualquier key de la cuenta con permiso sobre ese recurso. No guardes contraseñas, tokens ni datos personales sensibles.
Idempotencia
Una escritura puede llevar el encabezado Idempotency-Key con una clave que tu sistema genera para esa operación. Si la llamada se corta —un timeout, una caída de red— y no sabés si llegó, reintentala con la misma clave: Safety Panel no la ejecuta dos veces.
sh
curl -X PATCH "https://tuempresa.safetypanel.com.ar/api/v1/professionals/45" \
-H "Authorization: Bearer spk_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c2a4e-8b0d-4d5e-9a3f-2c7b1e9d0a64" \
-d '{"external_reference": "E-123"}'- Usá una clave nueva por operación, por ejemplo un UUID. La clave tiene entre 1 y 255 caracteres ASCII visibles, sin espacios.
- Un reintento con la misma clave y el mismo pedido (mismo método, misma ruta con los mismos parámetros y mismo cuerpo) no se vuelve a ejecutar: responde el mismo estado y el mismo cuerpo que la primera vez, con el encabezado
Idempotent-Replayed: true. El orden de los campos en el JSON no importa. - La misma clave con otro pedido responde
422con el códigoidempotency_key_reused. - Si el primer pedido todavía está en curso, el reintento responde
409con el códigoidempotency_key_in_progress. Esperá unos segundos y reintentá con la misma clave. - Solo se recuerdan las respuestas exitosas (
2xx). Si la llamada responde un error, no se escribió nada: corregí el pedido y reintentá, con la misma clave o con otra. - Cada clave vale para la key de API que la usó y se recuerda durante 24 horas. Después, la misma clave se toma como una operación nueva. Dos keys de la misma cuenta no comparten claves.
La autenticación, la habilitación del módulo y los permisos de la key se verifican antes que la clave: una llamada rechazada por cualquiera de ellos no consume la clave ni recibe una respuesta de idempotencia.
Los PATCH de campos externos aceptan el encabezado pero no lo exigen. Las escrituras que lo exigen lo indican en Recursos, y sin él responden 400 con el código idempotency_key_missing.
En los empleados, lo exigen el alta (POST), todo PATCH que envíe status o legal_entity_id, aunque sea con el valor que ya tiene, y siempre asignar a un sitio (PUT) y quitar de un sitio (DELETE). Un PATCH que solo envía sus demás datos lo acepta, pero no lo exige.
En los sitios, lo exigen el alta (POST) y todo PATCH que envíe status o responsible_entity_ids, aunque sea con el valor que ya tiene. Un PATCH que solo envía sus demás datos lo acepta, pero no lo exige.
Límites de uso
Cada key tiene un cupo de 300 llamadas por minuto. El cupo es por key, no por dirección IP, así que dos sistemas con keys distintas no se afectan entre sí.
Cada respuesta a una llamada con key informa el cupo en tres encabezados:
| Encabezado | Qué indica |
|---|---|
x-ratelimit-limit | Las llamadas permitidas por minuto. |
x-ratelimit-remaining | Las que quedan en el minuto en curso. |
x-ratelimit-reset | El instante en que se renueva el cupo, en segundos desde el 1 de enero de 1970 (UTC). |
El cupo se renueva al comienzo de cada minuto, no un minuto después de la primera llamada. Una llamada por encima del cupo responde 429 con el código rate_limited y el encabezado retry-after, que indica cuántos segundos faltan para que se renueve. Esperá ese tiempo antes de reintentar.
La descarga del certificado de una constancia tiene, además, un cupo propio de 30 por minuto por key, porque cada certificado se imprime en el momento. Cada descarga cuenta en los dos cupos. Superarlo responde el mismo 429 rate_limited con su retry-after, y no afecta al resto de las llamadas de la key. Los encabezados x-ratelimit-* informan el cupo general, salvo en ese 429, donde informan el de certificados.