Apariencia
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_accessen los profesionales: si estrue, el profesional accede a todos los sitios.responsible_professional_idyprofessional_idsen los sitios: asignar o quitar un profesional cambia elupdated_atdel 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.
- Cargá antes los empleados y guardá el
idque Safety Panel le dio a cada uno. - Por cada entrega de tu sistema, hacé un
POSTa/api/v1/employees/:employee_id/ppe_historical_deliveriescon:- el encabezado
Idempotency-Keycon 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.
- el encabezado
- Mantené el ritmo dentro del límite de uso de 300 llamadas por minuto: mirá
x-ratelimit-remainingy, si recibís429, esperá los segundos deretry-aftery 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
| Respuesta | Qué hacer |
|---|---|
401 | La key se revocó, está mal copiada o la cuenta está desactivada. Pedí una key nueva. |
403 | La cuenta no tiene la API habilitada. |
409 | Otro pedido con la misma Idempotency-Key sigue en curso. Esperá unos segundos y reintentá con la misma clave. |
429 | Se 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 escritura | Reintentá con la misma Idempotency-Key: si la primera llegó, responde lo mismo sin volver a escribir. |
Ver todos los códigos en Errores.