Come faccio una chiamata di prova?

Aggiungi "isTest": true a settings. Stessa richiesta, stesso endpoint, stessa risposta. Non viene addebitato nulla, il documento è marcato TEST su ogni pagina e non ha valore legale. La tua chiave ha bisogno dell'ambito isTest: la chiave iniziale ce l'ha, e su una chiave nuova è la casella Sandbox calls.

Un documento di prova

curl -X POST https://app.doconure.com/api/v1/compose/documents/generate \
  -H "Authorization: Bearer $DOCONURE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": { "title": "Order confirmation", "customer": { "name": "Rossi Costruzioni Srl" } },
    "settings": { "templateId": "YOUR_TEMPLATE_ID", "isTest": true }
  }' \
  --dump-header headers.txt --output test-document.pdf

Il PDF torna come al solito. X-Credits-Used vale 0, e X-Test-Remaining dice quanti elementi di prova restano oggi. Con "responseFormat": "json" lo stesso numero è in output.credits.testRemaining.

Una firma di prova

curl -X POST "https://app.doconure.com/api/v1/sign/envelopes?send=true" \
  -H "Authorization: Bearer $DOCONURE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-envelope-1" \
  -d '{
    "signers": {
      "A": { "email": "you@example.com", "fullName": "Your Name",
             "fields": [{ "kind": "signature", "page": 1,
                          "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.09 }] }
    },
    "settings": { "documentId": "THE_X-DOCUMENT-ID", "subject": "Test", "isTest": true }
  }'

Le email sono vere, quindi mandale a te stesso: ognuna porta [TEST] nell'oggetto e si apre con un avviso rosso. La pagina di firma e il file firmato portano la stessa fascia rossa TEST.

Un flusso di prova

curl -X POST https://app.doconure.com/api/v1/flow \
  -H "Authorization: Bearer $DOCONURE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-flow-1" \
  -d '{
    "data": { "title": "Service agreement", "customer": { "name": "Rossi Costruzioni Srl" } },
    "settings": { "templateId": "YOUR_TEMPLATE_ID", "isTest": true },
    "signature": {
      "subject": "Service agreement (test)",
      "signers": {
        "A": { "email": "you@example.com", "fullName": "Your Name",
               "fields": [{ "kind": "signature", "page": 1,
                            "x": 0.1, "y": 0.78, "width": 0.32, "height": 0.09 }] }
      }
    }
  }'

Un flusso di prova è un solo elemento di prova per il documento e la firma insieme.

Le chiamate di prova consumano credito?

No. Consumano la dotazione condivisa di elementi di prova della tua organizzazione: 20 al giorno, salvo un numero diverso concordato con te. Una chiamata è un elemento. La dotazione si ricarica alle 00:00 UTC di ogni giorno, un orario fisso su cui puoi contare. Vedi quanto resta in tre posti:

• ogni risposta di prova: output.credits.testRemaining, oppure l'intestazione X-Test-Remaining su un PDF;
• GET /api/v1/usage, in testItems, con il momento della ricarica in resetsAt;
• la home della console (quanto manca alla ricarica), e Riferimento → Limiti, che scrive le stesse 00:00 UTC nell'ora della tua organizzazione (le 02:00 in Italia d'estate, l'01:00 d'inverno).

Quando la dotazione è vuota, una chiamata di prova è rifiutata per intero con TEST_QUOTA_EXCEEDED (429). Non viene addebitato nulla.

Che cosa non può fare una chiamata di prova

Una chiamata di prova non spende mai denaro presso un terzo. Chiedere un sigillo qualificato, una marca temporale qualificata, un codice SMS o un livello FEA/FEQ insieme a isTest è rifiutato con FEATURE_NOT_AVAILABLE_IN_TEST_MODE (422) prima che qualcosa sia riservato o inviato; details.features li nomina tutti. Nulla viene tolto in silenzio.

Prove e produzione si contano a parte

La console, GET /api/v1/usage e l'esportazione contano prima la produzione e mostrano accanto le chiamate di prova (“1.240 documenti · 37 prove”), mai un numero che mescola le due. Gli elenchi di documenti, firme e flussi hanno un filtro Tutti / Produzione / Prova, e ogni riga di prova ha un bollino rosso TEST. Lo stesso filtro c'è nell'API: GET /api/v1/sign/envelopes?kind=production e GET /api/v1/flow?kind=test (all, production o test).

L'esportazione della tua cronologia (Esporta nel menu della console, uno ZIP di file CSV) ha una colonna is_test in ogni file, compresi signature_recipients.csv e bulk_items.csv, e il suo README.txt dà separati i totali di produzione e di prova.

Altro: Generare un documento, Buste di prova, Esempi pronti.