Documentazione API

AuditReady Enterprise API

REST API versionata per integrare AuditReady con sistemi aziendali: raccolta documentale, classificazione AI, lettura dati estratti, export e webhook firmati HMAC SHA-256.

Consulta la documentazione interattiva Scarica la specifica OpenAPI

Flusso consigliato

1. Crea o seleziona una pratica

2. Genera o condividi il link cliente

3. Ricevi webhook sugli eventi

4. Recupera classificazioni, dati o export

La API key resta nel backend aziendale. Il cliente finale riceve solo il link cliente per caricare i documenti; i webhook avvisano il sistema aziendale e il backend usa poi le API per leggere i dettagli.

Casi d’uso supportati

Document collection + classification

Usa AuditReady come portale intelligente di raccolta documenti: il cliente carica file dal link sicuro, AuditReady li classifica e il sistema aziendale legge stato e categoria tramite API.

Extraction + export

Usa AuditReady anche per estrarre dati dalle bollette e generare export Excel con URL firmati, pronti per import o archiviazione.

Autenticazione

Ogni chiamata a `/api/v1/*` richiede header Bearer. Genera il token da AuditReady, salvalo in un secret manager e non esporlo mai in frontend o link cliente.

export AUDITREADY_TOKEN="ar_live_xxxxxxxxxxxxxxxxxxxxxxxx"

curl https://app.auditready.it/api/v1/practices \
  -H "Authorization: Bearer $AUDITREADY_TOKEN"

Endpoint e Scope minimi

Metodo	Endpoint	Scope minimo	Uso
GET	/api/v1/practices	practices:read	Lista pratiche disponibili per l’organizzazione.
POST	/api/v1/practices	practices:write	Crea una pratica dal sistema aziendale.
GET	/api/v1/practices/{id}/files	files:read	Legge file caricati, stato e classificazione.
POST	/api/v1/practices/{id}/files	files:write	Carica documenti tramite multipart/form-data.
GET	/api/v1/practices/{id}/extracted-bills	extracted_bills:read	Legge dati strutturati estratti dalle bollette.
POST	/api/v1/practices/{id}/exports	exports:write	Genera export e restituisce un URL firmato.

Esempi curl

curl "https://app.auditready.it/api/v1/practices?status=ready_to_export" \
  -H "Authorization: Bearer $AUDITREADY_TOKEN"

curl https://app.auditready.it/api/v1/practices/<practice_id>/files \
  -H "Authorization: Bearer $AUDITREADY_TOKEN" \
  -F "requirement_id=<requirement_id>" \
  -F "file=@./documento.pdf"

curl https://app.auditready.it/api/v1/practices/<practice_id>/extracted-bills \
  -H "Authorization: Bearer $AUDITREADY_TOKEN"

curl -X POST https://app.auditready.it/api/v1/practices/<practice_id>/exports \
  -H "Authorization: Bearer $AUDITREADY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"standard"}'

Webhook

Configura le subscription dall’area Integrazioni di AuditReady. Il receiver aziendale deve accettare POST JSON e rispondere 2xx. In caso di errore AuditReady ritenta fino a 3 volte.

Eventi tipici

practice.created
file.uploaded
file.classified
bill_extracted
export.ready

Header inviati

x-auditready-event
x-auditready-event-id
x-auditready-timestamp
x-auditready-signature

signature = HMAC_SHA256(
  webhook_secret,
  x-auditready-timestamp + "." + raw_json_body
)

Rate limit e sicurezza

Rate limit

Il limite default è 60 richieste al minuto per token. Le risposte includono `X-RateLimit-Limit`, `X-RateLimit-Remaining` e, sui 429, `Retry-After`.

Regole operative

Usa un token per ambiente, assegna solo gli scope necessari, ruota subito il token se esposto e non inviarlo mai al cliente finale.