Audit dei sistemi esterni

L'API Audit conserva una sequenza di eventi inviata dai tuoi sistemi. Ogni evento descrive chi ha cambiato quale risorsa, quando e in quale sorgente. Il registro accetta soltanto metadati: non inviare valori precedenti o successivi, credenziali o contenuti della risorsa.

Gli eventi sono append only tramite API e non hanno una scadenza automatica. La company è determinata dalla chiave API, non dal payload. Usa una chiave server-side con external_audit:write per inviare eventi e external_audit:read per cercarli. Consulta autenticazione e fondamenti dell'integrazione per la gestione della chiave e degli errori.

Usa la base versionata https://api.hub.donutwork.com/2026-02-01. La versione 2026-02-01 è compatibile con l'implementazione 2024-08-01.

Inviare un evento

POST /audit-events.json richiede external_audit:write e un oggetto JSON di massimo 16 KiB. Un evento nuovo restituisce 201 Created.

curl -X POST 'https://api.hub.donutwork.com/2026-02-01/audit-events.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"event_id":"crm-change-123","source":"crm","action":"update","resource_type":"contact","resource_id":"contact-42","actor_id":"user-7","actor_type":"user","executor_ip":"203.0.113.7","occurred_at":"2026-09-30T12:00:00Z","changed_fields":["status"],"correlation_id":"request-123"}'

Non includere company_id: il server usa la company associata alla chiave. Per executor_ip, usa l'IP ricavato da una connessione o da un proxy fidato: Donutwork valida il formato, ma non può verificare che l'IP dichiarato corrisponda alla persona che ha eseguito l'azione. Campi non documentati, inclusi before e after, vengono rifiutati con 400.

La risposta contiene l'ID interno id, l'event_id inviato, i metadati normalizzati, occurred_at e received_at in UTC:

{
  "id": "INTERNAL_EVENT_ID",
  "event_id": "crm-change-123",
  "source": "crm",
  "action": "update",
  "resource_type": "contact",
  "resource_id": "contact-42",
  "actor_id": "user-7",
  "actor_type": "user",
  "executor_ip": "203.0.113.7",
  "correlation_id": "request-123",
  "changed_fields": ["status"],
  "occurred_at": "2026-09-30T12:00:00.000Z",
  "received_at": "2026-09-30T12:00:01.000Z"
}

Conserva lo stesso event_id nei retry. La coppia source + event_id è univoca nella company: un reinvio con contenuto identico restituisce lo stesso record con 200 OK; lo stesso ID con contenuto diverso restituisce 409 Conflict. Se l'invio ha un esito di rete incerto, ripeti lo stesso payload, incluso executor_ip. Nelle risposte relative a eventi precedenti senza questo campo, executor_ip è null.

Cercare gli eventi

GET /audit-events.json richiede external_audit:read. La risposta è ordinata per occurred_at decrescente e contiene elements, page, size e total.

curl 'https://api.hub.donutwork.com/2026-02-01/audit-events.json?source=crm&resource_type=contact&resource_id=contact-42&size=50&page=1' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

I filtri testuali sono confronti esatti: source, action, resource_type, resource_id, actor_id, event_id e correlation_id. from e to limitano occurred_at e accettano una data YYYY-MM-DD in UTC oppure un timestamp ISO 8601 con timezone. to=2026-09-30 include l'intera giornata UTC. page parte da 1 e size va da 1 a 100; i valori predefiniti sono 1 e 50.

Per leggere un singolo evento, usa l'id interno restituito da POST o dalla ricerca:

curl 'https://api.hub.donutwork.com/2026-02-01/audit-events/INTERNAL_EVENT_ID.json' \
  -H "Authorization: Bearer $DONUTWORK_API_KEY"

Un ID assente o appartenente a un'altra company restituisce 404. La ricerca è disponibile anche nel backoffice, in Developer Tools → External Audit.

Errori e limiti

received_at registra quando Donutwork ha ricevuto l'evento; occurred_at resta la data dichiarata dal sistema sorgente. L'API non modifica e non elimina gli eventi registrati.