DoConure

Come ottengo una chiave API?

Ogni chiamata API porta la chiave dell'organizzazione in un header HTTP:

Authorization: Bearer lpdc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Non c'è un passaggio di login né un token separato da ottenere: la chiave va su ogni richiesta.

Non mettere mai la chiave nell'URL. Una chiave in una query string finisce nei log del server, nei log dei proxy intermedi e nella cronologia del browser. Solo nell'header.

  • Un'organizzazione può avere più chiavi attive contemporaneamente: è così che ne ruoti una senza interruzioni di servizio. Emettete quella nuova, aggiornate i chiamanti, revocate quella vecchia.
  • Ogni chiave scade. Scegliete una durata quando la emettete (30, 90, 180, 365 o 730 giorni, 90 per impostazione predefinita); non esiste un'opzione illimitata né un periodo di tolleranza dopo la scadenza: una chiave scaduta risponde esattamente come una revocata. Emettete la chiave successiva prima che la vecchia scada.
  • La revoca ha effetto immediato: la richiesta successiva riceve già INVALID_API_KEY. Non c'è finestra di tolleranza.
  • Una chiave porta degli scope: ciò per cui può essere usata, scelti all'emissione, un permesso alla volta, con una casella per ciascuno (composizione, lettura, download, gestione dei modelli, invio per la firma, il flusso in una chiamata, batch, consumi, chiamate di test), e mai ampliati in seguito: i permessi di una chiave possono solo restringersi. Chiamare qualcosa fuori dai suoi scope risponde TOKEN_SCOPE_NOT_ALLOWED; emettete una nuova chiave più ampia invece di provare a modificare quella vecchia.
  • Una chiave ha un nome, obbligatorio e diverso dal nome di ogni altra chiave attiva della vostra organizzazione (billing-export, crm-sync); il nome di una chiave revocata può essere riutilizzato. Le chiavi si emettono solo dalla console, nella pagina Chiavi API: mai da noi per conto vostro.
  • Le chiavi sono conservate solo come hash. Nemmeno un amministratore può rileggere una chiave emessa: la console ne mostra solo gli ultimi quattro caratteri, per distinguere tra loro più chiavi aperte.

La chiave iniziale

