Usare l'API pubblica

La API pubblica di Accordyx ti permette di leggere, e con gli scope giusti anche scrivere, controparti e contratti da un sistema esterno. L'organizzazione a cui accedi è sempre quella legata alla chiave che usi: non la passi mai come parametro.

Endpoint e autenticazione

Nel riquadro in cima alla sezione API & Integrazioni trovi tre informazioni:

• Endpoint base: l'indirizzo a cui inviare tutte le richieste. Copialo da lì o dalla pagina /developers: tutti i percorsi di questa guida si aggiungono in fondo all'Endpoint base.
• Autenticazione: header Authorization: Bearer <la-tua-chiave>.
• Specifica: la specifica della API, pubblica e senza autenticazione, descrive tutti gli endpoint in un formato standard leggibile dagli strumenti di sviluppo. Chi sviluppa la trova anche, in forma interattiva, nella pagina /developers: vedi La documentazione per sviluppatori.

Un esempio pratico

curl -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "<Endpoint base>/v1/contracts?limit=25"

Al posto di <Endpoint base> metti l'indirizzo mostrato in Impostazioni → API & Integrazioni.

Endpoint di lettura

Richiedono lo scope indicato:

• GET /v1/counterparties e /v1/counterparties/:id — scope «Leggi controparti».
• GET /v1/contracts e /v1/contracts/:id — scope «Leggi contratti».
• GET /v1/contracts/:id/files — scope «Leggi contratti»: l'elenco dei documenti del contratto, dal più recente.
• GET /v1/contracts/:id/milestones e /v1/milestones — scope «Leggi scadenze».
• GET /v1/export/counterparties.csv e /v1/export/contracts.csv — scope «Export CSV», fino a 10.000 righe.

Endpoint di scrittura

• POST /v1/counterparties — scope «Crea/modifica controparti». Risponde 409 se esiste già una controparte con la stessa P.IVA/CF.
• PATCH /v1/counterparties/:id — aggiorna solo i campi che invii, senza toccare gli altri.
• POST /v1/contracts — scope «Crea contratti». Crea un contratto con i soli dati (JSON) oppure caricando il documento (PDF, DOCX o TXT fino a 20 MB). Aggancia la controparte per ID, P.IVA, CF o ragione sociale esatta. Ogni contratto creato consuma un'unità «Contratto in ingresso» del piano: se la quota è esaurita ricevi un errore 402.
• PATCH /v1/contracts/:id — scope «Crea contratti». Aggiorna dati, posizione nel ciclo di vita e controparte di un contratto.
• Gestione webhook via API (GET/POST/DELETE /v1/webhooks) — scope «Gestisci webhook». Vedi I webhook in uscita.

Caricamento dei documenti, aggiornamento dei contratti e regole sui duplicati sono spiegati in Caricare e aggiornare contratti via API. Nessun endpoint avvia l'analisi AI: analisi, OCR delle scansioni ed estrazione delle scadenze partono dall'applicazione.

Paginazione e filtri

Le liste accettano limit (1–100, default 25) e offset, e rispondono con {data, pagination}; pagination.has_more ti dice se ci sono altre pagine. Puoi filtrare con updated_since (data e ora in formato ISO 8601) per recuperare solo le righe cambiate da una certa data in poi. Su /v1/milestones puoi filtrare anche per data di scadenza con due_before e due_after.

Lingua dei messaggi

I messaggi di errore della API sono in italiano. Le integrazioni non devono basarsi sul testo, che può cambiare, ma sul codice stabile error.code: vedi Errori e limiti dell'API.

Problemi comuni

• 401 "API key mancante o malformata" / "API key non valida o revocata" — controlla l'header Authorization e che la chiave non sia stata revocata.
• 402 con codice feature_disabled — la API pubblica non è disponibile per la tua organizzazione: vedi L'API non è disponibile per la mia organizzazione.
• 403 "Scope mancante: …" — la chiave non ha lo scope richiesto da quell'endpoint: creane una nuova con lo scope giusto. Il messaggio indica lo scope con il suo nome tecnico, per esempio write:contracts per «Crea contratti».
• 429 "Rate limit superato" — hai superato le 60 richieste al minuto; rispetta l'header Retry-After prima di riprovare.
• 404 / 405 — rotta o metodo non validi: controlla la specifica della API nella pagina /developers.