How do I make a test call?

Add "isTest": true to settings. Same request, same endpoint, same answer. Nothing is charged, the document is marked TEST on every page, and it has no legal value. Your key needs the isTest scope: the starter key has it, and on a new key it is the box Sandbox calls.

A test document

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

The PDF comes back as usual. X-Credits-Used is 0, and X-Test-Remaining says how many test items are left today. With "responseFormat": "json" the same number is in output.credits.testRemaining.

A test signature

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 }
  }'

The emails are real, so send them to yourself: each one says [TEST] in the subject and opens with a red warning. The signing page and the signed file carry the same red TEST band.

A test flow

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 }] }
      }
    }
  }'

A test flow is one test item for the document and the signature together.

Do test calls use credit?

No. They spend your organisation’s shared pool of test items: 20 a day unless we agreed another number with you. One call is one item. The pool refills at 00:00 UTC every day, a fixed time you can plan around. You can see what is left in three places:

• every test answer: output.credits.testRemaining, or the X-Test-Remaining header on a PDF;
• GET /api/v1/usage, in testItems, with the reset moment in resetsAt;
• the console’s home page (how long until it refills), and Reference → Limits, which writes the same 00:00 UTC in your organisation’s own time (02:00 in Italy in summer, 01:00 in winter).

When the pool is empty, a test call is refused whole with TEST_QUOTA_EXCEEDED (429). Nothing is charged.

What a test call cannot do

A test call never spends money at a third party. Asking for a qualified seal, a qualified timestamp, an SMS code or an AES/QES level together with isTest is refused with FEATURE_NOT_AVAILABLE_IN_TEST_MODE (422) before anything is reserved or sent; details.features names each. Nothing is quietly left out.

Test and production are counted apart

The console, GET /api/v1/usage and the export count production first and show test calls beside it (“1,240 documents · 37 test”), never one number mixing the two. The lists of documents, signatures and flows have an All / Production / Test filter, and every test row has a red TEST badge. The same filter is in the API: GET /api/v1/sign/envelopes?kind=production and GET /api/v1/flow?kind=test (all, production or test).

The export of your history (Export in the console menu, a ZIP of CSV files) has an is_test column in every file, including signature_recipients.csv and bulk_items.csv, and its README.txt gives the production and the test totals separately.

More: Generating a document, Test envelopes, Ready examples.