Un nuovo account riceve una chiave iniziale, chiamata hello-world, invece di una con accesso completo. Contiene esattamente ciò che serve alla prima chiamata: documents:compose, documents:read, documents:download, usage:* e isTest (la sandbox). Non può gestire i modelli, inviare per la firma, eseguire il flusso né inviare un batch, e scade dopo poco tempo (90 giorni, salvo che l'abbiamo cambiato). Un coordinatore crea una chiave completa con un clic nella pagina Chiavi API della console; nessuna chiave esistente cambia quando lo fa. Chiamare qualcosa che la chiave iniziale non contiene risponde TOKEN_SCOPE_NOT_ALLOWED e indica lo scope mancante in details.missingScopes.

Quale scope serve a ogni chiamata

Una chiave deve avere uno scope del gruppo della chiamata e lo scope specifico della chiamata; lo scope di gruppo (documents:*, signatures:*, bulk:*) soddisfa ogni chiamata del suo gruppo. Un rifiuto elenca lo scope che vi mancava. L'invio di un batch ne richiede due: bulk:submit esegue il batch e lo scope della singola chiamata (documents:compose, signatures:ses o flow:*) autorizzate ciò che vi si fa, quindi un batch non è mai un modo per aggirare uno scope. Se mancano entrambi, la risposta indica il primo, bulk:submit; una volta concesso, indica l'altro.

ChiamataScope
POST /api/v1/compose/documents/generatedocuments:compose
POST /api/v1/compose/documents/validatedocuments:compose
GET /api/v1/compose/documents/{id} (il PDF), /api/v1/compose/documents/{id}/download-linksdocuments:download
POST o DELETE /api/v1/compose/filesdocuments:compose
GET /api/v1/compose/filesdocuments:read
/api/v1/compose/templates/*documents:templates
/api/v1/sign/*signatures:ses
POST /api/v1/bulk/composebulk:submit e documents:compose
POST /api/v1/bulk/signbulk:submit e signatures:ses
POST /api/v1/bulk/flowbulk:submit e flow:*
POST /api/v1/bulk/files, annullare o ritentare un batchbulk:submit (un nuovo tentativo richiede anche lo scope dell'operazione del batch)
GET /api/v1/bulk/jobs*bulk:read
/api/v1/flow/*flow:*
GET /api/v1/usage, GET /api/v1/callback-environmentsnessuno: leggibili da qualsiasi chiave attiva
Una richiesta con "isTest": trueisTest, in aggiunta a quanto sopra

Avvisi di scadenza

Scriviamo ai coordinatori dell'organizzazione una volta a 30, 7 e 1 giorno dalla scadenza di una chiave, con la data esatta e un link per creare la successiva. Una chiave la cui intera durata non supera una soglia salta quell'avviso. Non c'è periodo di tolleranza: al secondo indicato la chiave smette di funzionare.

Un limite per una singola chiave

Oltre al limite di richieste al minuto dell'organizzazione, un coordinatore può dare a una singola chiave un limite proprio, nella pagina Chiavi API. Una chiave oltre il suo limite viene rifiutata con RATE_LIMIT_EXCEEDED (HTTP 429, i consueti header Retry-After e X-RateLimit-*, e details.limitedBy: "token") prima che la richiesta venga conteggiata per l'organizzazione, così un'integrazione guasta non può consumare il margine delle altre. Il limite dell'organizzazione vale comunque per ogni chiave. Senza un limite impostato, la chiave segue un valore predefinito della piattaforma, che è nessun limite.

Cosa può chiamare una chiave

La suite è composta da tre prodotti, venduti separatamente, e un'organizzazione può averne qualsiasi combinazione:

SuperficiePrefissoRisponde anche su
Composer Fly — composizione di documenti/api/v1/compose/*/api/v1/documents/*
/api/v1/templates/*
Signer Fly — firma elettronica/api/v1/sign/*/api/v1/signatures/*
Document Fly — il flusso in una chiamata/api/v1/flow/*—

Un prefisso per prodotto, dal 2026-09-19. Le tre superfici sono i tre prodotti così come vengono venduti e attivati, quindi l'URL ora dice quale state chiamando. Tutto ciò che sta sotto un prefisso appartiene a quel prodotto: /api/v1/compose/documents/generate, /api/v1/compose/templates, /api/v1/sign/envelopes.

I percorsi precedenti funzionano ancora e non spariranno a una data che non vi abbiamo comunicato. Se la vostra integrazione chiama /api/v1/documents/generate, continua a funzionare esattamente come prima: stessa richiesta, stessa risposta, governata dallo stesso interruttore dell'organizzazione. La nuova forma è quella che questa guida documenta e quella che il servizio restituisce nelle proprie risposte (il document.url di un flusso, per esempio); passare alla nuova è un cambio di stringa e nient'altro. Se mai ritireremo i vecchi prefissi, lo annunceremo con una data e un periodo di preavviso: non lo scoprirete da soli.

Una chiamata a un prodotto non attivo risponde 403 SUITE_NOT_ENABLED, lo indica in details.suite ed elenca ciò che avete attivo in details.enabled. Non viene addebitato nulla, e nessun cambio di chiave lo risolve: è un abbonamento, non una credenziale. Un coordinatore vede lo stesso elenco in Impostazioni, nella propria console.

Gli interruttori governano le porte, non le capacità. Un flusso compone internamente un documento che l'API di composizione sia attiva o no per voi: state chiamando il flusso, non l'API di composizione. Però la sua risposta rimanda a /api/v1/compose/documents/{id} e al download della busta, quindi con il solo flusso attivo quei link rispondono SUITE_NOT_ENABLED. Se dovete scaricare ciò che un flusso ha prodotto, vi serve la superficie su cui si trova.

Vale solo per le chiavi API. La vostra console non ne è toccata: modelli, documenti e firme restano visibili lì, qualunque cosa sia disattivata qui.