Riferimento API

Tutti gli endpoint dell'API pubblica di Prynt, autenticati con una chiave API del workspace. Per costruire una richiesta per uno dei tuoi template con i nomi reali dei parametri, apri Sviluppatori → API explorer nella web app: scrive per te il codice cURL, C#, JavaScript e Python.

URL di base e convenzioni#

• URL di base: https://api.prynt.it/api/v1. I percorsi qui sotto omettono il prefisso /api dell'host dell'API: /v1/render significa https://api.prynt.it/api/v1/render.
• Header: Authorization: Bearer prynt_live_… in ogni chiamata tranne i link ai documenti, Content-Type: application/json per i corpi, facoltativamente Prynt-Workspace: <workspaceId> e un tuo X-Correlation-ID.
• I membri JSON sono in camelCase, le date in ISO 8601 UTC, e gli errori sono problem details (vedi Errori).
• Ogni risposta riporta X-Correlation-ID: lo stesso id compare nella pagina Log del workspace e nel corpo degli errori.

POST /v1/render#

Genera la versione pubblicata di un template con i tuoi parametri. Scope render.

Generazione sincrona

È la modalità predefinita. La risposta è 200 OK con il documento come corpo (application/pdf, oppure application/zpl per le etichette) e questi header:

HTTP/1.1 200 OKContent-Type: application/pdfContent-Disposition: attachment; filename="INVOICE_18425.pdf"X-Correlation-ID: 4bf92f3577b34da6a3ce929d0e0e4736X-Template-Version: 7X-Page-Count: 2X-Document-Format: pdfX-Environment: productionX-Run-ID: 0199c2f1-5a7e-7b31-9c4d-2f0a8e6b1d23

• X-Template-Version: la versione generata; X-Page-Count (PDF) o X-Label-Count (ZPL).
• X-Document-Format, X-Environment e X-Run-ID: l'esecuzione registrata nella pagina Log.

Generazione asincrona

Con "async": true l'API risponde subito 202 Accepted con un job di generazione, e il suo statusUrl nell'header Location. Interroga il job (o ascolta il webhook document.generated) finché il suo stato non è succeeded o failed.

curl -X POST https://api.prynt.it/api/v1/render \  -H "Authorization: Bearer prynt_live_..." \  -H "Content-Type: application/json" \  -d '{ "template": "INVOICE", "parameters": { "DOCUMENT_ID": 18425 }, "async": true }'

GET /v1/jobs/{jobId}#

Lo stato di un job di generazione: queued, running, succeeded o failed. Scope render. Un job riuscito ha un documentUrl per scaricare il documento; uno fallito un error con code e message (i codici della generazione, più RENDER_TIMEOUT e JOB_ABANDONED).

{  "jobId": "0199c2f1-7c10-7d2e-8f61-1b9a4c3e5d77",  "status": "succeeded",  "statusUrl": "https://api.prynt.it/api/v1/jobs/0199c2f1-7c10-7d2e-8f61-1b9a4c3e5d77",  "template": "INVOICE",  "version": 7,  "environment": "production",  "format": "pdf",  "attempts": 1,  "createdAt": "2026-10-08T09:12:03.120Z",  "startedAt": "2026-10-08T09:12:03.410Z",  "completedAt": "2026-10-08T09:12:04.020Z",  "pageCount": 2,  "outputBytes": 48213,  "documentUrl": "https://api.prynt.it/api/v1/documents/eyJhbGciOi…",  "documentUrlExpiresAt": "2026-10-08T09:27:04.020Z",  "documentExpiresAt": "2026-10-09T09:12:04.020Z",  "error": null,  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}

Interroga il job ogni uno o due secondi all'inizio, poi meno spesso; il job conserva il risultato dopo il completamento.

GET /v1/documents/{token}#

Scarica un documento conservato. Il documentUrl di un job è un link firmato e di breve durata (documentUrlExpiresAt): non richiede la chiave API, quindi si può passare a un browser o a un servizio di stampa, ma scade rapidamente. Il documento stesso viene conservato fino a documentExpiresAt; rileggi il job per ottenere un link nuovo. Un link scaduto o non valido risponde 404 DOCUMENT_NOT_FOUND.

GET /v1/templates#

Elenca i template pubblicati e attivi del workspace; GET /v1/templates/{code} ne restituisce uno. Scope templates.read. Ogni template riporta i suoi parametri, un JSON Schema (2020-12) dell'oggetto parameters con cui puoi validare i dati, e i suoi dataset con i rispettivi campi.

{  "code": "INVOICE",  "description": "Sales invoice",  "documentType": "FATTURA",  "format": "document",  "version": 7,  "updatedAt": "2026-10-01T15:40:00Z",  "parameters": [    { "name": "DOCUMENT_ID", "type": "integer", "required": true, "defaultValue": null, "description": "Invoice id" },    { "name": "LANGUAGE", "type": "string", "required": false, "defaultValue": "it", "description": "" }  ],  "parameterSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "…": "…" },  "datasets": [    { "code": "HEADER", "description": "Invoice header", "cardinality": "single", "fields": [{ "name": "NUMBER", "type": "string" }] }  ]}

POST /v1/datasets/{template}/{dataset}/execute#

Esegue un dataset della versione pubblicata di un template con i tuoi parametri e ne restituisce le righe in JSON: utile per mostrare nella tua applicazione i dati di un documento prima di stamparlo. Scope datasets.execute. La query non viene mai esposta e non puoi inviare SQL. maxRows vale 1.000 per impostazione predefinita e può arrivare a 10.000; truncated indica se alcune righe sono state escluse.

{  "parameters": { "DOCUMENT_ID": 18425 },  "environment": "production",  "maxRows": 500}

{  "template": "INVOICE",  "version": 7,  "dataset": "LINES",  "environment": "production",  "columns": [{ "name": "ITEM", "type": "string" }, { "name": "QTY", "type": "decimal" }],  "rows": [{ "ITEM": "A-100", "QTY": 2 }],  "rowCount": 1,  "truncated": false,  "elapsedMs": 38}

Errori#

Gli errori seguono la RFC 9457 (application/problem+json). Oltre ai membri standard, ogni problem riporta un errorCode stabile su cui basare la logica e il correlationId della richiesta; gli errori di validazione aggiungono errors (membro → messaggi). Non interpretare title o detail: sono per le persone.

{  "type": "about:blank",  "title": "Invalid parameter",  "status": 400,  "detail": "Parameter DOCUMENT_ID must be an integer.",  "errorCode": "PARAMETER_INVALID",  "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}