Skip to content

Sincronizar con otro sistema ​

Esta guía es para quien programa la integración. Antes, emití una key para ese sistema.

1. La primera lectura ​

Recorré cada listado página por página, hasta que meta.next_page sea null:

sh
curl "https://tuempresa.safetypanel.com.ar/api/v1/sites?per_page=100&page=1" \
  -H "Authorization: Bearer spk_…"

Hacé lo mismo con site_groups, professionals, employees, legal_entities, positions, ppe_categories, ppe_products, ppe_deliveries, ppe_historical_deliveries, certifications, training_records e incidents, según los permisos de la key, y con el stock de cada sitio en sites/:site_id/ppe_stocks. Antes de empezar, guardá el instante de la lectura: es el punto de partida de la próxima.

Las necesidades de EPP no se copian: se calculan en el momento, así que pedilas por sitio cada vez que planifiques una compra o un despacho.

Si además guardás los certificados en PDF de las constancias, descargalos aparte y a no más de 30 por minuto: tienen un cupo propio, más chico que el de las demás llamadas, porque cada uno se imprime en el momento. Las listas, en cambio, podés recorrerlas al ritmo del cupo general.

Por defecto, los listados devuelven solo los registros activos. Ver status. Los incidentes no tienen ese filtro: el listado los trae todos, rechazados y archivados incluidos.

2. Las lecturas siguientes ​

Pedí solo lo que cambió desde la última lectura, con updated_since:

sh
curl "https://tuempresa.safetypanel.com.ar/api/v1/sites?updated_since=2026-09-01T12:00:00Z" \
  -H "Authorization: Bearer spk_…"

Para enterarte también de las bajas, repetí la llamada con status=inactive y con status=deleted. Un registro dado de baja deja de aparecer en el listado por defecto, pero sigue disponible con esos filtros.

Las razones sociales no tienen estado: para enterarte de las fusiones, repetí la llamada con merged=true. Ver Fusiones.

Los productos y las categorías de EPP tampoco tienen estado. No se borran por la API, pero sí se pueden eliminar en el panel: un registro eliminado deja de aparecer en el listado, así que para enterarte comparalo de vez en cuando con una lectura completa.

3. El acceso de cada profesional ​

La API no trae una lista de sitios por profesional. Para mantenerla al día, seguí los cambios de los dos recursos:

  • full_client_access en los profesionales: si es true, el profesional accede a todos los sitios.
  • responsible_professional_id y professional_ids en los sitios: asignar o quitar un profesional cambia el updated_at del sitio, no el del profesional.

Ver A qué sitios accede un profesional.

4. Cargar el historial de entregas ​

En la puesta en marcha, cargá las entregas de EPP que tu sistema ya tenía como historial de entregas, así las necesidades y las reposiciones parten de la última entrega real. No hay carga masiva: es una llamada por entrega.

  1. Cargá antes los empleados y guardá el id que Safety Panel le dio a cada uno.
  2. Por cada entrega de tu sistema, hacé un POST a /api/v1/employees/:employee_id/ppe_historical_deliveries con:
    • el encabezado Idempotency-Key con el identificador del registro en tu sistema, precedido por el recurso (ppe_historical_delivery-HIST-0042): las claves valen para toda la key, así que sin el prefijo chocarían con las de otro recurso que comparta el número, y
    • el identificador, sin el prefijo, en external_reference.
  3. Mantené el ritmo dentro del límite de uso de 300 llamadas por minuto: mirá x-ratelimit-remaining y, si recibís 429, esperá los segundos de retry-after y seguí desde el mismo registro.
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", "external_reference": "HIST-0042"}'

Si la carga se corta, retomala desde el principio: dentro de las 24 horas la misma Idempotency-Key responde lo mismo sin cargar dos veces. Pasado ese plazo la clave ya no se recuerda, así que antes de volver a cargar un registro buscalo con GET /api/v1/ppe_historical_deliveries?external_reference=HIST-0042: si aparece, ya está cargado. Safety Panel no rechaza dos entregas con la misma external_reference, porque esa referencia es de tu sistema.

Un registro que responde 422 no se cargó: el mensaje dice qué corregir. Las entregas de un empleado dado de baja responden employee_deactivated; cargalas después de reactivarlo, o dejalas fuera si no volvió a trabajar.

Si una llamada falla ​

RespuestaQué hacer
401La key se revocó, está mal copiada o la cuenta está desactivada. Pedí una key nueva.
403La cuenta no tiene la API habilitada.
409Otro pedido con la misma Idempotency-Key sigue en curso. Esperá unos segundos y reintentá con la misma clave.
429Se superó el límite de uso. Esperá los segundos que indica retry-after y reintentá. Las descargas de certificados tienen un cupo propio de 30 por minuto: en una sincronización inicial, descargalos a ese ritmo, no al de las demás llamadas.
Timeout o error de red en una escrituraReintentá con la misma Idempotency-Key: si la primera llegó, responde lo mismo sin volver a escribir.

Ver todos los códigos en Errores.

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