API per sviluppatori · Lato ricezione
InvoiceIn.
Ogni fattura elettronica che ricevi, in un unico JSON.
Un solo endpoint stateless. Invia in POST qualsiasi file arrivi nella tua casella — XRechnung, ZUGFeRD, Factur-X, Peppol BIS 3, FatturaPA, KSeF — e ricevi un JSON EN 16931 canonico, un report di validazione che dice cosa deve correggere il mittente, un PDF da mostrare a una persona e un CSV o DATEV per la contabilità. Elaborazione in memoria, ~10–50 ms per documento.
Solo in memoria. Nulla viene salvato. Nessun access point Peppol richiesto.
Perché esiste
Il tuo software legge già FatturaPA: in Italia la fattura elettronica passa dallo SdI dal 2019. Ma ora i tuoi clienti ricevono anche fatture estere in formato EN 16931 — XRechnung dalla Germania, Factur-X dalla Francia, Peppol BIS 3 dal Belgio, KSeF dalla Polonia — e ogni formato ha il suo parser e il suo set di regole. Invece di cinque parser, ci mandi il file e ricevi un solo JSON per tutti, più l'elenco di cosa non va, scritto in parole che un contabile può inoltrare al fornitore. Il documento non viene mai conservato.
Demo dal vivo
Trascina una fattura passiva reale. La analizziamo, la validiamo con i set di regole ufficiali e mostriamo le indicazioni — nulla viene conservato.
Intestazione
Segnalazioni
JSON grezzo
Cinque output. Una sola chiamata.
JSON EN 16931 canonico
Una sola struttura per ogni sintassi. Campi denominati secondo il modello semantico con i numeri BT/BG: cedente, cessionario, righe, riepilogo IVA, totali, pagamento e IBAN, riferimenti, allegati. Le estensioni nazionali stanno sotto extensions.
Report con indicazioni su cosa correggere
Set di regole ufficiali più controlli aritmetici incrociati. Ogni regola non superata porta con sé un'indicazione in linguaggio chiaro, in inglese, tedesco, francese, italiano o polacco — cosa deve cambiare il mittente e quale campo (numero BT) riguarda.
PDF o HTML leggibile
Stesso layout A4 per ogni sintassi, etichette in inglese, tedesco, francese, italiano o polacco. Per chi approva e vuole vedere la fattura, non l'XML.
CSV e DATEV
CSV piatto per riga o per documento, e un Buchungsstapel DATEV (EXTF 700, il formato contabile tedesco) per la fattura passiva — SKR03 o SKR04, con il tuo conto fornitore.
Server MCP
Remoto su /mcp o locale via stdio. Claude, Cursor, n8n o il tuo agente legge e valida una fattura con una sola chiamata tool.
Cosa entra, cosa viene controllato.
Il rilevamento è automatico — invii il file, ti diciamo cos'era. I PDF ibridi vengono aperti e l'XML incorporato viene estratto; il PDF stesso non viene mai scritto su disco.
| Formato | Sintassi | Contenitore | Validazione applicata |
|---|---|---|---|
| XRechnung 3.0 | UBL 2.1 o CII D16B | XML | XSD · EN 16931 Schematron 1.3.17 · XRechnung 3.0.2 · aritmetica |
| EN 16931 | UBL 2.1 o CII D16B | XML | XSD · EN 16931 Schematron 1.3.17 · aritmetica |
| Peppol BIS Billing 3 | UBL 2.1 | XML | XSD · EN 16931 · regole Peppol BIS 3 · aritmetica |
| ZUGFeRD 2.x / Factur-X — EN 16931, EXTENDED, XRECHNUNG | CII D16B | PDF/A-3 ibrido o XML puro | XSD · EN 16931 Schematron 1.3.17 · aritmetica |
| ZUGFeRD 2.x / Factur-X — BASIC, BASIC WL, MINIMUM | CII D16B | PDF/A-3 ibrido o XML puro | XSD · regole di profilo Factur-X 1.09.2 (FX-SCH) · aritmetica (le regole base EN 16931 non si applicano sotto il profilo EN 16931) |
| ZUGFeRD 1.0 | CII (CrossIndustryDocument 1p0) | PDF/A-3 ibrido o XML puro | Schema · aritmetica |
| FatturaPA 1.2 | FatturaPA | XML | XSD FatturaPA 1.2.2 · aritmetica (i file con più corpi vengono restituiti come lotto) |
| KSeF FA(2) / FA(3) | Schema FA | XML | XSD FA(2) / FA(3) · aritmetica |
| Francia — CTC-FR (venditore e acquirente in Francia) | UBL 2.1 o CII D16B | XML o PDF Factur-X | XSD · EN 16931 · FNFE CTC-FR 1.4.0.04 (regole BR-FR, Flux 2) · aritmetica |
| RO e-Factura (CIUS-RO) | UBL 2.1 | XML | XSD · CIUS-RO 1.0.1, che contiene già le regole EN 16931 · aritmetica |
| Emirati Arabi Uniti — PINT AE (Billing, Self-Billing) | UBL 2.1 | XML | XSD · OpenPeppol PINT AE 1.0.4 (regole PINT comuni + regole emiratine) · pagina di verifica gratuita (EN) |
Le versioni delle regole sono elencate anche in tempo reale su GET /v1/formats. Manca un formato che ricevi? Dicci quale.
Fatto per i team che ora devono riceverle.
Ricevere fatture strutturate non è più facoltativo: in Italia la fattura elettronica via SdI è obbligatoria dal 2019, e accanto alle FatturaPA arrivano ora fatture estere EN 16931; in Germania l'obbligo di ricezione vale dal 1° gennaio 2025, in Belgio via Peppol da gennaio 2026, in Polonia il KSeF per il B2B dal 1° aprile 2026, in Francia dal 1° settembre 2026. Il lato ricezione ha bisogno di un parser, di un validatore e di un modo per mostrare il documento a una persona — e questo è tutto il prodotto.
SaaS di contabilità e ciclo passivo
I tuoi clienti inoltrano qualsiasi cosa mandino i loro fornitori. Un solo endpoint trasforma sei sintassi in un unico JSON che il tuo flusso di riconciliazione e approvazione già capisce — più un'indicazione da inoltrare al fornitore quando il suo file è sbagliato.
Plugin per ERP ed e-commerce
Dolibarr, InvoicePlane, Sylius, Shopware, Odoo — un plugin che legge XRechnung e Factur-X in arrivo è una funzione che puoi rilasciare in questo sprint invece di un progetto parser da sei mesi. Niente Java, niente toolchain Schematron nella tua build.
Agenzie che sviluppano strumenti per le PMI
I piccoli clienti in IT, DE, FR, PL e Benelux ricevono fatture elettroniche e ti chiedono cosa farne. Valida, genera il PDF, esporta in DATEV o CSV — e restituisci il rifiuto al mittente con il campo esatto da correggere.
Tre righe per il tuo primo parsing.
Invia il file come campo multipart file o come body XML/PDF grezzo. Autenticati con Authorization: Bearer <key> o X-Api-Key. Senza chiave hai la quota demo: 20 fatture per IP al giorno.
curl -X POST "https://invoicein-api.peculiar.systems/v1/invoice?include=validation&lang=en" \
-H "Authorization: Bearer $INVOICEIN_KEY" \
-F "[email protected]"import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("file", new Blob([await readFile("invoice.xml")]), "invoice.xml");
const res = await fetch("https://invoicein-api.peculiar.systems/v1/invoice?include=validation,datev&lang=de", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.INVOICEIN_KEY}` },
body: form,
});
const data = await res.json();
if (!data.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.invoice.totals); // { net, tax, gross, due, … }
console.log(data.validation.issues); // [{ id, severity, hint, field, who }]import os, requests
r = requests.post(
"https://invoicein-api.peculiar.systems/v1/invoice",
params={"include": "validation,pdf", "lang": "en"},
headers={"X-Api-Key": os.environ["INVOICEIN_KEY"]},
files={"file": open("invoice.pdf", "rb")},
timeout=30,
)
data = r.json()
if not data["ok"]:
raise SystemExit(f'{data["error"]["code"]}: {data["error"]["message"]}')
print(data["source"]["format"], data["source"]["profile"])
print(data["validation"]["valid"], data["validation"]["errors"], "errors")Risposta di esempio (abbreviata)
{
"ok": true,
"source": {
"format": "xrechnung-ubl",
"syntax": "UBL",
"profile": "XRechnung 3.0",
"container": "xml"
},
"invoice": {
"document": {
"id": "RE-2026-0421",
"issue_date": "2026-08-30",
"type_code": "380",
"currency": "EUR",
"buyer_reference": "04011000-12345-03"
},
"seller": {
"name": "Nordlicht Werkstatt GmbH",
"vat_id": "DE123456789",
"electronic_address": { "value": "[email protected]", "scheme": "EM" },
"address": { "line1": "Kanalstraße 12", "city": "Kiel", "postcode": "24103", "country": "DE" }
},
"buyer": { "name": "Beispiel Bau AG", "address": { "city": "Hamburg", "country": "DE" } },
"payment": {
"means_code": "58",
"credit_transfers": [{ "iban": "DE02120300000000202051" }]
},
"totals": { "line_net": 314.86, "net": 314.86, "tax": 22.04, "gross": 336.09, "due": 336.09 },
"tax_breakdown": [{ "category": "S", "rate": 7, "taxable": 314.86, "tax": 22.04 }],
"lines": [
{ "id": "1", "quantity": 3.5, "unit": "HUR", "net_amount": 314.86,
"price": { "amount": 89.96 }, "tax": { "category": "S", "rate": 7 },
"item": { "name": "Wartung Lüftungsanlage" } }
],
"extensions": {}
},
"validation": {
"valid": false,
"errors": 1,
"warnings": 0,
"rule_sets": [
{ "id": "EN16931-UBL", "version": "EN 16931 validation artefacts 1.3.17" },
{ "id": "XRechnung-UBL", "version": "XRechnung 3.0.2 Schematron 2.6.0" }
],
"issues": [
{
"id": "BR-CO-15",
"severity": "error",
"rule_set": "EN16931-UBL",
"message": "[BR-CO-15]-Invoice total amount with VAT (BT-112) = Invoice total amount without VAT (BT-109) + Invoice total VAT amount (BT-110).",
"hint": "Il totale fattura con IVA (BT-112) deve essere uguale al totale senza IVA (BT-109) più il totale IVA (BT-110). 314.86 + 22.04 = 336.90, ma il documento riporta 336.09 — il mittente ha arrotondato i totali indipendentemente dalle righe.",
"field": "totals.gross (BT-112)",
"who": "sender"
}
]
},
"timings_ms": { "detect": 1.2, "map": 3.8, "validate": 18.1, "total": 23.4 }
}Endpoint
- POST /v1/invoice
- Tutto in un solo JSON.
?include=validation,html,pdf,csv,datev&lang=en|de|fr|it|pl - POST /v1/validate
- Solo il report.
- POST /v1/parse
- Solo JSON canonico, senza validazione.
- POST /v1/render.html
- HTML leggibile.
- POST /v1/render.pdf
- PDF A4 leggibile.
- POST /v1/export.csv
- CSV piatto.
?level=lines|documents - POST /v1/export.datev
- Buchungsstapel DATEV.
?skr=03|04&creditor_account=70000 - GET /v1/formats
- Input supportati e versioni dei set di regole.
- GET /v1/rules/{id}
- Spiega un id di regola in linguaggio chiaro.
?lang=de - GET /v1/countries
- Quale formato richiede l'obbligo di ciascun paese, e con cosa lo validiamo.
- GET /v1/vat/{number}
- Verifica una partita IVA UE: formato offline, poi VIES in tempo reale, con ricevuta datata.
- GET /v1/peppol/{id}
- Una controparte è pubblicata su Peppol, e cosa può ricevere.
- GET /docs
- Riferimento OpenAPI.
- MCP /mcp
- Server MCP remoto; build locale stdio su richiesta.
Gli errori tornano come {"ok": false, "error": {"code", "message", "hint"}} con lo status HTTP corrispondente. I crediti residui sono nell'header X-Credits-Remaining.
Paghi per documento. I crediti acquistati non scadono mai.
Una fattura = un credito, qualunque output tu richieda in quella chiamata; un file che contiene più fatture costa un credito per ciascuna. Nessun minimo mensile, nessun costo per utente.
Con la tua prima chiave, validi 30 giorni. Nessuna carta. Abbastanza per collegare l'integrazione e provarla su file reali dei fornitori.
Per un plugin in produzione con una manciata di clienti.
La fascia tipica per uno strumento di ciclo passivo o un'agenzia che segue diversi clienti.
Volumi maggiori e immagini on-premise su fattura — chiedi.
Prezzi IVA esclusa. Pagamento tramite fattura o link di pagamento; checkout self-service in arrivo. Fattura su richiesta per volumi maggiori. La quota demo (20 fatture per IP al giorno) non richiede alcuna chiave.
Richiedi una chiave.
Lascia la tua email e, se vuoi, cosa ricevi. Rispondiamo con una chiave e, per i piani a pagamento, con la fattura o il link di pagamento.
I risultati della validazione descrivono cosa dicono i set di regole ufficiali su un file. Non sono consulenza legale o fiscale, e nessun controllo automatico può certificare che un documento venga accettato da un'autorità fiscale, dallo SdI o da un acquirente.
Risposte brevi.
È un access point Peppol?
Conservate le mie fatture?
Quali versioni delle regole usate?
- Artefatti di validazione EN 16931 1.3.17 (Schematron UBL e CII)
- XRechnung 3.0.2 — Schematron KoSIT 2.6.0 (UBL e CII)
- Regole Peppol BIS Billing 3.0, master corrente
- Profilo di transizione FNFE CTC-FR 1.4.0.04 (regole BR-FR, Flux 2) — si applica quando venditore e acquirente sono entrambi stabiliti in Francia
- CIUS-RO 1.0.1 (ro16931-ubl-1.0.9) — esito e formulazione coincidono con quanto restituisce lo SPV dell'ANAF
- Convenzioni di mercato che nessuno Schematron legge: condizioni di sconto tedesche (Skonto) nel testo libero e il numero KSeF polacco (
?ksef=) - XSD UBL 2.1 · XSD CII D16B · XSD FatturaPA 1.2.2 · XSD KSeF FA(2) e FA(3)
- Controlli aritmetici incrociati (somme di riga, IVA per categoria, totali) su ogni formato
Ogni risposta indica le versioni usate: validation.rule_sets nel corpo e l'header X-Invoicein-Rulesets. Le modifiche sono datate su /rules/changelog (feed Atom) e GET /v1/rulesets; qualsiasi id di regola può essere spiegato via GET /v1/rules/{id}?lang=it.
E i profili Factur-X BASIC e MINIMUM?
coverage: schema.