Caricare e aggiornare contratti via API

Con la API pubblica puoi portare in Accordyx i contratti di un altro sistema: caricare il documento, agganciarlo alla controparte giusta e poi tenerne aggiornati dati e posizione. È il modo più comodo per migrare un archivio contrattuale o per collegare un gestionale. Per endpoint base e autenticazione vedi Usare l'API pubblica.

Caricare il documento di un contratto

Invia una richiesta POST /v1/contracts in formato multipart/form-data, con il file nel campo file.

• Formati: PDF, DOCX o TXT, fino a 20 MB. Il contenuto deve corrispondere all'estensione.
• Campi facoltativi: title (se manca, si usa il nome del file senza estensione), type (categoria in testo libero, ricondotta a una delle nove categorie di Accordyx), value (importo, con punto o virgola come separatore decimale), start_date, expiry, direction (cliente, fornitore o altro).
• Posizione dichiarata: con status puoi indicare bozza, in_attesa, in_attesa_firma o attivo; in quel caso serve anche status_reason, una motivazione da 3 a 500 caratteri.

Il documento viene archiviato e il contratto compare subito in archivio, attribuito alla persona che ha creato la chiave API. La risposta (201) contiene il contratto, il file caricato e l'esito della lettura del testo.

Nessuna elaborazione AI parte dalla API: il testo viene letto in modo automatico ma senza AI, e l'analisi si avvia dall'applicazione quando qualcuno apre il contratto. Se il PDF è una scansione senza testo leggibile, la risposta lo indica (ocr_needed): il riconoscimento del testo si avvia dall'applicazione. Vedi Caricare contratti.

In alternativa puoi creare un contratto con i soli dati, senza documento, inviando la stessa richiesta in JSON con almeno il title.

Agganciare la controparte

Accordyx cerca la controparte in quest'ordine:

1. i campi che invii: counterparty_id, oppure counterparty_piva o counterparty_cf, oppure counterparty_name (nome esatto, usato solo se in anagrafica c'è una sola controparte con quel nome);
2. se non hai indicato né ID né Partita IVA né Codice Fiscale, la Partita IVA o il Codice Fiscale letti nel documento.

Se non trova nulla e hai inviato counterparty_create_if_missing=true insieme a counterparty_name, crea una nuova controparte. Nella risposta il campo matched_by dice come è stata individuata: id, piva, cf, name, document oppure created.

Evitare i doppioni

• external_id — l'identificativo del contratto nel tuo sistema. Se invii di nuovo un contratto con lo stesso external_id, Accordyx non lo duplica: risponde 200 con il contratto già creato e idempotent: true. È il modo sicuro per ripetere un caricamento interrotto.
• Documento identico — se lo stesso file è già in archivio, la richiesta viene rifiutata con 409 duplicate_file e il campo existing_contract_id indica il contratto che lo contiene. Se vuoi caricarlo lo stesso, aggiungi allow_duplicate=true.

Quota del piano

Ogni contratto creato consuma un'unità «Contratto in ingresso» del piano, come un caricamento dall'app. Quando la quota è esaurita la richiesta riceve 402 con codice plan_limit e nessun contratto viene creato. Una risposta idempotente o un duplicato rifiutato non consumano nulla. Vedi Utilizzo del piano e quote.

Aggiornare un contratto esistente

Invia PATCH /v1/contracts/:id in JSON con i soli campi da cambiare: gli altri restano invariati. Puoi aggiornare title, type, value, start_date, expiry, direction, counterparty_id (una controparte già presente nella tua organizzazione), external_id e la posizione nel ciclo di vita.

Per la posizione valgono le stesse regole dell'applicazione:

• status accetta bozza, in_attesa, in_attesa_firma o attivo, sempre con una motivazione status_reason da 3 a 500 caratteri; con status: null torni al calcolo automatico della posizione;
• un contratto firmato in piattaforma non si sposta: risposta 409 contract_status_locked_by_signature;
• un contratto in attesa di una decisione di approvazione non si sposta: risposta 409 approval_pending;
• dichiarare attivo non avvia nessuna generazione di documenti né analisi AI.

Leggere i documenti di un contratto

GET /v1/contracts/:id/files (scope «Leggi contratti») restituisce i documenti del contratto, dal più recente, con nome, tipo, dimensione, impronta del contenuto (SHA-256) e stato della lettura del testo.

Problemi comuni

• 409 duplicate_file "Documento identico già in archivio" — il file c'è già: usa existing_contract_id per ritrovare il contratto, oppure ripeti con allow_duplicate=true.
• 409 external_id_in_use — quell'identificativo esterno è già associato a un altro contratto.
• 413 file_too_large "File oltre il limite di 20 MB" — riduci il file o dividilo.
• 415 unsupported_file_type — il formato non è PDF, DOCX o TXT, oppure il contenuto non corrisponde all'estensione.
• 422 invalid_fields "Dati non validi" — il campo details elenca i campi da correggere, per esempio una motivazione troppo corta o una data non valida.
• 422 counterparty_not_found — il counterparty_id indicato non esiste nella tua organizzazione.
• 400 invalid_fields "Nessun campo aggiornabile nel body" — la PATCH non contiene nessun campo modificabile.
• 402 plan_limit — quota «Contratto in ingresso» esaurita.

Per tutti i codici vedi Errori e limiti dell'API.