Panoramica API
L'endpoint di generazione, le chiavi API, le risposte e gli errori (problem details RFC 9457).
L'API di Prynt genera su richiesta i template pubblicati. È un'API JSON su HTTPS: le richieste portano una chiave API, le generazioni riuscite restituiscono il documento stesso e ogni errore è un problem document leggibile da una macchina.
URL di base
Tutti gli endpoint si trovano sotto /api/v1 dell'API di Prynt, https://api.prynt.it. L'API è servita solo su HTTPS, dall'Unione Europea. Il riferimento API elenca tutti gli endpoint.
Chiavi API
I server si autenticano con una chiave API nell'header Authorization, come bearer token. Le chiavi appartengono a un solo workspace, e le chiavi di test non possono mai generare con i dati di produzione (vedi Autenticazione).
Authorization: Bearer prynt_live_...- Crea le chiavi in Sviluppatori → Chiavi API. La chiave completa viene mostrata una sola volta; Prynt ne conserva solo un hash.
- Le chiavi live iniziano con
prynt_live_, quelle di test (development e staging) conprynt_test_: una chiave trapelata si riconosce facilmente, e i secret scanner possono individuarla. - Tieni le chiavi lato server: nella configurazione o in un secret manager, mai nel codice eseguito dal browser o da un'app mobile.
- Per ruotare una chiave, creane una nuova, distribuiscila, poi revoca la vecchia. La revoca è immediata.
Non esporre mai una chiave in un browser
Generare un documento
POST https://api.prynt.it/api/v1/render genera la versione di un template pubblicata in un ambiente, con i parametri che passi.
{ "template": "invoice", "environment": "production", "parameters": { "invoiceId": 18425 }}| Campo | Tipo | Descrizione |
|---|---|---|
templateobbligatorio | string | Codice del template, così come impostato alla creazione (ad es. invoice). |
environment | string | Ambiente di cui usare le sorgenti dati: development, staging o production. Se omesso, l'ambiente predefinito della chiave. |
parameters | object | Valori dei parametri del template, per nome. I tipi vengono verificati sul template prima che venga eseguita qualsiasi query. Omettilo per i template senza parametri. |
Esempi
1curl -X POST https://api.prynt.it/api/v1/render \2 -H "Authorization: Bearer prynt_live_..." \3 -H "Content-Type: application/json" \4 -d '{5 "template": "invoice",6 "environment": "production",7 "parameters": { "invoiceId": 18425 }8 }' \9 -o invoice-18425.pdfRisposte
Una generazione riuscita risponde 200 OK con il documento come corpo: application/pdf per i documenti, application/zpl per i template di etichette. Gli header riportano il nome file suggerito e il correlation ID.
HTTP/1.1 200 OKContent-Type: application/pdfContent-Length: 48213Content-Disposition: attachment; filename="invoice-18425.pdf"X-Correlation-ID: 4bf92f3577b34da6a3ce929d0e0e4736Errori
Gli errori seguono la RFC 9457 (Problem Details for HTTP APIs), con Content-Type: application/problem+json. Oltre ai membri standard, ogni problem riporta un errorCode stabile su cui basare la logica e il correlationId della richiesta. Non interpretare title o detail: sono pensati per le persone e possono cambiare.
{ "type": "about:blank", "title": "Invalid parameter", "status": 400, "detail": "Parameter invoiceId must be an integer.", "errorCode": "PARAMETER_INVALID", "correlationId": "4bf92f3577b34da6a3ce929d0e0e4736"}| Stato | errorCode | Significato |
|---|---|---|
| 400 | VALIDATION_FAILED | Il corpo della richiesta non è valido oppure manca un campo. |
| 400 | PARAMETER_INVALID | Un parametro manca oppure il suo valore non corrisponde al tipo dichiarato. |
| 401 | API_KEY_INVALID | La chiave API manca, non è valida o è sconosciuta (anche API_KEY_REVOKED, API_KEY_EXPIRED). |
| 403 | SCOPE_MISSING | La chiave è valida ma non ha lo scope dell'endpoint (anche ENVIRONMENT_NOT_ALLOWED, WORKSPACE_MISMATCH). |
| 404 | TEMPLATE_NOT_FOUND | Nessun template con questo codice nel workspace della chiave. |
| 404 | TEMPLATE_NOT_PUBLISHED | Il template non ha una versione pubblicata. |
| 409 | TEMPLATE_DISABLED | Il template è disattivato. |
| 422 | RENDER_FAILED | I dati sono stati letti ma non è stato possibile produrre il documento (errore di espressione o di layout). |
| 422 | DATASET_FAILED | Non è stato possibile leggere un dataset dalla sorgente dati. |
| 429 | RATE_LIMITED | Troppe richieste. Attendi i secondi indicati dall'header Retry-After. |
| 503 | RENDER_BUSY | La capacità di generazione è satura. Riprova con backoff esponenziale, oppure genera in modo asincrono. |
| 500 | INTERNAL_ERROR | Errore imprevisto. Comunica il correlationId al supporto. |
Ritenta solo in caso di 429 e 503 (e di errori di rete), con backoff esponenziale. Gli altri errori 4xx richiedono una modifica della richiesta o del template.
Correlation ID
Ogni risposta riporta un header X-Correlation-ID, presente anche nei problem document. Invia il tuo con l'header di richiesta omonimo per seguire un documento dai tuoi log fino alla cronologia delle esecuzioni di Prynt; altrimenti ne viene generato uno.