Riferimento API v1
Elenco completo degli endpoint per entrambi i prodotti CrateAPI: esempi curl, risposte, autenticazione, limiti.
Preferisci l'OpenAPI grezzo? La specifica leggibile da macchina e la Swagger UI si trovano su api.crateapi.com/docs →
Per iniziare
Tre passaggi per la tua prima chiamata API.
Ottieni la tua chiave gratuita
Una chiave API gratuita è disponibile all'istante, direttamente qui sul sito — nessuna carta richiesta. I piani a pagamento aprono al lancio: iscriviti alla lista per il 20% di sconto.
Invia la tua chiave
Un header su ogni richiesta: X-Api-Key. Niente giri OAuth, nessun SDK richiesto.
Spedisci i documenti
Semplice HTTP + JSON/XML in ingresso, risultati in uscita. La documentazione mostra un curl funzionante per ogni endpoint.
oppure lascia che il tuo agente IA la chiami — server MCP →
Autenticazione
URL base fatturazione elettronica: https://api.crateapi.com/v1. URL base document tools: https://api.crateapi.com (percorsi /pdf, /screenshot, /email, /extract).
Inviate la vostra chiave come X-API-Key: <la vostra chiave>. Vi serve una chiave gratuita? Ottenetela all'istante su crateapi.com/account/ - nessun modulo, solo la vostra email.
Gli endpoint contrassegnati gratuito non richiedono alcuna chiave - è intenzionale, non una prova: la validazione resta gratuita per sempre.
curl -X POST https://api.crateapi.com/v1/validate/ubl \ -H "Content-Type: application/xml" \ --data-binary @invoice.xml {"profile":"peppol","valid":true,"counts":{"fatal":0,"warning":0},"findings":[],"duration_ms":12}
curl -X POST https://api.crateapi.com/v1/generate/ubl?profile=peppol \ -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \ -d @invoice.json -o invoice.xml
API di fatturazione elettronica
EN 16931: UBL/Peppol BIS, CII, Factur-X, FatturaPA (Italia: fatture e note di credito/debito TD01/TD04/TD05, codici Natura incl. forfettario), Facturae (Spagna: fatture verso la pubblica amministrazione), FA_VAT/KSeF (Polonia) e Order-X (ordini d'acquisto). Specifica OpenAPI completa: /openapi.json · documentazione interattiva: /docs (Swagger UI).
| Endpoint | Autenticazione | Note |
|---|---|---|
POST /v1/validate/ubl | gratuito | Valida una fattura UBL. `profile` è `peppol` per impostazione predefinita; passa `profile=auto` per il rilevamento automatico dal CustomizationID del documento (ripiego su en16931), oppure scegli esplicitamente: en16931, peppol, xrechnung, ro, fr, fr-extended, ehf, nlcius, pint. |
POST /v1/validate/cii | gratuito | Valida una fattura CII. `profile` è `en16931` per impostazione predefinita; passa `profile=auto` per il rilevamento automatico dal CustomizationID del documento (ripiego su en16931), oppure scegli esplicitamente: en16931, xrechnung, fr, fr-extended. |
POST /v1/validate/facturapa | gratuito | Solo validazione strutturale XSD per FatturaPA (non esiste un set ufficiale di regole schematron da vendorizzare). |
POST /v1/validate/orderx | gratuito | Order-X Basic - validazione XSD completa + schematron ufficiale. |
POST /v1/pdfa/validate | gratuito | Validazione PDF/A (veraPDF). `flavour`: auto|1a|1b|2a|2b|2u|3a|3b|3u|4|4e|4f. |
GET /validator | gratuito | Validatore drag-and-drop nel browser, stesso motore, senza registrazione. |
POST /v1/generate/ubl | richiede X-API-Key | Modello fattura JSON → XML UBL. `profile`: en16931, peppol, xrechnung, ro, ehf, nlcius, pint. |
POST /v1/generate/cii | richiede X-API-Key | Modello fattura JSON → XML CII. `profile`: en16931, xrechnung. |
POST /v1/generate/facturx | richiede X-API-Key | Il nostro PDF visivo minimale + XML CII incorporato (EN16931). |
POST /v1/generate/facturx/embed | richiede X-API-Key | Il vostro PDF a marchio + JSON fattura → PDF/A-3 con CII incorporato (multipart). |
POST /v1/generate/facturapa | richiede X-API-Key | XML FatturaPA (Italia): fatture TD01, note di credito/debito TD04/TD05, codici Natura di esenzione IVA (incl. forfettario N2.2), ritenuta/bollo/cassa opzionali. |
POST /v1/generate/orderx | richiede X-API-Key | XML ordine d'acquisto Order-X Basic (non è una fattura). |
POST /v1/convert/ubl-to-cii | richiede X-API-Key | Senza perdite o respinto: 422 con i dettagli invece di un degrado silenzioso. |
POST /v1/convert/cii-to-ubl | richiede X-API-Key | Stessa garanzia, direzione opposta. |
POST /v1/render/html | richiede X-API-Key | XML fattura → HTML leggibile (visualizzazione ufficiale KoSIT). |
POST /v1/render/pdf | richiede X-API-Key | XML fattura → PDF. `style`: compact (predefinito, 1 pagina) o kosit (modulo di audit). |
POST /v1/pdfa/convert | richiede X-API-Key | Qualsiasi PDF → PDF/A-3b, con file incorporati opzionali. |
POST /v1/pdfa/consistency | richiede X-API-Key | Factur-X: l'XML incorporato corrisponde al testo visibile del PDF? |
POST /v1/repair/ubl | richiede X-API-Key | Auto-riparazione best-effort: date non-ISO, scostamenti aritmetici sui totali. |
POST /v1/repair/cii | richiede X-API-Key | Stesso principio, sintassi CII. |
API Document Tools
PDF, screenshot, validazione email, estrazione contenuti. Autenticazione: la chiave gratuita da crateapi.com/account/ copre l'API di fatturazione elettronica — i piani Document Tools aprono al lancio, iscriviti alla lista. Specifiche per singola API: /pdf/openapi.json, /screenshot/openapi.json, /email/openapi.json, /extract/openapi.json.
| API | Endpoint | Note |
|---|---|---|
POST /pdf/merge | Unisce 2+ PDF, nell'ordine di caricamento. | |
POST /pdf/split | Estrae pagine, es. `pages=1-3,5`. | |
POST /pdf/watermark | Sovrapposizione testo diagonale - `text`, `opacity`, `color`, `font_size`. | |
POST /pdf/protect | Crittografia con password AES-256. | |
POST /pdf/compress | Ricompressione Ghostscript - `level`: low|medium|high; non restituisce mai un file più grande dell'originale. | |
POST /pdf/from-html | HTML grezzo → PDF (Chromium headless). | |
POST /pdf/from-url | URL pubblico → PDF, stessa protezione anti-SSRF di /screenshot. | |
POST /pdf/to-images | Pagine → PNG/JPEG, restituite come ZIP. | |
POST /pdf/extract-text | Estrazione di testo sensibile al layout (poppler, fallback pypdf). | |
POST /pdf/metadata | Numero pagine, flag di crittografia, campi info documento. | |
| screenshot | GET /screenshot/take | URL → PNG/JPEG. `block_ads`, `block_trackers`, `block_cookie_banners`, `cache_ttl`, `full_page`, `delay_ms`. |
GET /email/validate | Segnali sintassi + MX + usa-e-getta + account di ruolo + provider gratuito, con un punteggio. | |
POST /email/validate-batch | Fino a 100 indirizzi, corpo JSON. | |
POST /email/validate-bulk | Upload CSV, fino a 5.000 indirizzi; `format=json` o `format=csv` (risultati aggiunti). | |
| extract | GET /extract/article | URL → testo articolo pulito + metadati, senza elementi superflui. |
| extract | POST /extract-html | HTML grezzo → testo pulito (senza fetch). |
Limiti
Fatturazione elettronica: corpo XML limitato a 2 MB, upload PDF a 10 MB. La quota mensile per chiave (calibrata per piano, generosa di default - vedi prezzi) si applica a ogni endpoint eccetto /validate/* e /pdfa/validate, che restano senza limite.
Document tools: queste cifre descrivono i piani in arrivo al lancio (100 richieste/mese nel piano gratuito, fino a 50.000/mese su Ultra - vedi prezzi). Non esiste ancora nessuna chiave API per i Document Tools - prova subito ogni strumento dal vivo nel browser su /products/, e iscriviti alla lista per ricevere una chiave al lancio. La validazione email in blocco è limitata a 5.000 indirizzi / 2 MB per upload.
Server MCP (agenti AI)
Ospitato su https://api.crateapi.com/mcp (streamable HTTP) - aggiungete direttamente l'URL alla configurazione del vostro client MCP, niente da eseguire:
{"mcpServers": {"crateapi-einvoicing": { "type": "http", "url": "https://api.crateapi.com/mcp", "headers": {"X-API-Key": "your-key-here"}}}}
validate_invoice non richiede alcuna chiave; gli altri tre leggono l'header X-API-Key. Validare senza chiave è soggetto a un limite fair-use per IP, identico al validatore gratuito del sito.
Preferite il self-hosting - per privacy, un ambiente isolato o sviluppo locale? Stessi strumenti, come processo vostro:
{"mcpServers": {"crateapi-einvoicing": { "command": "python", "args": ["-m", "einvoicing.mcp_server"], "env": {"EINVOICE_API_KEY": "your-key-here"}}}}
Strumenti: validate_invoice (gratuito), repair_invoice, generate_invoice, convert_invoice. Approfondimento completo: /mcp/. Riepilogo leggibile da macchina di tutta questa pagina: /llms.txt · /ai (JSON).
I percorsi degli endpoint, gli esempi curl, i nomi di parametri e profili, e i payload JSON restano in inglese ovunque - il codice da copiare e incollare non ha bisogno di traduzione.