Skip to content

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.yaml

Trae 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:

NivelPermisoQué deja hacer
Sin acceso—Nada: toda llamada al recurso responde 403.
Lectura<recurso>:read, por ejemplo sites:readLeerlo con GET.
Lectura y escritura<recurso>:write, por ejemplo sites:writeLeerlo 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 HTTPcodeCuándo
400idempotency_key_missingLa escritura exige el encabezado Idempotency-Key y no llegó.
400idempotency_key_invalidEl encabezado Idempotency-Key está vacío, supera los 255 caracteres o tiene caracteres no admitidos.
401unauthorizedFalta la key, no es válida para esta cuenta o la cuenta está desactivada.
403module_disabledLa 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.
403insufficient_scopeLa key es válida, pero no tiene el permiso que la llamada necesita. El mensaje dice cuál.
404not_foundEl registro no existe en esta cuenta, o la ruta no existe.
404certificate_unavailableLa 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.
409idempotency_key_in_progressOtro pedido con la misma Idempotency-Key todavía está en curso.
409ppe_stock_disabledSe quiso cargar stock de EPP en una cuenta con la gestión de stock apagada.
409ppe_delivery_not_editableSe quiso modificar una entrega de EPP firmada o cancelada, o editar una lista para firmar. Trae status, el estado en el que está.
422invalid_parameterUn 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.
422idempotency_key_reusedLa Idempotency-Key ya se usó con un pedido distinto.
422employee_deactivatedSe 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.
422site_deactivatedSe quiso asignar un empleado o registrar una entrega de EPP en un sitio archivado. Trae site_id.
422ambiguous_external_referenceEl 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.
422legal_entity_mergedLa razón social indicada se fusionó con otra. Trae survivor_id, la razón social vigente que la reemplaza.
429rate_limitedLa 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ámetroValor por defectoValores válidos
page1Un entero desde 1.
per_page25Un 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
  }
}
  • total es la cantidad de registros que cumplen los filtros, sumando todas las páginas.
  • next_page es el número de la página siguiente, o null en la última. Para recorrer un listado completo, pedí páginas hasta que next_page sea null.
  • Una página más allá de la última responde con data vací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.

CampoTipoQué contiene
external_referencetexto o nullEl identificador que tu sistema le da al registro. Hasta 255 caracteres. No tiene que ser único.
external_metadataobjetoPares 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 "" o null la quitan.
  • Metadatos: se actualizan por clave. Una clave enviada reemplaza su valor y las demás no cambian. Una clave con "" o null se 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 422 con el código idempotency_key_reused.
  • Si el primer pedido todavía está en curso, el reintento responde 409 con el código idempotency_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:

EncabezadoQué indica
x-ratelimit-limitLas llamadas permitidas por minuto.
x-ratelimit-remainingLas que quedan en el minuto en curso.
x-ratelimit-resetEl 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.

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