# Italy FatturaPA Validator - SDI Preflight for FPA12, FPR12 (`kamerozkan/italy-fatturapa-validator`) Actor Offline structural and deterministic content preflight for FPA12, FPR12, and FSM10 XML with pinned derived schemas and structured findings. Italian e-invoicing preflight before SDI submission: catches technical errors that commonly cause an SDI scarto, without claiming SDI acceptance. - **URL**: https://apify.com/kamerozkan/italy-fatturapa-validator.md - **Developed by:** [Kamer Ozkan](https://apify.com/kamerozkan) (community) - **Categories:** Developer tools - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 1,000 invoice validateds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Italy FatturaPA Validator - SDI Preflight for FPA12, FPR12 [![FatturaPA](https://img.shields.io/badge/FatturaPA-FPA12%20%7C%20FPR12%20%7C%20FSM10-0066cc)](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/) [![Validation](https://img.shields.io/badge/Scope-OFFLINE__PREFLIGHT-0a7f5a)](#what-is-checked-offline) [![Rules](https://img.shields.io/badge/rules-SHA--256_pinned-1f6feb)](#pinned-artifact-chain) [![Billing](https://img.shields.io/badge/Billing-%240.004%20per%20evaluated%20invoice-6f42c1)](https://apify.com/kamerozkan/italy-fatturapa-validator) Offline structural and deterministic content preflight for FatturaPA XML. Validate `FPA12`, `FPR12`, and `FSM10` invoices before submitting them to Italy's Sistema di Interscambio (SdI). Each evaluated document receives a structured result, bounded findings, SHA-256 evidence, and exact artifact versions. > `ACCEPTED` means the XML passed the bundled derived XSD and the implemented > document-content checks. It is not an SdI acceptance, delivery, signature, > identity, registry, legal, accounting, or tax-validity guarantee. [Run the live Actor](https://apify.com/kamerozkan/italy-fatturapa-validator) ### Supported routes | Format | Offline schema route | Content reference | |---|---|---| | `FPA12` | Derived ordinary compatibility schema `1.2.3` | FatturaPA 1.4, SdI 1.8.4, controls 2.0 | | `FPR12` | Derived ordinary compatibility schema `1.2.3` | AdE Allegato A 1.9.1 | | `FSM10` | Derived simplified compatibility schema `1.0.2` | AdE Allegato A 1.9.1 | The current B2G and B2B profiles used by this Actor are effective from 2026-05-15. No Agenzia delle Entrate or FatturaPA XSD, PDF, spreadsheet, example, or stylesheet downloaded from the official sites is bundled. ### Quick start The default input contains a fictional FPR12 invoice and is ready to run. API callers can send inline XML: ```json { "documents": [ { "documentId": "supplier-invoice-1042", "fileName": "IT12345678903_001.xml", "xml": "..." } ], "resultDetail": "FINDINGS", "maxFindingsPerDocument": 100, "storeXmlReport": false, "storeHtmlReport": false } ``` Each `documents` item must contain exactly one source field: `url`, `xml`, or `base64`. Console file upload and customer key-value store records are also supported. URLs must use HTTPS. The input and output schemas are agent-readable and work through the Apify API, MCP clients, webhooks, Make, n8n, and standard SDKs. ### Result contract One dataset item is returned for every submitted entry. A technically rejected invoice is a completed evaluation, not a processing failure. | Processing | Conformance | Meaning | Validation event charged | |---|---|---|---| | `SUCCEEDED` | `ACCEPTED` | Bundled XSD and implemented deterministic checks passed | Yes | | `SUCCEEDED` | `REJECTED` | At least one bundled XSD or deterministic check failed | Yes | | `FAILED` | `NOT_EVALUATED` | Input, format, ruleset, timeout, or budget prevented a decision | No | Every row also returns: ```json { "validationScope": "OFFLINE_PREFLIGHT", "externalStateStatus": "NOT_EVALUATED_EXTERNAL_STATE", "previewConformanceStatus": "NOT_EVALUATED", "versions": { "schemaSource": "OPEN_SOURCE_DERIVED", "officialArtifactsBundled": false, "ordinarySchema": { "version": "1.2.3", "sha256": "10709324b24a5b5ba284bbf595392286cc94446d8b69defb2afd3a4f24f8213a" }, "simplifiedSchema": { "version": "1.0.2", "sha256": "698d4960a5e6121764e06157aef2593be5ea06fd4ab0938d52185643fcba4c29" }, "activeRuleset": { "name": "FatturaPA offline profiles current from 2026-05-15", "effectiveAt": "2026-05-15" } } } ``` `previewConformanceStatus` remains in the shared family output contract and is always `NOT_EVALUATED` for this product because there is no preview ruleset. ### Real output examples These compact records are taken from successful live run `95PRKHFR5WAZGlx7n`, build `0.0.2`, dataset `VwGNYgKd34KDOfiEM`. The run emitted two `invoice-validated` events for the evaluated documents and did not bill the unsupported document.
01. ACCEPTED - FPR12 passed the offline checks ```json { "documentId": "accepted-fpr12", "processingStatus": "SUCCEEDED", "conformanceStatus": "ACCEPTED", "validationScope": "OFFLINE_PREFLIGHT", "externalStateStatus": "NOT_EVALUATED_EXTERNAL_STATE", "validationFamily": "ITALY_FATTURAPA", "syntax": "FATTURAPA_XML", "profile": "FPR12", "counts": { "fatal": 0, "error": 0, "warning": 0, "information": 0 }, "findings": [], "sha256": "a08f1d2bc65d5658860ccf15c5308f89617c87b2e3a5671a550d6288f100b7a7", "error": null } ```
02. REJECTED - arithmetic and VAT totals failed ```json { "documentId": "rejected-arithmetic", "processingStatus": "SUCCEEDED", "conformanceStatus": "REJECTED", "validationScope": "OFFLINE_PREFLIGHT", "externalStateStatus": "NOT_EVALUATED_EXTERNAL_STATE", "profile": "FPR12", "counts": { "fatal": 0, "error": 2, "warning": 0, "information": 0 }, "findings": [ { "severity": "ERROR", "stage": "SDI_DETERMINISTIC", "ruleId": "00421", "message": "Imposta differs from the rounded VAT calculation by at least EUR 0.01", "location": "/FatturaElettronicaBody[1]/DatiBeniServizi/DatiRiepilogo[1]/Imposta" }, { "severity": "ERROR", "stage": "SDI_DETERMINISTIC", "ruleId": "00422", "message": "The taxable summary for a VAT rate differs from its lines, pension contributions, and rounding by at least EUR 1.00", "location": "/FatturaElettronicaBody[1]/DatiBeniServizi/DatiRiepilogo" } ], "sha256": "1fa834287d8a921c4ba1d80aa75bed47a5638ee0d46ba949997e97e600668463", "error": null } ```
03. NOT_EVALUATED - unsupported UBL syntax ```json { "documentId": "unsupported-ubl", "processingStatus": "FAILED", "conformanceStatus": "NOT_EVALUATED", "validationScope": "OFFLINE_PREFLIGHT", "externalStateStatus": "NOT_EVALUATED_EXTERNAL_STATE", "validationFamily": "UNKNOWN", "syntax": "UNKNOWN", "profile": "UNKNOWN", "counts": { "fatal": 0, "error": 0, "warning": 0, "information": 0 }, "findings": [], "sha256": null, "error": { "code": "UNSUPPORTED_DOCUMENT", "message": "The XML root does not match a supported invoice syntax" } } ```
### What is checked offline - Secure XML parsing with DTDs, entities, and external resources blocked - Root namespace, document type, format route, and derived XML Schema - VAT rate and Natura relationships - Withholding and pension contribution relationships - Invoice and linked-document date consistency inside the XML - Recipient-code length and root-format consistency - Invoice-number content and discount or charge completeness - Line total calculation, including sequential percentage adjustments - VAT summary tax calculation with the documented cent tolerance - Taxable summary calculation with the documented euro tolerance - Line, pension, and summary VAT or Natura cross-field coverage - Simplified-invoice EUR 400 limit with RF19, RF20, and correction exceptions - Document-type relationships that can be proven from VAT IDs present in XML - Duplicate date and invoice-number pairs inside a multi-body XML document The implemented deterministic rule IDs are pinned in `rules_manifest.json`. The Actor does not claim to reproduce every SdI check. ### What is not evaluated The following checks require live external state and return `NOT_EVALUATED_EXTERNAL_STATE`: - Submission history and duplicate file-name history - Tax, VAT, fiscal-code, and Gruppo IVA registries, including error `00327` - IPA and recipient-code directories - Declaration-of-intent status, including error `00477` - Certificate chain, expiry, trust, and revocation - Channel authorization, routing, delivery, and actual SdI acceptance When the buyer supplies only a fiscal code, comparisons that require resolving its VAT identifier are not guessed. The Actor also does not validate signed `.p7m` containers, ZIP packages, cryptographic authenticity, UBL, CII, or PDF invoices. ### Pricing - `invoice-validated`: `$0.004` for each invoice producing `ACCEPTED` or `REJECTED` - `NOT_EVALUATED` processing failures do not trigger the validation event - The Actor runtime refuses pay-per-event execution if the configured `invoice-validated` price differs from `$0.004` - Apify platform start charges may still apply separately ### Optional reports Both report settings are off by default: - `storeXmlReport`: normalized XML findings report - `storeHtmlReport`: human-readable findings report Returned keys appear in the row's `reports` object. Reports can contain invoice values and follow the retention settings of the customer's Apify account. ### Security and limits - Validation runs locally inside the Actor container - No invoice is sent to a third-party validation API - Raw invoice XML is not copied to dataset rows or logs - HTTPS downloads block private, local, reserved, and cloud metadata targets - Redirects and response sizes are bounded - Each XML document is limited to 5 MiB - A run accepts up to 100 invoice entries and 100 MiB total input - Finding count, text fields, and total findings payload are bounded - The container runs as the non-root `myuser` account Validation findings and optional reports can contain invoice values. Treat them as sensitive business data. ### Pinned artifact chain | Artifact | Source chain | Bundled SHA-256 | |---|---|---| | Ordinary derived schema 1.2.3 | `phax/ph-fatturapa` 3.1.0, commit `c5fc3a97208bf22e50949b09dd9bd396cb18cc9f` | `10709324b24a5b5ba284bbf595392286cc94446d8b69defb2afd3a4f24f8213a` | | Simplified derived schema 1.0.2 | `invopop/gobl.fatturapa` v0.69.0, commit `23b1ae16f7e5a243fa11f77e937912d0814db9e9` | `698d4960a5e6121764e06157aef2593be5ea06fd4ab0938d52185643fcba4c29` | | XMLDSig schema | W3C licensed schema | `35cf8197da812c85e40d57891b35c94187569ed474a2dac813ce5090dafcd35c` | The two baseline projects declare Apache License 2.0. Their license texts, the derived-schema notice, and the W3C notice are retained in the image. Docker verifies every bundled artifact against `ARTIFACTS_SHA256SUMS`. This is an engineering license assessment, not legal advice. Upstream provenance risk is not zero because the open-source baselines are based on Italian public specifications. See `THIRD_PARTY_NOTICES.md` for the exact source, commit, archive, baseline, derived, and license hashes. ### Release gates The offline release suite includes authored fixtures for: - Accepted FPA12, FPR12, and FSM10 routes - Rejected FPR12 VAT and taxable-summary arithmetic - Rejected FSM10 total-limit handling - Unsupported UBL producing `NOT_EVALUATED` - External-state status on every evaluated row - Artifact hashes, manifest routes, metadata, and exact pricing guard - DTD rejection, output truncation, URL safety, and non-root execution from the shared family core Official examples are not redistributed. ### References - [FatturaPA format documentation](https://www.fatturapa.gov.it/it/norme-e-regole/documentazione-fattura-elettronica/formato-fatturapa/) - [FatturaPA SdI documentation](https://www.fatturapa.gov.it/it/norme-e-regole/DocumentazioneSDI/) - [Agenzia delle Entrate technical specification 1.9.1 page](https://www.agenziaentrate.gov.it/portale/specifiche-tecniche-versione-1.9.1-%C2%A0-utilizzabili-dal-15-maggio-2026-) - [phax/ph-fatturapa](https://github.com/phax/ph-fatturapa) - [invopop/gobl.fatturapa](https://github.com/invopop/gobl.fatturapa) - [Third-party licenses and notices](THIRD_PARTY_NOTICES.md) This Actor is also exposed to AI agents through Apify's MCP server (mcp.apify.com): an agent can discover it by search and run it with the same pay-per-event billing, with no separate integration. ### E-invoice validator family Same engine, same output contract, one validator per market: [XRechnung & ZUGFeRD (Germany)](https://apify.com/kamerozkan/xrechnung-xml-batch-validator-api) | [Peppol BIS Billing](https://apify.com/kamerozkan/peppol-bis-preflight-validator) | [Poland KSeF FA(3)](https://apify.com/kamerozkan/poland-ksef-preflight-validator) | [France E-Invoice](https://apify.com/kamerozkan/france-einvoice-validator) # Actor input Schema ## `invoiceFiles` (type: `array`): Upload FPA12, FPR12, or FSM10 XML. Signed containers, ZIP files, UBL, CII, and PDF are not supported. Source XML is not copied to the output dataset. ## `documents` (type: `array`): Each object needs exactly one XML source: url, xml, or base64. URLs must use HTTPS. documentId and fileName are optional. ## `sourceKeyValueStoreId` (type: `string`): Optional. Select a key-value store containing FatturaPA XML records, then list the record keys below. ## `keyValueStoreKeys` (type: `array`): Record keys to read from the selected source key-value store. ## `resultDetail` (type: `string`): FINDINGS returns rule IDs, messages, and locations. SUMMARY returns only status and counts. ## `maxFindingsPerDocument` (type: `integer`): Caps the findings array without changing the total severity counts. ## `storeXmlReport` (type: `boolean`): Optional. Stores a normalized XML report in the run key-value store. It can contain invoice values. ## `storeHtmlReport` (type: `boolean`): Optional. Stores a human-readable findings report in the run key-value store. It can contain invoice values. ## Actor input object example ```json { "documents": [ { "documentId": "synthetic-fpr12-valid", "fileName": "synthetic-fpr12-valid.xml", "xml": "IT12345678903TEST0001FPR120000000IT12345678903Fictional Seller SRLRF20Via Test 100100RomaITIT98765432109Fictional Buyer SRLVia Example 220100MilanoITTD29EUR2026-07-29TEST-2026-001122.001Fictional validation service1.00100.00100.0022.0022.00100.0022.00" } ], "resultDetail": "FINDINGS", "maxFindingsPerDocument": 100, "storeXmlReport": false, "storeHtmlReport": false } ``` # Actor output Schema ## `validationResults` (type: `string`): No description ## `summary` (type: `string`): No description # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "documents": [ { "documentId": "synthetic-fpr12-valid", "fileName": "synthetic-fpr12-valid.xml", "xml": "IT12345678903TEST0001FPR120000000IT12345678903Fictional Seller SRLRF20Via Test 100100RomaITIT98765432109Fictional Buyer SRLVia Example 220100MilanoITTD29EUR2026-07-29TEST-2026-001122.001Fictional validation service1.00100.00100.0022.0022.00100.0022.00" } ] }; // Run the Actor and wait for it to finish const run = await client.actor("kamerozkan/italy-fatturapa-validator").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "documents": [{ "documentId": "synthetic-fpr12-valid", "fileName": "synthetic-fpr12-valid.xml", "xml": "IT12345678903TEST0001FPR120000000IT12345678903Fictional Seller SRLRF20Via Test 100100RomaITIT98765432109Fictional Buyer SRLVia Example 220100MilanoITTD29EUR2026-07-29TEST-2026-001122.001Fictional validation service1.00100.00100.0022.0022.00100.0022.00", }] } # Run the Actor and wait for it to finish run = client.actor("kamerozkan/italy-fatturapa-validator").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "documents": [ { "documentId": "synthetic-fpr12-valid", "fileName": "synthetic-fpr12-valid.xml", "xml": "IT12345678903TEST0001FPR120000000IT12345678903Fictional Seller SRLRF20Via Test 100100RomaITIT98765432109Fictional Buyer SRLVia Example 220100MilanoITTD29EUR2026-07-29TEST-2026-001122.001Fictional validation service1.00100.00100.0022.0022.00100.0022.00" } ] }' | apify call kamerozkan/italy-fatturapa-validator --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=kamerozkan/italy-fatturapa-validator", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/acts/wGcRt736F8h1gEuqL/builds/wSMetanmmvd9LiDdw/openapi.json