Apariencia
API
La API permite que un sistema externo, como el ERP o el sistema de RRHH de la empresa, lea y cargue datos de una cuenta de Safety Panel sin que una persona inicie sesión.
Lee el directorio de la cuenta y la evidencia que se genera en Safety Panel, y escribe lo que lleva el otro sistema: el personal, los sitios, el catálogo y el stock de EPP, y las entregas para firmar. La tabla de Qué expone dice qué se hace con cada recurso. Además, cada sistema puede guardar en un registro su propio identificador y sus propios datos, para reconocerlo después (ver Asociar los registros con los de tu sistema).
Nada se borra por la API: los empleados se dan de baja y los sitios se archivan, y los dos se restauran con todo su historial. La firma ocurre siempre en Safety Panel: la API nunca crea ni modifica una entrega firmada. Para conectar un ERP de punta a punta, ver Integrar un ERP.
Qué expone
| Recurso | Qué contiene |
|---|---|
account | La cuenta a la que pertenece la key. Sirve para comprobar que la credencial funciona. |
sites | Los sitios de la cuenta, con su dirección, sus razones sociales responsables y su CUIT, su grupo y los profesionales asignados. Se crean, se modifican, se archivan y se restauran por la API. |
site_groups | Los grupos de sitios y los sitios que reúnen. |
professionals | Los profesionales de la cuenta, con sus datos de contacto y si acceden a todos los sitios. |
employees | Los empleados de la cuenta, con su número de legajo, su empleador y los sitios y puestos en los que trabajan. |
legal_entities | Las razones sociales de la cuenta, con su identificador fiscal y sus actividades económicas, y a cuál se fusionó cada una. |
ppe_deliveries | Las entregas de EPP, con lo que firmó el empleado, sus devoluciones y un enlace temporal a la constancia en PDF. El ERP puede crearlas para que el empleado las firme en Safety Panel. |
positions | Los puestos de cada sitio, con su sector y las categorías de EPP que exigen. |
ppe_categories | Las categorías del catálogo de EPP. Solo lectura. |
ppe_products | Los productos del catálogo de EPP y los sitios donde están habilitados. Se crean, se modifican y se habilitan en sitios por la API. |
certifications | Las constancias de capacitación: quién hizo qué curso, su estado, su vencimiento y el certificado en PDF. Solo lectura. |
training_records | Los registros de capacitación presencial y quiénes asistieron. Solo lectura. |
ppe_stocks | El stock de cada producto en cada sitio: la cantidad actual y el mínimo. Lo carga el ERP por la API. |
incidents | Los incidentes, con su sitio, el empleado afectado, tipo, gravedad, el estado de cada etapa y si tienen la denuncia SRT enviada. Sin datos de salud ni relatos. Solo lectura, con un permiso que hay que elegir a propósito. |
ppe_needs | Las categorías de EPP que requiere cada empleado y si ya las tiene cubiertas, esperando firma o faltantes. Solo lectura. |
ppe_historical_deliveries | Las entregas en papel: el historial de entregas de EPP anterior a Safety Panel, que el ERP carga de a una en la puesta en marcha. No son evidencia de firma. |
Nada más: una key no lee ningún otro registro.
Los nombres de la API están en inglés
Los recursos y los campos se llaman en inglés, como es habitual en una API. Un site es un sitio, un site_group es un grupo de sitios, un professional es un profesional, un employee es un empleado, una legal_entity es una razón social, una ppe_delivery es una entrega de EPP, una position es un puesto, una ppe_category es una categoría de EPP, un ppe_product es un producto de EPP, un ppe_stock es el stock de un producto en un sitio, una certification es una constancia de capacitación, un training_record es un registro de capacitación, un incident es un incidente y una ppe_historical_delivery es una entrega en papel, los mismos conceptos que se ven en el panel (ver el glosario).
Keys
Cada sistema externo se identifica con una key: un texto que empieza con spk_ y viaja en cada llamada. La key pertenece a la cuenta, no a una persona, y solo accede a los recursos que se le dieron al emitirla: cada uno en lectura o en lectura y escritura (ver Permisos).
Conviene emitir una key por sistema. Así, cuando uno cambia o deja de usarse, se revoca solo la suya y los demás siguen funcionando.
Safety Panel no guarda la key, solo una huella que permite reconocerla. Por eso se muestra una sola vez, al emitirla.
Una cuenta por dirección
La API responde en el subdominio de la cuenta. Una key de otra cuenta no abre esta, y un registro de otra cuenta responde igual que uno que no existe.
Sincronización incremental
Cada recurso informa cuándo cambió por última vez, y se puede pedir solo lo que cambió desde una fecha. Así otro sistema se mantiene al día sin volver a leer todo. Ver Sincronizar con otro sistema.
Webhooks
En lugar de consultar cada tanto, un sistema puede recibir un aviso en el momento en que se firma una entrega de EPP, se registra una devolución, se carga un incidente o una constancia está por vencer o vence. El aviso trae solo el tipo de evento y el id del registro, que se lee con la key. Ver Webhooks.
Guías
- Emitir una key
- Revocar una key
- Sincronizar con otro sistema
- Asociar los registros con los de tu sistema
- Recibir eventos con un webhook
- Integrar un ERP
Referencia
- Habilitación — Cómo se activa en la cuenta y quién gestiona las keys.
- Convenciones — Dirección, autenticación, errores, paginación, filtros y límites de uso.
- Recursos — Cada recurso con sus campos.
- Webhooks — Los eventos, qué lleva cada aviso, cómo se verifica su firma y cómo se reintenta.
- Especificación OpenAPI —
/api/v1/openapi.yaml, para generar un cliente o validar las llamadas contra el contrato.