Usare l'API pubblica

Endpoint, autenticazione e i principali endpoint di lettura e scrittura della API pubblica v1 di Accordyx.

Prima di iniziare: Una chiave API con lo scope necessario, creata da chi ha il permesso «Gestisci integrazioni e API».

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 al tab Chiavi API trovi tre informazioni:

Endpoint base: nel formato <url>/functions/v1/public-api.
Autenticazione: header Authorization: Bearer <la-tua-chiave>.
Specifica: GET /v1/openapi.json, pubblica e senza autenticazione, descrive tutti gli endpoint in formato OpenAPI.

Un esempio pratico

curl -H "Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://dvfnmhwbzjjgwxfoqmfm.supabase.co/functions/v1/public-api/v1/contracts?limit=25"

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/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». Aggancia la controparte per ID, P.IVA, CF o ragione sociale esatta. Consuma crediti come un caricamento manuale: se la quota è esaurita ricevi un errore 402.
Gestione webhook via API (GET/POST/DELETE /v1/webhooks) — scope «Gestisci webhook». Vedi I webhook in uscita.

Paginazione e filtri

Le liste accettano limit (1–100, default 25) e offset, e rispondono con {data, pagination}. Su controparti e contratti puoi filtrare con updated_since per recuperare solo le righe cambiate da una certa data in poi.

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.
403 "Scope mancante: …" — la chiave non ha lo scope richiesto da quell'endpoint: creane una nuova con lo scope giusto.
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 su /v1/openapi.json.