# POP Cloud API Documentation — full text Concatenated source of every guide, API reference page, and monthly release-notes entry in site-docs, in every language it's available in (full coverage in Italian and English; a subset of guides in French, German, Spanish, Dutch, and Polish; release notes are Italian/English only). --- ## Source: https://docs.popapi.io/de/guides/getting-started/choosing-an-invoicing-integration ## Ziel Verstehen, welchen Übermittlungskanal Sie für Ihren Shop aktivieren sollten, aus den in POP verfügbaren. **Die Kanäle schließen sich gegenseitig aus**: Sie können jeweils nur einen aktiv haben (die Aktivierung eines Kanals deaktiviert automatisch die anderen). ## Verfügbare Kanäle | Kanal | Für wen | Externe Abhängigkeiten | Hinweise | | --- | --- | --- | --- | | **SdI via POP** | Für alle, die den einfachsten Ablauf für Italien wollen: kein externer Dienst zu konfigurieren | Keine | Direkte Übermittlung an das SdI, Benachrichtigungen werden innerhalb von POP verwaltet, automatische Prüfung von Steuernummer/USt-IdNr. des Empfängers. | | **SdI via PEC** | Geringe Mengen, für alle, die bereits ein PEC-Postfach (zertifizierte E-Mail) haben und keine zusätzlichen externen Konten wollen | PEC-Postfach | Das XML wird per PEC-E-Mail gesendet; Ergebnisbenachrichtigungen müssen manuell im PEC-Postfach geprüft werden — sie werden nicht automatisch von POP verarbeitet. | | **Fatture in Cloud** | Für alle, die bereits Fatture in Cloud für Buchhaltung/Rechnungsstellung nutzen | Aktives Fatture-in-Cloud-Abonnement | Läuft über die offizielle Fatture-in-Cloud-API; erfordert die Zuordnung von [Zahlungsmethoden](../integrations/fatture-in-cloud-payment-methods.md) und ein Saldokonto vor der ersten Übermittlung. | | **Aruba Business** | Für alle, die bereits Aruba als E-Rechnungsanbieter nutzen | API-Aktivierung bei Aruba | Weniger Konfigurationsflexibilität als die anderen Optionen. | | **PEPPOL** | B2B-Verkäufe ins Ausland (PEPPOL-Netzwerk) | Keine | Keine Alternative zum SdI für Italien: es ist der Korridor für innergemeinschaftliche E-Rechnungsstellung. Deckt 28 Länder ab (vollständige Liste in [api/peppol](../../api/peppol.md)) — **Spanien ist ausgeschlossen** (Facturae-Korridor, noch nicht unterstützt), ebenso Nordirland und Liechtenstein. | | **KSeF** | Verkäufe nach Polen | Polnische NIP (Steuernummer) | Siehe [KSeF-Aktivierung](../integrations/ksef.md) — erfordert eine dedizierte Registrierung getrennt von SdI/PEPPOL. | | **Zoho (nativ)** | Für alle, die Zoho Invoice/Zoho Books nutzen und die Synchronisierung direkt über POP verwalten lassen möchten | OAuth-Autorisierung zu Zoho | Siehe [Zoho-Aktivierung](../integrations/zoho.md). Erfordert keine eigene n8n-Instanz. Für Konten, die in den Vereinigten Arabischen Emiraten, Saudi-Arabien, Bahrain, Kuwait, Oman oder Katar registriert sind, ist dies der **einzige** verfügbare Kanal: diese Länder haben kein unterstütztes offizielles E-Rechnungsnetzwerk (kein SdI/PEPPOL/KSeF). | Wenn Sie die Synchronisierungslogik lieber selbst auf Ihrer eigenen selbstgehosteten n8n-Instanz verwalten möchten (mehr Kontrolle/Anpassung), gibt es dafür auch ein dediziertes Paket — siehe [Synchronisierung zu Zoho über n8n](../integrations/n8n-zoho.md). ## Wie Sie wählen - **Sie verkaufen nur in Italien und nutzen noch kein externes Buchhaltungssystem** → SdI via POP: der Weg mit den wenigsten Konfigurationsschritten, Benachrichtigungen bleiben innerhalb von POP. - **Sie nutzen bereits Fatture in Cloud oder Aruba für die Buchhaltung** → verbinden Sie diese Integration, statt Daten anderswo zu duplizieren, planen Sie aber Zeit für die erforderliche Zuordnung ein (Konten, Zahlungsmethoden). - **Sehr wenige Dokumente pro Monat und Sie wollen keine zusätzlichen Kosten/Dienste** → SdI via PEC, wobei Sie die Ergebnisse manuell im PEC-Postfach prüfen müssen. - **Ihr Shop hat seinen Sitz in Italien oder San Marino** → bleiben Sie bei SdI (via POP oder via PEC), auch für ausländische Geschäftskunden: PEPPOL wird in diesem Fall nie aktiviert, unabhängig vom Land des Kunden. Rechnungen an ausländische Kunden laufen weiterhin über SdI, mit dem konventionellen Empfängercode für nicht-italienische Empfänger. - **Ihr Shop hat seinen Sitz in einem anderen EU-Land als Italien/San Marino, das von PEPPOL abgedeckt wird** (vollständige Liste in [api/peppol](../../api/peppol.md)), und Sie verkaufen B2B → nutzen Sie PEPPOL: es ist der zu SdI gleichwertige Kanal für die elektronische Rechnungsstellung in diesen Ländern. - **Sie verkaufen nach Polen** → Sie benötigen KSeF, unabhängig vom für Italien gewählten Kanal. - **Ihr Konto ist in den Vereinigten Arabischen Emiraten, Saudi-Arabien, Bahrain, Kuwait, Oman oder Katar registriert** → natives Zoho ist die einzige Option: für diese Länder ist kein anderer Kanal verfügbar. ## Gut zu wissen - Die gleichzeitige Aktivierung von SdI via POP und PEPPOL wird nicht unterstützt: sind am Ende beide aktiv, hat der zuletzt aktivierte Vorrang, der andere wird automatisch deaktiviert. - Sie können den Kanal später wechseln, aber die Konfiguration des neuen Kanals (Zugangsdaten, Zuordnungen) muss neu vorgenommen werden — es gibt keine automatische Datenmigration zwischen den Integrationen. ## Zugehörige Konfiguration Für Aktivierungsdetails zu jedem Kanal siehe die entsprechenden Anleitungen in diesem Abschnitt („Integrationen"). --- ## Source: https://docs.popapi.io/de/guides/getting-started/shopify-faq ## Ziel Sich schnell einen Überblick darüber verschaffen, was POP für Shopify tut (und nicht tut), bevor Sie in die einzelnen Konfigurationsanleitungen eintauchen. ## Bevor Sie beginnen **Berechnet POP die Steuern beim Checkout?** Nein. Shopify bleibt allein verantwortlich für die Berechnung und Anwendung von Steuern. POP verwendet die in Shopify vorhandenen Steuerdaten, um Dokumente (PDF/XML, SdI/PEPPOL/KSeF) zu erzeugen und zu versenden. **Wo konfiguriere ich USt, OSS, Märkte und Steuerregeln?** Immer im Shopify Admin (Markets, Tax regions). Für B2B prüfen Sie die Steuerdaten gegebenenfalls unter Company/Company Location. ## Steuerdaten des Kunden **Woher bezieht POP die Steuerdaten des Kunden?** Aus den Bestell-/Kunden-Metafeldern `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), mit einem Fallback auf die customAttributes der Bestellung. Details und Priorität in [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **Werden die Metafelder automatisch erstellt?** Ja, nach Abschluss des Assistenten und der POP-Lizenz wird versucht, fehlende Definitionen idempotent zu erstellen. Fehlt etwas, zeigt die Startseite einen Wiederherstellungsbereich mit der Schaltfläche „Fehlende Metafelder erstellen". ## Shopify Plus vs. Nicht-Plus **Was ist der Unterschied bei der Erfassung der Steuerdaten im Checkout?** Auf Shopify Plus ist die native POP Checkout UI Extension verfügbar. Bei Nicht-Plus-Shops werden die Felder über ein in das Theme eingefügtes Script zum Warenkorb/Warenkorb-Drawer hinzugefügt — siehe [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **Unterstützt POP sowohl B2B- als auch B2C-Szenarien?** Ja, beides; die steuerliche Korrektheit des Dokuments hängt weiterhin von der Qualität der in Shopify erfassten Daten ab. ## Italien, SdI und PEPPOL **Können die nativen Shopify-Felder Tax Code/PEC aus dem Checkout entfernt werden?** Nein, Shopify wendet sie nativ für Italien an, sie können von POP weder entfernt noch geändert werden. Sie bleiben optional; ihre Deaktivierung erfordert eine Anfrage an den Shopify-Support. **Kann ich mit einem Shop, dessen Währung nicht EUR ist, an das SdI senden?** Nein. SdI-Abläufe erfordern, dass die Hauptwährung des Shopify-Shops EUR ist. **Ist PEPPOL für Privatkunden verfügbar?** Nein. Der automatische Versand an PEPPOL überspringt immer Privatkunden (B2C); der PDF-Download als Gefälligkeitsdokument bleibt verfügbar. Details in [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **Validiert POP die USt-IdNr.?** Ja, über den offiziellen VIES-Dienst. Die endgültige steuerliche Entscheidung über die Anwendung der USt liegt weiterhin bei der Shopify-Konfiguration. ## Pläne und Limits **Wie viele Dokumente kann ich pro Monat erzeugen?** Das hängt vom aktiven Plan ab: Free 20/Monat, Basic 40/Monat, Growth 100/Monat, Pro 400/Monat, Enterprise 2000/Monat. Nach Überschreiten des Limits zeigt die Erzeugung eine Warnung mit einem Link zum Upgrade. ## Kurze Fehlerbehebung **Ich sehe nicht alle steuerlichen Felder bei Bestellung/Kunde:** 1. Prüfen Sie, ob der Assistent und die POP-Lizenz abgeschlossen sind. 2. Prüfen Sie, ob die `pop_*`-Metafelder erstellt wurden (andernfalls die Schaltfläche zur Neuerstellung auf der Startseite verwenden). 3. Prüfen Sie die Checkout-/Theme-Konfiguration. 4. Prüfen Sie Markets/Tax im Shopify Admin. **Die Steuern auf der Rechnung entsprechen nicht den Erwartungen:** 1. Prüfen Sie die Shopify-Steuerregeln. 2. Prüfen Sie den Kundentyp und die gespeicherten Steuerdaten. 3. Prüfen Sie auf eine fehlgeschlagene USt-Validierung. 4. Prüfen Sie den Übermittlungskanal (SdI/PEPPOL/KSeF) und dessen spezifische Einschränkungen. ## Zugehörige Konfiguration Für weiterführende Informationen beginnen Sie mit [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) und [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/de/guides/integrations/peppol ## Ziel Den Versand elektronischer Rechnungen über das PEPPOL-Netzwerk direkt aus Ihrem WordPress- oder Shopify-Shop aktivieren. ## Voraussetzungen - Bei WordPress: kein Mindestplan, Aktivierung und Versand sind in jedem Plan verfügbar (auch Free), auf Guthabenbasis. Bei Shopify ist weiterhin der **Basic-Plan oder höher** erforderlich. - Eine vollständige Adresse (Straße, Ort, Postleitzahl) für die juristische Person — PEPPOL benötigt diese Felder, um den Endpoint zu registrieren. - Für Deutschland: Sie müssen explizit den „Dokumentenkorridor" wählen (`zugferd` oder `peppol`) — ohne diese Wahl kann die Aktivierung nicht abgeschlossen werden. ## Schritte Sie können PEPPOL auf drei gleichwertige Arten aktivieren: 1. **Kontobereich** — gehen Sie auf `popapi.io` zu **Mein Konto > Integrationen**, öffnen Sie den PEPPOL-Tab und aktivieren Sie **„PEPPOL aktivieren"**. 2. **Über das Plugin/die App, mit bestehendem Konto** — in WordPress: Tab **Allgemein**, die Lizenzinformationen aktualisieren, dann zu **Integrationen** gehen und auf die PEPPOL-Karte klicken, um sie zu aktivieren. 3. **Geführter Einrichtungsassistent beim ersten Zugriff** — wenn Sie das Konto zum ersten Mal einrichten und Ihr Land den PEPPOL-Korridor nutzt, erfolgt die Aktivierung automatisch nach Abschluss des Assistenten. ## Automatischer Versand - **WordPress** — Tab **Erweitert > Automatischer Rechnungsversand**: aktivieren Sie den Versand per WP-Cron im Hintergrund. - **Shopify** — der automatische Versand bei bezahlten Bestellungen ist in den kostenpflichtigen Plänen verfügbar; er ist für Privatkunden standardmäßig deaktiviert (PEPPOL ist ein B2B-Korridor). ## Manueller Versand Verwenden Sie die Schaltfläche **„Rechnung senden"** in der Rechnungstabelle, um ein einzelnes Dokument an das PEPPOL-Netzwerk zu senden. ## Häufige Fehler - **„This field is required when PEPPOL is enabled."** — Adresse, Ort oder Postleitzahl der juristischen Person fehlen: ergänzen Sie diese im Kontobereich, bevor Sie es erneut versuchen. - **Aktivierung für Deutschland blockiert** — für `DE`-Konten müssen Sie den Dokumentenkorridor (`zugferd` oder `peppol`) wählen, bevor die Aktivierung gelingt. - **Automatischer Versand startet nicht bei einem Privatkunden** — erwartetes Verhalten: PEPPOL ist für Geschäftsempfänger konzipiert, der automatische Versand an Privatkunden ist standardmäßig deaktiviert. ## Zugehörige Konfiguration Für die Details des API-Vertrags (Payload, UBL-Feldzuordnung) siehe [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/de/guides/integrations/webhook ## Ziel Jedes von POP erzeugte Dokument (XML oder PDF) automatisch an ein externes Tool senden: Zapier, Make (Integromat), ein CRM, Google Drive oder einen benutzerdefinierten Endpoint. ## Voraussetzungen - POP **Basic-Plan oder höher** — Webhook-Zustellung ist im kostenlosen Plan nicht verfügbar. - Ein lauschender HTTP-Endpoint (die Ziel-Webhook-URL). ## Schritte 1. Gehen Sie auf `popapi.io` zu **Mein Konto > Integrationen > POP to Webhook > Verbinden**. 2. Konfigurieren Sie: - einen aussagekräftigen Namen - die Ziel-Webhook-URL - das Datenformat: **JSON** oder **XML** - den Aktivierungsschalter 3. Unter **WordPress**: gehen Sie im POP-Plugin zu **Erweitert > Webhook**, geben Sie die im vorherigen Schritt erstellte Webhook-ID ein, aktivieren Sie sie und aktivieren Sie zusätzlich den automatischen Versand per CRON, wenn Sie einen Hintergrundversand statt synchronen Versand wünschen. 4. Unter **Shopify**: geben Sie die Webhook-ID in den App-Einstellungen ein; in der Rechnungsliste erscheint dann ein Symbol zum Senden der Daten. ## Formate - **JSON** — für No-Code-Plattformen (Zapier, Make) konzipiert: die Daten werden automatisch in eine leicht zu mappende, flache Struktur gebracht. - **XML** — geeignet für Archivierung oder Systeme, die den FatturaPA-Standard benötigen; kann auch als Anhang gesendet werden. Sie können mehrere Webhooks mit unterschiedlichen URLs und Formaten gleichzeitig konfigurieren. ## Häufige Fehler - **Ungültige Webhook-URL** — prüfen Sie, ob die URL öffentlich erreichbar ist und erfolgreich antwortet (syntaktische Korrektheit allein reicht nicht aus). - **Nicht unterstütztes Datenformat** — verwenden Sie ausschließlich `JSON` oder `XML`; andere Formate werden abgelehnt. - **Der Webhook empfängt in der Sandbox nichts** — erwartete Einschränkung: die Webhook-Zustellung ist in der Sandbox-Umgebung nicht verfügbar (siehe [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Zugehörige Konfiguration Für den speziellen Fall der Weiterleitung an n8n mit einem dedizierten Connector (z. B. Zoho), siehe [api/connectors](../../api/connectors.md) und [n8n](n8n.md). --- ## Source: https://docs.popapi.io/en/api/connectors The connector API forwards a POP payload to an external service through a registered n8n webhook. Currently supports the `zoho` slug (Zoho Invoice / Zoho Books). For the `zoho` side, you don't need to build the logic yourself: an official package, [`n8n-nodes-pop-zoho`](https://www.npmjs.com/package/@getpopapi/n8n-nodes-pop-zoho), runs on your own self-hosted n8n instance, verifies the request signature, and creates the invoice/credit note in Zoho — see [guides/integrations/n8n-zoho](../guides/integrations/n8n-zoho.md) for installation. If you'd rather have sync managed directly by POP without running your own n8n instance, see [api/zoho](zoho.md). ## Endpoint - `GET /wp-json/api/v2/connector/pubkey` — RSA public key to configure the n8n node (no auth) - `POST /wp-json/api/v2/connector/{slug}` — forwards the payload (standard `X-API-Key` auth) ## What you need - `integration.use` must be `n8n-zoho` for the Zoho connector - `integration.id` — the webhook ID, from the same registry as standard webhooks, with `Connector type = n8n Connector — Zoho`, enabled ## POP-side errors | Code | Status | Cause | | --- | --- | --- | | `connector_not_found` | 404 | unknown slug in the URL | | `missing_integration_id` | 400 | `integration.id` not provided | | `connector_webhook_not_found` | 404 | no webhook registered for that `integration.id` | | `connector_webhook_disabled` | 422 | webhook disabled in the account panel | | `connector_unreachable` | 502 | the n8n webhook URL did not respond | | `connector_invalid_response` | 502 | n8n responded with non-JSON content | In `environment: sandbox` no real calls to Zoho are made and no quota is consumed. To generate SdI/PEPPOL invoices or validate VAT numbers from n8n (a different package, a different flow from this connector), see [guides/integrations/n8n](../guides/integrations/n8n.md). --- ## Source: https://docs.popapi.io/en/api/ksef Main route: `POST /wp-json/api/v2/create-ksef-xml` — generates FA(3) XML locally. With `integration.use = ksef` in the payload, it generates and sends in one step via KSeF via POP. Helper routes (connected accounts): `POST /wp-json/api/v2/ksef/document-get` (document status), `POST /wp-json/api/v2/ksef/upo-get` (UPO receipt). ## What you need - supplier with country `PL` and a valid Polish NIP - `customer_type` must be `company` or `freelance` (not `private`) - sending via KSeF via POP requires a registered legal entity and completed onboarding; on Shopify it also requires the `Basic` plan or higher (on WordPress, direct API, n8n, and MCP, sending no longer requires a paid plan, it uses available credits) ## Output - local generation: raw XML - KSeF via POP send (`integration.use = ksef`): JSON - `ksef/upo-get`: raw XML; `ksef/document-get`: JSON - errors: always JSON ## Good to know - supported payment codes: `MP01`, `MP02`, `MP03`, `MP05`, `MP08` - supported fiscal variants: standard VAT, exempt, reverse charge, intra-EU 0% (`ZERO_WDT`), export 0% (`ZERO_EXPORT`) - for credit notes, set `type = credit_note` in the shared payload - `integration.use` also accepts the alias `ksef-via-pop` - `ksef/document-get` returns the provider status (`in_queue`, `processing`, `valid`, `invalid`, `rejected`, `blocked`, `approved`, `draft`) translated into a human-readable message - main public error codes: `insufficient_level` (Shopify only, plan below `Basic`), `pop_api_ksef_legal_entity_missing` (legal entity not registered), `pop_api_ksef_onboarding_required` (onboarding incomplete), `pop_api_ksef_generation_failed` (FA(3) XML could not be generated) - `connector_exclusive_channel_active` (403) — KSeF delivery is blocked while Zoho is the account's active, connected billing channel; local XML generation is not affected --- ## Source: https://docs.popapi.io/en/api/onboarding Base path: `onboarding/v1`. A headless flow, independent of the browser/theme login, built for MCP, LLM, and external integrations. ## Flow ``` POST /request-otp → POST /verify-otp → GET /status → GET /account-setup → POST /account-setup ``` After `verify-otp`, every call requires the `onboarding_token` (header `X-Onboarding-Token` or query param `onboarding_token`), valid for 1800 seconds — it is not a permanent credential. ## Steps 1. `POST /request-otp` — validates the email, creates the account if it doesn't exist, generates an OTP. 2. `POST /verify-otp` — verifies the OTP (or admin password), returns `onboarding_token` and `next_action` (if `completed`, the account is already set up). 3. `GET /status` — current wizard state. 4. `GET /account-setup` — full payload: saved values, lookup tables, capabilities. 5. `POST /account-setup` — saves the configuration, activates SdI/PEPPOL/KSeF/ZUGFeRD based on country. ## Good to know - the flow covers variants for IT/SM (SdI), other EU countries (PEPPOL), and Germany (ZUGFeRD/PEPPOL corridor) - `configurations` returned by `GET /account-setup` only contains saved, coherent values - this same flow is also exposed as 5 MCP tools (`pop_onboarding_*`) on the [remote MCP server](../guides/integrations/mcp-remote.md), meant to be driven by an AI assistant instead of calling the routes directly — see [onboard-via-ai-assistant](../guides/getting-started/onboard-via-ai-assistant.md) - for GCC countries with no official e-invoicing network (AE, SA, BH, KW, OM, QA), the only available invoicing channel is the native Zoho connector (`configurations.connector`) — no official SdI/PEPPOL/ KSeF fiscal channel exists for these accounts - `general_store_vat_number` validates the format for IT, SM, and 33 other countries; the 422 error message includes a country-specific format example when the value doesn't match - activating an integration that doesn't match the account's country returns an explicit 422 (e.g. `active_sdipop_integration: 1` on a non-IT/SM account, `active_peppol_integration: 1` on a non-PEPPOL country, `active_ksef_integration: 1` on a country other than PL) --- ## Source: https://docs.popapi.io/en/api/overview POP Cloud API generates fiscal documents (SdI, PEPPOL, KSeF, PDF, ZUGFeRD) from a single shared payload and, when needed, delivers them through active integrations (webhook, SdI, PEPPOL, KSeF, Fatture in Cloud). ## Base URL - Production: `https://popapi.io/wp-json/api/v2/` - Sandbox (for testing, no credit consumed): `https://sandbox.popapi.io/wp-json/api/v2/` ## Authentication Header `X-API-Key: ` (preferred). Get your `license_key` from `Account > API` after activation. `license_key` in the body/query is also accepted, but deprecated. ## First steps 1. Get your `license_key`. 2. Verify it with `GET /account-profile`. 3. Send one document-generation request with a real `data` payload. 4. Add optional delivery integrations only after local generation works. ## Main endpoints | Domain | Guide | Route | | --- | --- | --- | | SdI / FatturaPA | [api/sdi](sdi.md) | `POST /create-xml` | | PEPPOL BIS / UBL | [api/peppol](peppol.md) | `POST /create-ubl` | | KSeF FA(3) | [api/ksef](ksef.md) | `POST /create-ksef-xml` | | PDF | [api/pdf](pdf.md) | `POST /create-pdf` | | ZUGFeRD / Factur-X | [api/zugferd](zugferd.md) | `POST /create-zugferd` | | Onboarding | [api/onboarding](onboarding.md) | `onboarding/v1/*` | | Connector (n8n) | [api/connectors](connectors.md) | `POST /connector/{slug}` | ## Full reference Full reference: [Postman collection](https://www.postman.com/getpopapi/pop-api-public-docs/). --- ## Source: https://docs.popapi.io/en/api/pdf `POST /wp-json/api/v2/create-pdf` generates the PDF of the shared POP payload. ## What you need - a valid `data` payload; `data.pdf` extends the payload only for rendering (billing, shipping, logo, header, footer) — it does not replace the common fiscal data - if present on both sides, `tax_regime` must match the account's - email delivery requires `data.pdf.email_invoice` with at least one recipient in `to` (max 3) ## Output - default: streamed PDF - with `data.pdf.email_invoice`: JSON (not the file stream) ## Email delivery - `to` — primary recipients, visible to each other - `bcc` — silent copy (max 3), not visible to `to`; when used, the response includes `bcc_to` alongside `sent_to` - to send an internal copy without exposing it to the customer, use `bcc` — do not add the address to `to` --- ## Source: https://docs.popapi.io/en/api/peppol `POST /wp-json/api/v2/create-ubl` generates PEPPOL BIS UBL XML from the shared POP payload. ## What you need - a valid `data` payload, authenticated license enabled - PEPPOL is a B2B corridor: the recipient must be a business entity ## Output - success: raw UBL XML - error (validation, quota, webhook, integration): structured JSON ## Delivery Generated XML can be sent to active PEPPOL integrations or to configured webhooks. ## Good to know - recipient routing does not use `sdi_type`; it is derived from VAT/registration identifiers and, when possible, PEPPOL directory lookups - `purchase_order_data.id` becomes `OrderReference` (often required to satisfy `PEPPOL-EN16931-R003` when sending to provider validation) - `connected_invoice_data.id`/`date` become `BillingReference` for credit notes - `connector_exclusive_channel_active` (403): PEPPOL delivery is blocked while Zoho is the account's active, connected billing channel; local UBL generation is not affected - `country_not_eligible_for_peppol`: the account's registered country is not a supported PEPPOL country - generating and sending via WordPress, direct API, n8n, or MCP no longer requires a paid plan: every plan, including Free, can send using its own available credits. On Shopify, sending still requires the Basic plan or higher - currently supported PEPPOL countries (28): AT, BE, BG, CY, CZ, DE, DK, EE, FI, FR, GR, HR, HU, IE, IS, LT, LU, LV, MT, NL, NO, PT, RO, SE, SI, SK, CH, GB. **Deliberately excluded**: Spain (Facturae corridor, not yet supported), Northern Ireland (not enabled in the country catalog), Liechtenstein (no configured PEPPOL endpoint identifier scheme) - **France (gov-fr, beta)**: when the transmitter country is `FR`, the request is automatically routed to the gov-fr corridor instead of generic PEPPOL: same public contract (`integration.use = peppol`), no different value to pass. The corridor has its own Legal Entity and its own error messages (`"France Legal Entity is missing."`, `"France integration is not active."` instead of the PEPPOL equivalents). The SIREN required for the Legal Entity is automatically derived from the account's French VAT number (last 9 digits); an optional `fr_siren` field in the account-setup payload lets you force a different one. Covers e-invoicing only: French e-reporting isn't implemented yet. See [france-peppol](../guides/integrations/france-peppol.md) for the activation guide. --- ## Source: https://docs.popapi.io/en/api/sdi `POST /wp-json/api/v2/create-xml` generates FatturaPA / SdI XML from the shared POP payload. ## What you need - a valid `data` payload, authenticated license enabled - if present on both sides, the payload's `tax_regime` must match the account's - recipient routing via `transmitter_data.sdi_code` or `transmitter_data.recipient_pec` ## Output - success: raw XML - error (validation, quota, webhook, integration): structured JSON ## Delivery Generated XML can be sent to active SdI integrations or to configured webhooks. ## Good to know - `purchase_order_data.id` adds `DatiOrdineAcquisto` - credit notes require `connected_invoice_data.id` and `date` - in sandbox, `invoice_number` is prefixed with `SANDBOX-` - `connector_exclusive_channel_active` (403) — SdI delivery is blocked while Zoho is the account's active, connected billing channel; local XML generation is not affected - `country_not_eligible_for_sdi` — the account's registered country is not IT or SM - generating and sending via WordPress, direct API, n8n, or MCP no longer requires a paid plan: every plan, including Free, can send using its own available credits. On Shopify, sending still requires the Basic plan or higher --- ## Source: https://docs.popapi.io/en/api/zoho The native Zoho integration is one of POP's sending channels (like SdI via POP, PEPPOL, KSeF): it syncs a document directly to Zoho Invoice or Zoho Books via OAuth, **without** going through a user-managed n8n webhook. It is a separate channel from the [generic connector](connectors.md), which instead forwards the payload to an n8n webhook that you configure and manage yourself — use this page if you need direct sync, the other one if you want to route through your own n8n workflow. ## Endpoint - `GET /wp-json/api/v2/integration/zoho/status` — connection status (region, product, org ID, token expiry, default invoice status, auto-create contacts). - `POST /wp-json/api/v2/integration/zoho/sync` — syncs a document to Zoho. - `GET /wp-json/api/v2/integration/oauth/callback` — OAuth callback used during authorization (handled automatically by the connection flow, not meant to be called manually). ## What you need - the Zoho channel activated from the POP account panel (it is one of the mutually exclusive sending channels: activating it automatically deactivates the others). - completed OAuth authorization — the `connected` state in `integration/zoho/status` must be `true` before you can sync. - No paid plan required on WordPress, direct API, n8n, or MCP: syncing uses available credits. On Shopify, the Basic plan or higher is still required. ## Good to know - every document synced in live mode consumes **1 credit**. - `zoho_product` indicates whether the account is linked to Zoho Invoice or Zoho Books. - `zoho_create_contact_if_missing` controls whether a missing Zoho contact is created automatically during sync, instead of failing. - `payment_terms` is derived automatically from `payment_data.payment_due_days`. - Fiscal/payment metadata with no dedicated Zoho field (`nature`, `ref_normative`, and key `payment_data` values) is automatically copied into the Zoho invoice `notes`. - To map those same values onto Zoho custom fields instead, pass `integration.custom_fields_map` (an object with `label` or `customfield_id` per field) — the native integration only creates documents, it doesn't update existing Zoho contacts. - **Credit notes** — require the linked order to already have a successfully synced Zoho invoice; without that reference the request fails with a 422 error ("Zoho credit notes require a Zoho parent invoice reference on the original order."). - **Sandbox** — a request with `environment: sandbox` doesn't create anything in Zoho: it returns a success response with a dry-run confirmation, without touching the real Zoho account. ## Common errors | Code | Cause | | --- | --- | | `no_connector_configured` | No native connector active on the account | | `unsupported_doc_type` | `doc_type` is not `TD01`/`TD04` | | `missing_connected_invoice` | Credit note request missing `connected_invoice_data.id` | | `tax_not_found` | An `order_items[].rate` value isn't configured in Zoho | | `contact_not_found` | Customer not found and auto-create is disabled | | `contact_ambiguous` | Multiple Zoho contacts match the same VAT/email/name | | `zoho_region_not_configured` / `zoho_organization_not_configured` | Region or Organization ID missing in account settings | | `zoho_api_error` | Generic Zoho-side error forwarded by POP | ## Related configuration For activation from the account panel and the status shown in the plugin/app, see [integrations/zoho](../guides/integrations/zoho.md). --- ## Source: https://docs.popapi.io/en/api/zugferd `POST /wp-json/api/v2/create-zugferd` generates a ZUGFeRD/Factur-X bundle from the shared POP payload. ## Output Always JSON, with three base64 attachments: - `attachments.pdf` — visual PDF - `attachments.xml` — EN16931 CII XML - `attachments.hybrid_pdf` — hybrid PDF with embedded XML ## Good to know - no outbound delivery (webhook/integrations) exists on this route - supports payload-only generation via RapidAPI (`X-RapidAPI-Key` without a POP `X-API-Key`); in this mode the payload must contain every required field explicitly - in sandbox, `invoice_number` is prefixed with `SANDBOX-` - supported fiscal variants: standard VAT, reverse charge, intra-EU 0%, export 0%, exempt, general outside-scope; not supported: OSS, margin scheme, split payment ## Consumer-side verification Use `validation.hybrid_pdf.has_embedded_xml` and `validation.hybrid_pdf.embedded_xml_matches` in the response as an immediate check that the XML is correctly embedded in the hybrid PDF. --- ## Source: https://docs.popapi.io/en/guides/changelog/shopify-app ## Where to look Unlike the WordPress plugin, the POP for Shopify app doesn't currently have a public per-version changelog: the app's listing on the Shopify App Store doesn't publish release notes. There's no self-service way to check what changed between versions — if you need to know whether a specific behavior was already fixed, or when a feature was introduced, open a support ticket with the installed version (see below). ## How to know which version you have installed The installed app version is visible on the app's **Settings** screen, along with the status of the active integrations (SdI, PEPPOL, KSeF, Zoho). ## When to contact support - If you notice a behavior you suspect was already fixed in a more recent version. - Before opening a ticket for a bug: include the installed version, it speeds up diagnosis. - After an announcement of new features (e.g. a new transmission channel or newly supported currency), to understand whether it requires a change to your configuration. ## Related configuration For configuring individual features, start from [shopify-faq](../getting-started/shopify-faq.md). --- ## Source: https://docs.popapi.io/en/guides/changelog/wordpress-plugin ## Where to look The full changelog for the WordPress plugin (version entries, generally categorized as Added, Fixed, Improved, Changed) isn't duplicated here because it changes with every release: check it directly on the **Changelog** page of the plugin listing on WordPress.org, generated from the `== Changelog ==` section of the plugin's own `readme.txt` — that's the only source that's always up to date. ## How to know which version you have installed In `wp-admin > Plugins`, the installed version is shown next to the POP plugin's name. The same version is also visible on the plugin's settings screen. ## When you should update - If you notice a behavior that the changelog indicates as already fixed in a version more recent than the one installed. - Before opening a support ticket for a bug: check that it hasn't already been resolved in a later version. For the update procedure, see the plugin's installation/update guide. --- ## Source: https://docs.popapi.io/en/guides/configuration/checkout-field-names ## Goal Know the technical names (`name`/meta key) of the fields POP adds to WooCommerce checkout, useful if you customize the theme, a custom checkout plugin, or read order meta via code. ## Fields added | Field | What it contains | | --- | --- | | `billing_choice_type` | Document choice: `receipt` or `invoice`. Visible only if the choice is enabled (see below). | | `billing_invoice_type` | Customer type: `private`, `company`, or `freelance` — fixed keys, even if you customize the labels. | | `billing_sdi_type` | A single field for **either PEC or the 7-character SDI recipient code** (these are not two separate fields). | | `billing_vat_number` | VAT number. | | `billing_tax_code` | Tax code (codice fiscale). | A format check (RegEx) is applied to the `billing_sdi_type`, `billing_vat_number`, and `billing_tax_code` fields, in addition to any required-field setting, which varies by country and customer type. ## Where visibility/labels are configured All of these behaviors are set in `POP → Electronic Invoice - Settings`, **Checkout** tab: - **Customer type list** — customizes the labels of `billing_invoice_type` (the `private`, `company`, `freelance` keys stay fixed); format: one line per entry, `key:Label`. - **Activate the choice of receipt** — shows/hides the `billing_choice_type` field. - **Disable PEC/unique code field** — hides `billing_sdi_type` (the recipient code is automatically set to `0000000`). - **Disable Fiscal Code** — hides `billing_tax_code` for companies and freelancers. - **VAT number and tax code for non-EU customers** — shows/hides these fields for non-EU customers. - **Position of the fields (e-invoice) in the checkout form** — positions the field block at the top or bottom of the form. ## Verify Inspect the checkout HTML (or the order meta in `wp-admin > Orders`) and check that the field names match exactly what's in the table. ## Common errors - **A custom plugin/theme can't find the PEC field** — it probably looks for `billing_pec`: the correct name is `billing_sdi_type` (used for both PEC and the SDI code). - **You're looking for `billing_cf`** — the actual name is `billing_tax_code`. - **The meta saved on the order doesn't match what was entered at checkout** — if you use a custom checkout plugin, compatibility with these fields isn't guaranteed: POP can't account for third-party logic that alters the order flow. ## Related configuration To add custom logic based on these fields (e.g. via the `wc_el_inv-*` hooks) see [custom-code-snippets](custom-code-snippets.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/custom-code-snippets ## Goal Add a small customization (e.g. modify a POP filter) without touching the theme's `functions.php` and without creating a dedicated plugin. ## Prerequisites - Administrator access to `wp-admin`. - A valid PHP snippet to insert (written by you or provided by POP support). ## Steps 1. Install the free **Code Snippets** plugin from `wp-admin > Plugins > Add New`, then activate it. 2. In the side menu, open **Snippets > Add New**. 3. Give it a descriptive title (e.g. "POP - disable invoice number for payment method X"). 4. Paste the PHP code into the dedicated area. **Do not** include the ` Require all denied Deny from all ``` This blocks direct browser access on **Apache** servers. The file is generated automatically on the first write to each folder: you don't need to create it by hand. ## Protection on NGINX (requires manual setup) On **NGINX** servers (e.g. Kinsta, WPEngine, a VPS running NGINX) `.htaccess` directives aren't read: you need an equivalent rule in the site configuration, for example: ``` location ~ ^/wp-content/uploads/pop-(pdf|xml|ubl|ksef|zugferd|invoice)/.*$ { return 403; } ``` After adding it, restart NGINX to apply it. ## Verify Try opening the URL of a generated file directly in the browser (e.g. `https://yoursite.com/wp-content/uploads/pop-pdf/2026/07/document.pdf`): it should return a **403 (access denied)** error, not the file. ## Common errors - **The file is publicly downloadable on NGINX** — the `.htaccess` generated by POP has no effect on NGINX: you need the manual `location` rule above, applied by your hosting/provider. - **You don't know whether your hosting uses Apache or NGINX** — ask your provider: the difference completely changes the protection method to apply. - **The `pop-invoice` folder is empty** — this is normal if you haven't enabled the optional local storage setting in **Advanced**: downloads from the Invoices tab still use the `pop-xml`/`pop-pdf` cache regardless. ## Related configuration For the format and limits of the generated XML, see [xml-invoices-generated](../getting-started/xml-invoices-generated.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/import-export-settings ## Goal Replicate POP's configuration (settings saved in the General, Numeration, Documents, etc. tabs) on another WordPress installation, without manually re-entering every field. ## Prerequisites - Administrator access to both installations (source and destination). - POP installed and active on both. ## Steps 1. On the **source** installation, go to `POP → Electronic Invoice - Settings`, **Advanced** tab, **Import/Export** section (also reachable from the link in the tab's internal navigation bar). 2. Copy the entire contents of the **Export options** field (read-only): it's a serialized snapshot of the plugin's current options. 3. On the **destination** installation, open the same **Advanced > Import/Export** tab. 4. Paste the copied text into the **Import options** field. 5. Save the page (the Advanced tab's save button). ## Verify After saving, reload the tab and check that the values in the other tabs (General, Numeration, Documents...) match those on the source installation. ## Common errors - **The settings don't change after importing** — make sure you saved the page (pasting the text alone isn't enough): saving only happens on submitting the Advanced tab's form. - **Some "premium" settings (credit note numbering, etc.) stay locked after the import** — if the destination account's plan doesn't enable them, the imported values for those fields are ignored. - **You want to copy only some settings, not all of them** — import/export replaces the entire text collection of options: it isn't designed for a selective merge of individual fields. - **Account-specific data** (license, POP account ID) — import/export covers the plugin's locally saved options; the license and account connection stay tied to each installation and still need to be completed with the wizard, see [first-installation](../getting-started/first-installation.md). ## Related configuration For the update procedure, see [update-plugin](update-plugin.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/invoice-numbering-and-order-status ## Goal Understand exactly when POP assigns the invoice number and when it generates the XML, to avoid mismatches between document numbering and dates. ## When the invoice number is assigned The number is assigned the **first time the order moves** to **"Processing"** or **"Completed"** status (whichever comes first). From that point on, the order already has a sequential number, even if the document hasn't been sent to the customer yet. ## When the XML is generated By default, the XML is generated when the order reaches **"Completed"** status (this behavior can be customized via a filter for developers, not through a UI setting). For **refunds**, POP automatically generates the credit note XML the moment the refund is registered in WooCommerce — no manual action is needed just to generate the document. > If you use an add-on that transmits to an external accounting software (e.g. Fatture in Cloud, Aruba), > **sending** to the external software may still require a manual upload from the "Invoices" tab > depending on the add-on's configuration: check the specific behavior in the active add-on's > configuration, since it can differ from what's described here for the native flow. ## The invoice date depends on when it's sent This is the point that causes the most confusion: - If the invoice is sent **while the order is still "Processing"**, the document date stays the date of the move to Processing. - If it's **not sent** while the order is "Processing" and is only sent once the order is completed, the date updates to the day of completion. **Mismatch example:** 1. 01/04 — Order #101 moves to Processing → invoice no. 1 generated, not yet sent. 2. 01/07 — Order #102 moves to Processing → invoice no. 2 generated **and sent** dated 01/07. 3. 03/04 — Order #101 is completed and invoice no. 1 is only sent now → the date updates to 03/04. Result: invoice no. 2 has a date (01/07) earlier than invoice no. 1 (03/04), even though it has a lower number. ## Verify Before sending invoices in bulk, check in the **Invoices** tab that numbering and dates are consistent (increasing number = increasing date). ## Common errors - **Numbering and dates out of chronological order** — avoid leaving orders "Processing" for a long time before sending the invoice; if you know an order will stay in Processing for a while, consider not moving it to that status until you're ready to handle it. - **The refund XML doesn't show up** — check that the refund was actually registered in WooCommerce (not just an external refund noted separately). - **The XML doesn't reach the external accounting software connected via add-on** — document generation and sending it to the external software are two separate steps when an add-on is active: check whether a manual upload is needed. ## Related configuration For the credit note and its requirements, see [credit-note-generation](../troubleshooting/credit-note-generation.md); for where/how the XML files are stored, see [generated-files-storage](generated-files-storage.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/order-completed-emails ## Goal Manage the automatic emails POP adds to WooCommerce's transactional emails, each with a different document attached. ## What the plugin adds POP registers **3 additional emails** in WooCommerce's email list (`WooCommerce > Settings > Emails`), all triggered when the order moves to **"Completed"** status: | Email | Attachment | | --- | --- | | Send Invoice XML on order completed | XML invoice | | Send Invoice PDF on order completed | PDF invoice | | Send Receipt PDF on order completed | PDF receipt | Each one is a standalone WooCommerce email: you can enable/disable it and customize its subject/heading independently of the others, exactly like WooCommerce's standard emails (new order, order completed, etc.). ## Prerequisites - WooCommerce with working transactional emails (SMTP configured if needed). - The order must have a total different from zero: if you've enabled the option that blocks invoicing on zero-amount orders, these orders won't generate a number or attachments. ## Steps 1. Go to `WooCommerce > Settings > Emails`. 2. Find the three entries listed above among the available emails. 3. Enable the ones you need and customize the subject/heading if necessary. 4. Save. ## Verify Generate a test order and move it to "Completed": you should receive (or see in the log/email queue) the enabled emails, each with its respective attachment. ## Common errors - **The customer receives the wrong document or no attachment** — check that the specific email is enabled in `WooCommerce > Settings > Emails` and that the document (XML/PDF) was actually generated for that order. - **You also want to attach a pro-forma invoice to the standard order-completed email (not these 3 dedicated emails)** — that's a separate option, see [pro-forma-invoice-email](pro-forma-invoice-email.md). - **The emails don't send at all** — first check that WooCommerce can send emails in general (an SMTP delivery issue, not specific to POP). ## Related configuration For sending the pro-forma invoice/receipt via WooCommerce's standard order-completed email, see [pro-forma-invoice-email](pro-forma-invoice-email.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/pro-forma-invoice-email ## Goal Automatically attach the PDF (invoice or receipt, depending on the customer's choice) to WooCommerce's standard "order completed" email. ## Prerequisites - WooCommerce with the "order completed" email active. ## Steps 1. Go to `POP → Electronic Invoice - Settings`, **Documents** tab, **PDF Documents** section. 2. Enable the **Proforma invoice via email** option ("Active the sending of the invoice/receipt in PDF format via e-mail upon completion of the order"). 3. Save. From this point on, the PDF is attached to WooCommerce's order-completed email when the order reaches that status. ## Verify Complete a test order and check that the "order completed" email arrives with the PDF attached. ## Common errors - **The PDF is no longer attached after enabling "Generate proforma in HTML"** — this is expected behavior, not a bug: the HTML option (intended only as a fallback for when PDF generation has issues) shows the document in HTML format but **doesn't attach it** to the email. If you need the PDF attachment, don't enable this option together with "Proforma invoice via email". - **The attachment is missing only for some orders** — check that the order actually reached "Completed" status and that it isn't a zero-amount order (if you've enabled the invoicing block for zero-amount orders). - **You also want a separate dedicated email with just the XML or just the PDF invoice** — those are distinct WooCommerce emails, see [order-completed-emails](order-completed-emails.md). ## Related configuration For the three dedicated emails with XML/PDF invoice/PDF receipt, see [order-completed-emails](order-completed-emails.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/reverse-charge ## Goal Correctly apply (or remove) VAT on the invoice based on the customer's country/type, for sales abroad (EU and non-EU). ## Prerequisites - A POP plan that includes reverse charge (a paid feature: without an enabled plan the fields stay visible but disabled). - VAT rates configured in WooCommerce (`WooCommerce > Settings > Tax`) — a step not handled by POP but necessary for everything to work. ## Steps 1. Go to `POP → Electronic Invoice - Settings`, **Checkout** tab, **Reverse Charge** section. 2. Enable **"Activate reverse charge (globally)"** (or activate it per product, if you'd rather not apply it globally). 3. Enable **"Activate VIES validation"**: this is a **required** step, not optional — reverse charge won't activate without VIES validation of the customer's VAT number. If your hosting can't validate the VAT number, check that the `SoapClient` PHP extension is enabled on the server (ask your hosting provider). 4. In **"Tax classes"**, select the zero-rate tax class to use for reverse charge: POP automatically detects, among the tax classes configured in WooCommerce, those with a 0% rate (usually the class is called "Zero rate", but the name isn't binding: what matters is the rate). 5. Set the nature code and regulatory reference for each of the 5 handled scenarios: **EU individuals**, **EU companies with validated VIES**, **EU companies without validated VIES**, **non-EU individuals**, **non-EU companies**. Check with your accountant for the correct values case by case. 6. If you use an add-on that transmits to an external accounting software, make sure the same nature codes are also configured in that software. ## Verify Make a test purchase with a real, valid EU VAT number: if everything is configured correctly, VAT is removed from the cart and the invoice shows the nature code expected for the corresponding scenario. ## Common errors - **The site can't validate the customer's VAT number** — likely a server-side issue: check that `SoapClient` is available (needed to query the VIES service). - **Reverse charge doesn't activate even though you've checked it** — check that "Activate VIES validation" is also enabled: without VIES, reverse charge stays inactive by design. - **You can't find a zero-rate tax class to select** — the menu only shows classes with a 0% rate actually configured in WooCommerce: create one in `Settings > Tax` if it doesn't exist yet. ## Related configuration For the table of nature codes to apply based on the seller's tax regime, see [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-auto-email-invoice ## Goal Enable automatic email delivery of the PDF invoice, understand which address it is sent from, and where the customer's replies go. ## Prerequisites - A paid plan (Basic or higher): automatic sending is not available on the Free plan. - Access to **Settings** in the POP for Shopify app. ## Steps POP has two distinct email settings, which are not interchangeable: 1. **Automatic invoice email** (card "Automatic invoice email") — if enabled, POP sends the PDF to the order's email address every time a document is generated, whether manually from the Orders app or automatically. Here you can also set: - **Reply-to email address** — the address that receives the customer's replies (it is not fixed: it is configurable per store). - **Merchant copy email address** — if set, every send (manual or automatic) also sends a BCC copy to this address, invisible to the customer. 2. **Automatic PDF email on payment** (separate card) — controls whether, when an order is paid, the PDF is automatically sent to the customer and/or in copy to the merchant. The toggle for the merchant requires that the copy email address above is already configured. ## Verify - Generate a document from a test order and check that the PDF arrives at the email address associated with the order. - Reply to the email you received and verify that the reply reaches the address set in **Reply-to email address** (if not set, the email is still sent from `noreply@popapi.io`). - If you set the merchant copy email address, check that every send also produces a BCC to that mailbox. ## Common errors - **The customer doesn't receive the PDF** — check that you are on a paid plan and that **Automatic invoice email** (or **Automatic PDF email on payment**, depending on the trigger) is enabled. - **The customer's replies get lost** — set **Reply-to email address**: by default emails are sent from `noreply@popapi.io`, an unmonitored address. - **The merchant doesn't receive the copy** — check that **Merchant copy email address** is filled in; without that value, the "copy to merchant" toggle in the automatic send on payment has no effect. ## Related configuration To customize the content of the PDF itself (footer, logo), see [shopify-customize-invoice-pdf](shopify-customize-invoice-pdf.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-bank-transfer-payment ## Goal Automatically show bank details on the generated document when the order's payment method is a bank transfer. ## Prerequisites - Access to **Settings > Bank transfer payment** in the POP for Shopify app. ## Steps 1. Fill in **Beneficiary** with the same name present in Shopify's payment settings. 2. Fill in **Bank name** and **IBAN**. 3. Optional: set **Payment due (days)** (e.g. 30) to indicate the bank transfer due date on the invoice. POP automatically detects whether an order was paid by bank transfer (based on the Shopify payment method or gateway used at checkout) and, only in that case, inserts the configured beneficiary, bank, and IBAN into the XML and PDF, for SdI and PEPPOL. For orders paid with other methods (card, PayPal, cash on delivery, direct debit...) these fields are not inserted. ## Verify - Generate a document for an order paid by bank transfer and check that the beneficiary, bank, and IBAN appear in the payment section of the PDF/XML. - Generate a document for an order paid by card and verify that these fields do not appear. ## Common errors - **Bank details don't appear on an order paid by bank transfer** — check that the Shopify payment gateway/method used is actually recognized as bank transfer; custom payment methods with non-standard names might not be detected. - **The data appears on an order paid differently** — this shouldn't happen: check the order's actual payment method in Shopify Admin. ## Related configuration For the payment block contract in the payload, see [api/sdi](../../api/sdi.md) and [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-checkout-vat-tax-code-fields ## Goal Configure whether and when to request the VAT number and Tax Code from customers at checkout, distinguishing between EU and non-EU customers. This section applies to **Shopify Plus** stores only: on non-Plus stores, fiscal fields are added to the cart via an embed script, with a separate configuration (see [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Prerequisites - A store on **Shopify Plus** (the **Settings > Checkout** section isn't visible on non-Plus plans, since it controls a Checkout UI Extension only available on Plus). ## Steps In the **Checkout** section: 1. **VAT number and tax code for EU customers** — choose whether to make the fields **required** (useful for B2B or when full fiscal data is needed) or **not required** (simpler checkout). 2. **VAT number and tax code for non-EU customers** — choose whether to **show** the fields (for fiscal needs or manual checks) or **not show them** (if not relevant for VAT purposes). These two toggles control only the Shopify Plus Checkout UI Extension. On non-Plus stores, required/ optional fields are configured separately in the embed script (see [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Verify - From a test store, start a checkout with an EU billing address and verify that the VAT/tax code field is required or optional according to the setting. - Repeat with a non-EU address and verify that the fields appear or not according to the setting. ## Common errors - **Italian customers still see Shopify's native Tax Code/PEC fields** — these are fields natively applied by Shopify for Italy and cannot be removed or modified by POP; they are optional regardless. Disabling them requires a specific request to Shopify support. - **The fields don't appear at all at checkout** — check that the Checkout Extension is active. On non-Plus stores, this settings section isn't even visible: use the cart embed script instead (see [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Related configuration For how this data is then read and prioritized by POP during invoicing, see [shopify-fiscal-data-management](shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-customize-invoice-pdf ## Goal Customize the appearance of the invoice PDF generated by POP: footer text, logo, and (optionally) the name of the downloaded file. ## Prerequisites - A paid plan: PDF customization is not available on the Free plan. - Access to **Settings > PDF customization** in the POP for Shopify app. ## Steps 1. **Footer text** — enter legal notes, bank details, or useful links to show at the bottom of the PDF. 2. **Invoice logo** — upload an image to show at the top of the PDF: - accepted formats: **PNG, JPG, or SVG**; - for PNG/JPG: **maximum 600px** per side and **maximum 500KB**; - after uploading, the logo URL appears in the "Logo URL" field (you can also remove it with **Remove logo**). 3. **Use invoice number for PDF filename** (optional toggle) — if enabled, the download/email file name uses VAT number + invoice number; the internal storage key stays unchanged. ## Good to know - **Document title language** — the "Invoice"/"Credit note" title on the PDF automatically follows the customer's Shopify locale (German, English, Spanish, French, French-Belgium, Italian, or Dutch), not the merchant's country. If the customer's locale isn't one of those, the title falls back to English. This isn't configurable — it's automatic on every document. ## Verify - Generate a test document and check that the footer and logo appear in the PDF. - If you enabled the filename toggle, download the PDF and verify that the name contains the VAT number and invoice number. ## Common errors - **"Upload a PNG, JPG or SVG image."** — the uploaded file is not in one of the accepted formats. - **"Logo must be smaller than 500KB."** — compress the image before re-uploading it. - **"Logo must be at most {max}px on each side."** — resize the PNG/JPG within the indicated limit before uploading. - **I don't see these options** — PDF customization requires a paid plan. ## Related configuration For automatic sending of the customized PDF, see [shopify-auto-email-invoice](shopify-auto-email-invoice.md). For the PDF document format, see [api/pdf](../../api/pdf.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-file-progressive-number ## Goal Understand what the "document progressive" is and manage its reset (automatic or manual), separately from the legal invoice number. ## Prerequisites - Access to **Settings > Document progressive** in the POP for Shopify app. ## What it is The document progressive is the counter used in the name of the XML/PDF file generated by POP — it is not the legal invoice number (for that, see [shopify-invoice-numbering](shopify-invoice-numbering.md)). It matters most for sending to SdI, which requires file names with ordered progressives; for PEPPOL it is not mandatory but it is still recommended to keep it ordered for administrative consistency. ## Steps In the **Document progressive** card: 1. **Automatic reset at year change** — if enabled, the counter restarts from `00001` on the first document generated in the following year. 2. **Reset progressive now** — immediate manual reset, useful after a migration or after testing in sandbox. Use it only after you have sent all the documents for the previous year. The card always shows the current status ("Current state: year {year}, counter {counter}") and the date of the last reset. ## Verify - After a manual reset, generate a new document and check that the counter in the file name restarts from `00001`. - With automatic reset enabled, verify that the first document generated in the new calendar year restarts from `00001` without manual action. ## Common errors - **"Reset the document progressive for {year} in Settings before generating new files."** — POP blocks generation because the current year's progressive has not yet been initialized/reset: go to Settings and run **Reset progressive now**. - **The progressive doesn't reset in January** — check that **Automatic reset at year change** is enabled; if disabled, the counter keeps incrementing past the year change. - **Confusion with the invoice number** — if the number you see on the invoice doesn't change after a reset here, you are probably looking for the wrong setting: the invoice number is configured separately in [shopify-invoice-numbering](shopify-invoice-numbering.md). ## Related configuration See [api/sdi](../../api/sdi.md) for the file naming requirements required by the Sistema di Interscambio (SdI, Italy's e-invoicing exchange system). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-fiscal-data-management ## Goal Understand where POP reads the customer's fiscal data from (customer type, VAT number, Tax Code, PEC) and where to manually correct it before invoicing. ## Prerequisites - Access to Shopify Admin (order and/or customer). ## Steps POP uses two mechanisms for the customer's fiscal data on an order: 1. **Order metafields `app.pop_*`** — structured fields automatically created by POP (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), populated from checkout (Checkout Extension on Shopify Plus, embed script on non-Plus) or from automatic detection from customer data. If pinned in Shopify Admin, they are visible and editable directly by the operator. 2. **Order customAttributes** ("Additional details") — legacy, unstructured mechanism, used as a fallback when the corresponding metafields are not set. **Priority**: when POP generates a document, it first reads the order `app.pop_*` metafields; it falls back to customAttributes only if the corresponding metafields are absent. The **customer** metafields (same namespace/keys) store the same data on the customer profile to prefill subsequent checkouts. ### Fixing a fiscal data point before invoicing 1. Open the order in Shopify Admin. 2. Edit the relevant `app.pop_*` order metafield (it must be pinned to be visible). 3. Save: the next generation will immediately use the updated value. If the metafields have not been created (e.g. the POP wizard/license is not completed), the app shows a recovery section on the Home page with a button to recreate them manually. ## Verify - Generate a document for an order with the `app.pop_vat` metafield set to a value different from the corresponding customAttribute: the document must use the metafield value. - After editing a pinned order metafield, regenerate the document and verify that the new value was used. ## Common errors - **I don't see fiscal fields on the order or the customer** — check that the POP wizard/license are completed and that the `pop_*` metafields have been created; if missing, use the recreation button from the Home page. - **I fixed the customAttribute but the invoice doesn't change** — order metafields always take priority: fix the metafield, not the customAttribute. - **Non-Plus store, POS, or manual orders** — on these channels the data might not be collected at checkout: it must be entered manually into the order metafields before invoicing (see [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md) for collection via the theme). ## Related configuration For the **customer's** billing address on a specific order, see [shopify-billing-address-override](../troubleshooting/shopify-billing-address-override.md). For the **seller's** address, see [shopify-seller-fiscal-data](shopify-seller-fiscal-data.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-invoice-numbering ## Goal Configure the invoice number sent in SdI and PEPPOL documents: digits, yearly reset, prefix, suffix, and starting number. ## Prerequisites - Access to **Settings > Invoice numbering** in the POP for Shopify app. ## Steps In the **Invoice numbering** card: 1. **Number of digits** — set the numeric padding (e.g. `4` → the number 13 becomes `0013`). 2. **Reset the numbers at each year change** — if enabled, the counter restarts from 1 on January 1st. 3. **Prefix invoice** — text before the number (e.g. `POP-0013`). 4. **Suffix** — text after the number (e.g. `0013-A`); automatically disabled if you use the year as a suffix. 5. **Set the year as a suffix** — adds the year to the number (e.g. `0013/2025`), with a short (`/YY`) or long (`/YYYY`) format of your choice. In the **Next available number** sub-section you can manually set the next invoice number and the reference year of the progressive (useful after a migration or to align with a numbering already in use elsewhere) and confirm with **Apply manually**. ## Verify - Generate a test document (in sandbox, see [use-sandbox-environment](../configuration/use-sandbox-environment.md)) and check that the invoice number respects the configured digits, prefix, and suffix. - After manually setting the number, the first document generated must use exactly that number. ## Common errors - **"Invoice numbering error: {message}"** — invoice number generation failed on POP's side; retry, and if it persists check that there isn't a recently set inconsistent manual number. - **The number doesn't reset at the new year** — check that **Reset the numbers at each year change** is enabled; this setting is independent from the [file progressive](shopify-file-progressive-number.md) reset. - **Confusing this numbering with the "file progressive"** — invoice numbering is the document's legal number (SdI/PEPPOL); the file progressive is a separate counter used only in the generated file's name. See [shopify-file-progressive-number](shopify-file-progressive-number.md). ## Related configuration For the invoice number fields contract in the payload, see [api/sdi](../../api/sdi.md) and [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-non-plus-billing-fields ## Goal Add POP's fiscal fields (customer type, VAT number, Tax Code, PEC/SDI) to the cart and/or cart drawer on a **non-Plus** Shopify store (Basic/Grow/Advanced), without a Checkout UI Extension. ## Prerequisites - Non-Plus Shopify account. - Access to the theme code (`theme.liquid` or the cart section). ## Steps 1. Paste the `pop-noplus-embed.js` script (provided by POP, loaded from `pub.popapi.io`) just before `` in `theme.liquid`, or in the cart section/template, **preceded** by the `window.POP_EMBED_CONFIG` block with your parameters. 2. Full example configuration for an EU store (`mode: 'peppol'`), with custom text: ```html ``` 3. Save the theme. Key config options: **mode** (`'sdi'` Italy — Tax Code required for private customers, validates PEC/SDI; `'peppol'` EU — hides PEC/SDI, Tax Code not required; `'ksef'` Poland — VAT/NIP; `'zugferd'` Germany — hides PEC/SDI and Tax Code, VAT only for companies), **scope** (`'b2b'` forces "company"; `'b2b+b2c'` shows the private/company/freelance selector), **cartContainerSelector** / **drawerContainers** / **insertMode** (where/how fields are inserted), **toggle** (show/hide a link to open the fields), **prefill** (initial values from `cart.attributes`, falling back to customer metafields `customer.metafields.app.pop_*`), and **taxCodeOptOut** (checkbox for `sdi` mode only, enabled by default — see below, its built-in default text is Italian-only). ## Customizing text (`labels`) Every visible label can be overridden via `labels: {...}` — omit a key to keep its default (in English, except `toggle.label` and `taxCodeOptOut.label`/`note`, whose built-in defaults are already in Italian): | Key | Default | Controls | | --- | --- | --- | | `title` | "Electronic invoicing details" | Heading of the fields block | | `customerType` | "Customer type" | Label of the customer-type select | | `private` / `company` / `freelance` | "Private" / "Company" / "Freelance" | Customer-type select options | | `vat` | "VAT number" ("VAT/NIP" in `ksef` mode) | VAT number field label | | `taxCode` | "Tax code" | Tax Code field label (`sdi` mode only) | | `pec` | "PEC or Recipient code" | PEC/SDI field label (`sdi` mode only) | | `vatPlaceholder` | `IT12345678901` (`PL1234567890` in `ksef`, `DE123456789` in `zugferd`) | VAT field placeholder | | `taxPlaceholder` | `RSSMRA80A01H501Z` | Tax Code field placeholder | | `pecPlaceholder` | `you@pec.it / Z4G7P1Q` | PEC/SDI field placeholder | | `errorVat`, `errorTax`, `errorRequiredVat`, `errorPec` | English validation messages | Per-field validation error text | | `globalError` | "Complete billing details to proceed to checkout." | Message shown when checkout is blocked for missing data | ## Alternative without an external script If you'd rather have a self-contained form (inline HTML+CSS+JS, no external script from `pub.popapi.io`), ready-to-copy drop-in snippets are available, one per mode, in the public [`pop-snippets-library`](https://github.com/getpopapi/pop-snippets-library/tree/main/shopify/non-plus) repository: `cart-attributes-for-sdi.liquid`, `cart-attributes-for-peppol-b2b.liquid`, and `cart-attributes-for-peppol-b2b-b2c.liquid`. They cover fewer cases (no dedicated `zugferd`/`ksef` support) but don't require managing `POP_EMBED_CONFIG`. ## Verify 1. Add a product to the cart. 2. Open the cart page (or the cart drawer, depending on where you inserted the containers). 3. Fill in the fields (e.g. VAT number). 4. Proceed to checkout. 5. Check that POP receives the data when the invoice is generated (see [shopify-fiscal-data-management](shopify-fiscal-data-management.md) for where to verify it on the order). ## Common errors - **The fields don't appear on a page** — if the indicated CSS container (`cartContainerSelector` or `drawerContainers`) doesn't exist on that page, the script simply shows nothing: it is not an error, check the selector. - **Switching from "company" to "private" doesn't clear the fields** — this is expected behavior only if the change isn't intercepted: in `peppol`/`zugferd` switching to "private" clears the VAT number, in `sdi` it also clears PEC/SDI, immediately syncing the cart attributes. - **Shopify Plus stores** — no need to modify the theme: use POP's native Checkout Extension instead of the embed script. ## Related configuration On non-Plus stores, required/optional fields are configured here in the embed script (`customerOptions`, `taxCodeOptOut`), not in **Settings > Checkout** (that section applies to Shopify Plus only, see [shopify-checkout-vat-tax-code-fields](shopify-checkout-vat-tax-code-fields.md)). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-order-metafields-reporting ## Goal Make POP's invoice number, credit note number, and delivery status readable by third-party Shopify reporting apps (e.g. Report Pundit), without manual exports or the paid "POP to Webhook" integration. ## What you need - No configuration: the metafields are created automatically the first time the POP app loads after the update (works on existing installations too). - To read them from a third-party app (e.g. Report Pundit): map the following metafields in that app's configuration. ## Available metafields All under the `app` namespace, natively visible on the Shopify Admin order page (they're pinned): | Key | Type | Content | | --- | --- | --- | | `app.pop_fattura_numero` | text | Invoice number (e.g. `0787/2026`) | | `app.pop_fattura_status` | text | Active channel status for the invoice (e.g. `RC`, `MC`, `NS`, `sent`, `valid`) | | `app.pop_nota_credito_numero` | JSON | `{ "": "" }`, one entry per credit note on the order | | `app.pop_nota_credito_status` | JSON | `{ "": "" }`, same schema | ## Good to know - The invoice number is published **independently** of delivery through an official channel (SdI, PEPPOL, etc.): PDF-only stores or markets with no official channel still get the metafield populated. - If the status becomes `NS` (not deliverable), the invoice number stays unchanged: only the status changes. - An order can have multiple credit notes (multiple refunds): each credit note gets its own entry in the JSON, keyed by refund id. ## Verify 1. Generate an invoice (or credit note) on a test order after the update. 2. Open the order in Shopify Admin: `app.pop_fattura_numero` and `app.pop_fattura_status` should appear in the metafields section, with the expected values. 3. Configure your reporting app to read these metafields on the order. ## Common errors - **Old orders don't have the metafield populated**: expected, metafields are only populated by invoices generated after the update, not retroactively. For a specific order, regenerate the document to make it appear. - **Metafields don't appear at all on the order page**: reopen the POP app from Shopify Admin, the metafield definitions are created the first time it loads after the update. ## Related configuration To understand when POP actually generates the invoice or credit note on Shopify, see [shopify-faq](../getting-started/shopify-faq.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-reverse-charge ## Goal Configure the exemption/VAT nature codes for reverse charge, for each of the customer categories managed by POP. ## Prerequisites - Access to **Settings > Reverse Charge** in the POP for Shopify app. ## Steps POP manages reverse charge for five customer categories, each with a pair of fields: **Type** (nature code for SdI, e.g. `N2.1`, or VATEX code for PEPPOL depending on the sending channel) and **Description** (reason for the exemption): 1. EU Private 2. EU Business (VAT validated by VIES) — SdI/PEPPOL 3. EU Business (VAT not validated by VIES) — SdI/PEPPOL 4. Non-EU Private 5. Non-EU Companies — SdI/PEPPOL For stores sending to KSeF, the Type field for the EU/non-EU categories shows a hint of the accepted value (`zero_wdt` for EU, `zero_export` for non-EU). 1. For each category, fill in **Type** and **Description** according to the applicable tax regime. 2. Save the settings: they will be used automatically when generating a document based on the channel (SdI, PEPPOL, or KSeF) and the customer type/country detected on the order. ## Verify - Generate a test document for an order with a VIES-validated EU business customer and check that the XML/PDF report the nature code and description configured for that category. - Repeat for a non-EU private customer and verify the corresponding category. ## Common errors - **PEPPOL doesn't send to private customers** — regardless of the reverse charge codes configured, automatic PEPPOL sending always skips private customers (B2C); the PDF download remains available as a courtesy document. - **The code doesn't match what SdI/PEPPOL expects** — check that you used the correct format for the active channel (SdI nature vs. PEPPOL VATEX): the same Type field is interpreted differently depending on the sending channel. ## Related configuration For the VAT exemption fields contract in the payload, see [api/sdi](../../api/sdi.md) and [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-seller-fiscal-data ## Goal Replace Shopify's default billing address with the seller's correct fiscal data in the documents generated by POP (PDF, SdI XML, PEPPOL UBL). ## Prerequisites - Access to **Settings > Seller billing details** in the POP for Shopify app. ## Steps Fill in all fields in the **Seller billing details** section: - Billing email - Phone - Address (line 1) and optionally line 2 - ZIP / Postal code - City - Province (2-letter ISO code) - Country (2-letter ISO code) The override activates only if **all** required fields are filled in: the card shows an **"Override active"** badge when the configuration is complete, **"Override incomplete"** otherwise. If even a single field is missing, POP uses the billing address configured on Shopify in its place (field by field: a missing value here doesn't blank out the others, it always falls back to the corresponding Shopify data). ## Verify - With all fields filled in, generate a test document and check that the issuer address in the PDF/XML matches the data entered here, not the Shopify store's. - Clear a single field (e.g. City) and verify that the next document uses the Shopify value only for that specific field. ## Common errors - **The document still shows the Shopify address** — check the badge: if it shows "Override incomplete" at least one required field is missing. - **Province or Country rejected** — they must be entered as a 2-letter ISO code (e.g. `MI`, `IT`), not spelled out. ## Related configuration This setting only concerns the **seller/issuer** address. For the **customer's** fiscal data (VAT number, Tax Code, customer type) see [shopify-fiscal-data-management](shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/shopify-zero-amount-orders ## Goal Configure how POP handles Shopify orders with a zero total (100% discounts, coupons, free gift items) to avoid unnecessary invoices or wasted numbering. ## Prerequisites - Access to **Settings > Documents** in the POP for Shopify app. ## Steps In the app's **Documents** section, two independent options are available: 1. **Disable document** — if enabled, when the order total is zero POP generates neither the document nor an invoice number for that order. 2. **Remove products** — removes only the zero-total lines from the invoice (e.g. free gifts, 100%-discount items), keeping the document for the rest of the order. The two options are independent: you can enable both, either one, or neither. ## Verify - With **Disable document** enabled, a zero-total order shows the message "Order total is 0. Document generation is disabled." in the Orders table, and the generation buttons remain inactive for that order. - With **Remove products** enabled, generate a document on an order with at least one zero-price line and verify that line doesn't appear in the resulting PDF/XML. ## Common errors - **The document isn't created and I don't understand why** — check whether **Disable document** is enabled: this is the expected behavior for zero-total orders, not an error. - **Free gift lines still appear on the invoice** — check that **Remove products** is enabled; if disabled, all lines (even zero-price ones) remain on the invoice. ## Related configuration See [shopify-invoice-numbering](shopify-invoice-numbering.md) to understand how invoice numbering behaves when a document is skipped due to a zero total. --- ## Source: https://docs.popapi.io/en/guides/configuration/tax-regime-invoicing-rules ## Goal Get oriented on how VAT treatment on the invoice changes based on the tax regime set in the **General** tab and on the customer type. > The examples are illustrative: the configuration of VAT natures and regulatory references should > always be confirmed with your accountant, since it varies based on the regime, the type of operations, > and the sales channel. ## Rule verified in the plugin: Forfettario/Minimi and WooCommerce taxes If the tax regime set is **RF19 (regime forfettario** — Italy's flat-rate tax scheme for small businesses**)** or **RF02 (regime dei minimi** — the earlier "minimum taxpayers" scheme**)**, WooCommerce taxes must stay **disabled** (`WooCommerce > Settings > Tax`). If you leave them active, the plugin raises a warning in `wp-admin`: with taxes active under these regimes, the resulting orders are inconsistent with the selected tax regime, risking invalid invoices. ## Reference by customer type | Customer | Ordinary regime | Forfettario/Minimi regime | | --- | --- | --- | | Italian (Company or Individual) | 22% VAT | No VAT — nature **N2.2** | | EU company, VIES-registered | Reverse charge — nature **N2** (art. 7-ter) | No VAT and no reverse charge — nature **N2.2** | | EU individual or EU company not VIES-registered | Standard Italian VAT | No VAT — nature **N2.2** | | Non-EU company | Not subject — nature **N2** (art. 7-quater) | No VAT — nature **N2.2** | | Non-EU individual | Not subject — nature **N2** (art. 7-quater) | No VAT — nature **N2.2** | For EU companies/individuals, the e-invoice must also include the recipient code (7 Xs by default if missing), the customer's country code, VAT number (or `9999999999` if unavailable for individuals), and postal code (`00000` if unavailable) — the tax code (codice fiscale) should not be entered for foreign customers. ## OSS regime for intra-EU B2C sales Only for those on the **Ordinary regime**: once you exceed the €10,000/year threshold for intra-EU B2C sales, you need to register for the OSS (One Stop Shop) regime and apply the VAT rate of the customer's country, with nature code **N7**. Those on the regime forfettario don't apply OSS: it always stays **N2.2**. ## Verify Generate a test order for each scenario relevant to your store (e.g. EU customer with/without VIES) and check that the nature and regulatory reference on the invoice match the table agreed with your accountant. ## Common errors - **Notice "For RF19/RF02 (Forfettario/Minimi), taxes must be disabled"** — disable taxes in WooCommerce: this is a requirement, not a suggestion, for these two regimes. - **Wrong nature code for an EU customer** — check whether the VAT number is VIES-validated: this changes the nature to apply (N2 vs N2.2 depending on the regime, but with different VIES/non-VIES conditions). - **You need to apply reverse charge** — see [reverse-charge](reverse-charge.md) for how to configure it operationally in POP. ## Related configuration For the technical activation of reverse charge, see [reverse-charge](reverse-charge.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/transmitter-data ## Goal Fill in, if needed, the **transmitter** data: the party that physically sends the XML file to the Sistema di Interscambio (SdI), which can be the company itself or an intermediary acting on its behalf. ## Prerequisites - Initial setup wizard completed (see [first-installation](../getting-started/first-installation.md)). ## Steps 1. Go to `POP → Electronic Invoice - Settings`, **General** tab, **Transmission Data** section. 2. Fill in, if relevant to your case, the fields (all **optional**): - **Transmitter ID** — VAT number of the transmitter/intermediary. - **Transmitter Phone number**. - **Transmitter email address**. 3. Save. If you leave everything blank, the transmission channel in use will apply its own default values (e.g. its own data as the direct transmitter). ## Verify Generate a test document and check, in the generated XML, that the transmitter data block reflects the values you entered (or stays empty/default if you didn't fill them in). ## Common errors - **The fields appear disabled/not editable** — after completing the wizard and connecting the account (active license), the company and transmitter data in **General** become read-only in `wp-admin`: any further changes must be made from the POP account panel, not from here. - **You use the Aruba add-on or another channel that acts as an intermediary on your behalf** — in that case the channel can manage its own transmitter data independently (e.g. its own tax code as an authorized intermediary): check the specific documentation for the active add-on/channel, since it can differ from what's configured here in the General tab. - **You're not sure whether you need to fill in these fields** — if you don't use an intermediary for sending (e.g. you send via SdI via POP directly as the company), you can leave them blank. ## Related configuration For choosing the transmission channel, see [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/update-plugin ## Goal Update the POP plugin to the latest version without interrupting invoice generation. ## Prerequisites - Administrator access to `wp-admin`. - Ideally, a staging environment mirroring the production site where you can test the update first. ## Steps 1. Go to `wp-admin > Plugins`. 2. Find "POP – European e-invoicing compliance for e-commerce" (or "ex-WooPop"): if an update is available, WordPress flags it on the same row. 3. Click **Update Now**. WordPress downloads and replaces the plugin files while keeping the saved settings (options are stored in the database, not in the plugin files). 4. Once done, open `POP → Electronic Invoice - Settings` to check that the tabs open correctly and that the previously configured data (General, Numeration, Documents...) are still there. ## Verify - The version shown in `wp-admin > Plugins` (next to the plugin name) matches the downloaded release. - Generate a test order (or one in sandbox) to confirm that XML and PDF are still produced correctly after the update. ## Common errors - **A setting seems to have disappeared or changed after the update** — check the changelog of the installed version before opening a ticket: some options get renamed or moved between tabs when the settings structure changes. See [changelog/wordpress-plugin](../changelog/wordpress-plugin.md) for where to find the release notes. - **Different behavior compared to before the update** — check whether the changelog lists it as an intentional change before treating it as a bug. - **You want to postpone an important update** — test it in staging first: universal compatibility with every combination of third-party themes/plugins installed on your store can't be guaranteed. ## Related configuration For the minimum requirements supported by the current version, see [minimum-requirements](../getting-started/minimum-requirements.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/use-sandbox-environment ## Goal Make test requests to the POP API without consuming account credits. ## Prerequisites - A valid `license_key` (see [get-your-license-key](../getting-started/get-your-license-key.md)). ## Steps You can activate the sandbox in two equivalent ways: 1. **Explicit parameter** — send `"environment": "sandbox"` in the body to `https://popapi.io/wp-json/api/v2/...`. 2. **Sandbox gateway** — call `https://sandbox.popapi.io/wp-json/api/v2/...` without specifying `environment`: the gateway forces it automatically. If you still send an explicit `environment`, that one takes priority. All document-generation routes (SdI, PEPPOL, KSeF, PDF, ZUGFeRD, legacy Facturae) accept `environment: sandbox`. ## Verify - Sandbox requests don't consume credit. - On the XML routes, `invoice_number` is returned with a `SANDBOX-` prefix. ## Common errors - **The configured webhook doesn't receive anything in sandbox** — webhook delivery isn't available in sandbox: this is an expected limitation, not a configuration error. - **Delivery to Fatture in Cloud doesn't start in sandbox** — same reason: not supported in sandbox. - **PDF email sending doesn't work in sandbox** — this isn't a limitation: PDF email delivery is allowed even in sandbox. ## Related configuration See [api/sdi](../../api/sdi.md) and the other `api/*` pages for the specific behavior of each route in sandbox. --- ## Source: https://docs.popapi.io/en/guides/configuration/virtual-stamp-duty ## Goal Automatically add the virtual stamp duty (marca da bollo — Italy's €2 stamp duty) on invoices issued without VAT when the amount exceeds the legal threshold, and optionally charge it to the customer. ## Prerequisites - Store with billing country **Italy or San Marino**: the option is only visible in this case. - Invoices issued without VAT applied (e.g. regime forfettario/minimi, or in general VAT natures that exclude the tax). ## Steps 1. Go to `POP → Electronic Invoice - Settings`, **Documents** tab, **Stamp duty** section. 2. Enable **"Add virtual stamp duty on invoices"**. The stamp duty (€2) is automatically applied when the invoice/PDF is issued without VAT and the order amount exceeds **€77.47**. 3. If you want the customer to pay it (instead of absorbing it yourself as the seller), also enable **"Stamp duty charged to the customer"**: in this case the amount is also added to the cart, charged to the customer. ## Verify Generate a test order without VAT with a total above €77.47: the invoice should show the stamp duty line item (€2). If you've enabled charging the customer, also verify that the amount appears in the cart before checkout. ## Common errors - **You don't see the stamp duty option among the settings** — it's only visible if the store's country is Italy or San Marino: for other countries the option doesn't appear. - **The stamp duty isn't applied even though the option is enabled** — check that the invoice is actually without VAT (or at zero VAT) and that the order amount exceeds €77.47: below this threshold, or with VAT applied, the stamp duty doesn't trigger. - **The customer doesn't see the charge in the cart** — check that you've also enabled the specific "charged to the customer" option, not just the base one: they're two separate checkboxes. ## Related configuration To understand when an invoice counts as "without VAT" based on the tax regime, see [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/en/guides/configuration/woocommerce-tax-settings ## Goal Configure taxes in WooCommerce to minimize rounding differences between the order totals and the amounts shown on the electronic invoice. ## What WooCommerce recommends WooCommerce itself recommends setting product prices **tax-exclusive** (not tax-inclusive), precisely to avoid imprecise rounding when the tax is extracted during the generation of fiscal documents. This is not a requirement imposed by POP: it is WooCommerce's official recommendation in its own tax settings guide. If you still prefer to work with tax-inclusive prices, WooCommerce allows it (**Tax** tab, "Yes, I will enter prices inclusive of tax" option), and POP handles this case too. ## Why small differences can appear on the invoice An e-commerce store is designed to sell, not to issue fiscal documents: when prices are tax-inclusive, some recalculations are unavoidable in order to produce a fiscally correct document: - **Line total** — on the fiscal document this is recalculated as the net unit price (net of any discounts) times the ordered quantity; it may differ by a few cents from the total shown on the WooCommerce order (which starts from a tax-inclusive price). - **VAT total per rate** — this is recalculated as the rate percentage × the aggregated taxable amount for that rate; if the WooCommerce order's VAT total differs by a few cents, the invoice uses the value that is correct from an accounting standpoint. These differences are not a plugin error: they ensure the invoice complies with Italian tax rules even when the store works with tax-inclusive prices. ## If you want to switch to tax-exclusive prices on a catalog already set to tax-inclusive 1. Make a full backup of the site. 2. Export the products to CSV using WooCommerce's native tool. 3. Update the tax-exclusive prices in the exported file. 4. Re-import the products. ## Verify Compare the VAT total of a test order with the one reported on the generated invoice: any differences of a few cents are expected and documented here, not a malfunction. ## Common errors - **The VAT total on the invoice doesn't exactly match the order** — see the explanation above: it is an effect of rounding during VAT extraction, not a bug. - **You want to eliminate the differences entirely** — the only effective strategy is to work with tax-exclusive prices, as recommended by WooCommerce; there is no tax-extraction method that, starting from the gross price, always exactly reconstructs the original net price. ## Related configuration For selling to foreign customers (reverse charge) see [reverse-charge](reverse-charge.md); for the nature codes to use based on the tax regime see [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/anonymous-generation ## Goal Generate a fiscal document (invoice, credit note, or PDF) by calling the POP API without having created an account yet, to try the output format before deciding whether to connect a real account. ## What you need - No `license_key`: just omit the field (or the `X-API-Key` header) from the request. - A valid `data` payload, same as for an authenticated call. ## What it covers - Available routes: `create-xml` (SdI), `create-ubl` (PEPPOL), `create-ksef-xml` (KSeF), `create-zugferd` (ZUGFeRD), `create-pdf`. - **Local generation only**: no sending to an external channel (SdI, PEPPOL, KSeF, Zoho, Fatture in Cloud, Aruba, SdI via PEC). Sending a document requires a POP account with an active integration. - Limit: **1000 generations per month per site**, shared across all the routes above. ## How the caller is identified With no account there's no `user_id` to use: the monthly limit is tracked by a combination of `site_url` (if present in the payload) and the request's IP address. Including `site_url` in the payload keeps the count stable even if the IP changes (e.g. behind a proxy or CDN). ## Verify Call one of the routes above without `license_key`: if under the monthly limit, you get the generated XML/PDF normally, same as with an authenticated account. ## Common errors - **`pop_api_generation_rate_limit`** (429): the monthly anonymous generation limit was reached for this site/IP, connect a POP account to continue beyond 1000 generations. - **Sending to a channel fails**: expected, anonymous generation only covers local document output, not sending. An account with the desired integration active is required. ## Related configuration To connect a real account and unlock sending to official channels, see [get-your-license-key](get-your-license-key.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/choosing-an-invoicing-integration ## Goal Understand which transmission channel to activate for your store, among those available in POP. **The channels are mutually exclusive**: you can have only one active at a time (activating one automatically deactivates the others). ## Available channels | Channel | Who it's for | External dependencies | Notes | | --- | --- | --- | --- | | **SdI via POP** | Those who want the simplest flow for Italy: no external service to configure | None | Direct transmission to SdI, notifications handled inside POP, automatic verification of the recipient's tax code/VAT number. | | **SdI via PEC** | Low volumes, those who already have a PEC (certified email) mailbox and don't want additional external accounts | PEC mailbox | The XML is sent via PEC email; outcome notifications must be checked manually in the PEC mailbox — they are not handled automatically by POP. | | **Fatture in Cloud** | Those who already use Fatture in Cloud for accounting/invoicing | Active Fatture in Cloud subscription | Goes through the official Fatture in Cloud API; requires mapping [payment methods](../integrations/fatture-in-cloud-payment-methods.md) and a balance account before the first submission. | | **Aruba Business** | Those who already use Aruba as their e-invoicing provider | API activation on Aruba | Less configuration flexibility than the other options. | | **PEPPOL** | B2B sales abroad (PEPPOL network) | None | Not an alternative to SdI for Italy: it's the corridor for intra-EU e-invoicing. Covers 28 countries (full list in [api/peppol](../../api/peppol.md)) — **Spain is excluded** (Facturae corridor, not yet supported), and so are Northern Ireland and Liechtenstein. | | **KSeF** | Sales to Poland | Polish NIP (tax number) | See [KSeF activation](../integrations/ksef.md) — requires a dedicated registration separate from SdI/PEPPOL. | | **Zoho (native)** | Those who use Zoho Invoice/Zoho Books and want sync managed directly by POP | OAuth authorization to Zoho | See [Zoho activation](../integrations/zoho.md). Doesn't require your own n8n instance. For accounts registered in the United Arab Emirates, Saudi Arabia, Bahrain, Kuwait, Oman, or Qatar, this is the **only** available channel: these countries have no supported official e-invoicing network (no SdI/PEPPOL/KSeF). | If you'd rather manage the sync logic yourself on your own self-hosted n8n instance (more control/ customization), a dedicated package also exists — see [syncing to Zoho via n8n](../integrations/n8n-zoho.md). ## How to choose - **You only sell in Italy and don't already use an external accounting system** → SdI via POP: it's the path with the fewest configuration steps, and notifications stay inside POP. - **You already use Fatture in Cloud or Aruba for accounting** → connect that integration instead of duplicating data elsewhere, but budget time to complete the required mapping (accounts, payment methods). - **Very few documents per month and you want zero extra cost/services** → SdI via PEC, knowing that you'll have to manually check the outcomes in the PEC mailbox. - **Your store is based in Italy or San Marino** → stay on SdI (via POP or via PEC) even for foreign business customers: PEPPOL never activates in this case, regardless of the customer's country. Invoices to foreign customers still go through SdI, using the conventional recipient code for non-Italian recipients. - **Your store is based in an EU country other than Italy/San Marino covered by PEPPOL** (full list in [api/peppol](../../api/peppol.md)) and you sell B2B → use PEPPOL: it's the channel equivalent to SdI for e-invoicing in those countries. - **You sell in Poland** → you need KSeF, regardless of the channel chosen for Italy. - **Your account is registered in the United Arab Emirates, Saudi Arabia, Bahrain, Kuwait, Oman, or Qatar** → native Zoho is the only option: no other channel is available for these countries. ## Good to know - On WordPress, none of these channels require a paid plan to activate: every plan, including Free, can send using its own credits. On Shopify, PEPPOL, native Zoho, KSeF, and the webhook still require the Basic plan or higher. - Activating SdI via POP and PEPPOL at the same time is not supported: if both end up active, the one activated last takes precedence and the other is automatically deactivated. - You can change channel later, but the new channel's configuration (credentials, mappings) has to be redone — there is no automatic data migration between one integration and another. ## Related configuration For activation details of each channel, see the dedicated guides in this same section ("Integrations"). --- ## Source: https://docs.popapi.io/en/guides/getting-started/first-installation ## Goal Install the POP plugin on a WordPress/WooCommerce site and complete the initial account setup. ## Prerequisites - A WordPress site with WooCommerce active. - Minimum supported versions: see [minimum-requirements](minimum-requirements.md). - An email address to create (or link) the POP account. ## Steps 1. Download/install the plugin from `wp-admin > Plugins > Add New`, searching for "POP – European e-invoicing compliance for e-commerce", or upload the zip downloaded from WordPress.org. 2. Click **Activate**. 3. The first time a `wp-admin` page loads after activation, the plugin automatically redirects to the wizard (`POP → Electronic Invoice - Settings`, tab **Wizard setup**). The redirect happens only once and only if the account is not yet linked (no `license_key` and no POP account associated). 4. If you are not redirected, open `POP → Electronic Invoice - Settings` manually and go to the **Wizard setup** tab (visible only until the account is linked). 5. Enter the account email: if you already have a POP account it links it, otherwise it creates a new one. You'll receive an OTP code by email to authenticate. 6. Complete the business details requested by the wizard (country, tax regime if in Italy, personal/ company data). Once completed, the **Wizard setup** tab disappears from the menu. ## Verify - The **Wizard setup** tab is no longer visible among the settings tabs. - In `POP → Electronic Invoice - Settings`, tab **General**, the license shows as linked. - The WordPress admin bar shows the POP entry with the environment status (Live/Sandbox). ## Common errors - **The wizard doesn't start automatically after activation** — the redirect is "one-shot": if you've already opened another admin page in the meantime, open directly `admin.php?page=wc_el_inv-options-page&tab=wizard&wizard=init`. - **The OTP email doesn't arrive** — check your email provider's spam/anti-spam filters; the address used for the wizard must be reachable. - **Compatibility is not guaranteed with untested themes/plugins** — before installing in production, test in a staging environment that mirrors your real e-commerce setup: universal compatibility with every theme/plugin combination cannot be guaranteed. ## Related configuration For minimum technical requirements see [minimum-requirements](minimum-requirements.md); to choose the transmission channel (SdI via POP, PEPPOL, KSeF, add-on) after the wizard see [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/get-your-license-key ## Goal Get a valid `license_key` to authenticate requests to the POP API. ## Prerequisites - A valid email address. - Access to the mailbox to receive the OTP. ## Steps 1. Open `https://popapi.io/otp-login/`. 2. Enter your email address. 3. Receive a one-time password (OTP) by email. 4. Enter the OTP. 5. Complete the account setup wizard. 6. Open `https://popapi.io/`. 7. Go to `Account > API`. 8. Copy the default `license_key` that was generated. ## Verify Test the key with: ```bash curl --request GET \ --url 'https://popapi.io/wp-json/api/v2/account-profile?sdk=wordpress' \ --header 'X-API-Key: YOUR_LICENSE_KEY' ``` A response with `"authenticated": true` confirms the key is valid. ## Common errors - **`account-profile` responds unauthenticated** — the OTP may have expired, or the setup wizard was not completed: repeat the OTP login. - **You need more than one key** (e.g. separate environments) — from `Account > API` you can generate additional `license_key` values linked to the same account. - **The key stops working** — check whether it was regenerated/revoked from `Account > API`; every `license_key` should be treated as a secret credential. ## Related configuration See [api/overview](../../api/overview.md) for the base URL, authentication header, and first steps with the API. --- ## Source: https://docs.popapi.io/en/guides/getting-started/minimum-requirements ## Goal Check that your WordPress environment meets the minimum requirements before installing POP. ## Requirements declared by the plugin | Component | Minimum required | Tested up to | | --- | --- | --- | | PHP | 7.4 | — | | WordPress | 4.6 | 7.0 | | WooCommerce | 4.0 | 9.x | These are the values declared in the plugin package (header and `readme.txt`). WooCommerce's HPOS (High-Performance Order Storage) is supported starting from WooCommerce 9.x. To reliably use all current features (setup wizard, Integrations tab, XML/PDF generation via the cloud API), we still recommend an up-to-date environment — WordPress 6.x and WooCommerce 9.x or higher — consistent with what your hosting already requires for security reasons. ## How to check the installed versions - **WordPress**: `wp-admin > About WordPress` (or at the bottom of any `wp-admin` screen). - **WooCommerce**: `WooCommerce > Status` (tab "Status"), "WordPress environment" section. - **PHP**: on the same `WooCommerce > Status` screen, "Server environment" section. ## Verify If the installed versions are equal to or higher than the minimums in the table, you can proceed with [first-installation](first-installation.md). ## Common errors - **The plugin doesn't appear among the ones you can activate / fatal error on activation** — check the PHP version: very old environments (PHP < 7.4) may behave differently in some areas of the plugin that depend on more recent autoloading features. - **Some settings don't appear (Integrations tab, wizard)** — make sure WooCommerce is active and up to date: the plugin registers its hooks against WooCommerce at `init`. - **Before updating WordPress/WooCommerce to a major version** — test in a staging environment: see [update-plugin](../configuration/update-plugin.md) for the procedure to update only the POP plugin. ## Related configuration For the first launch after installation see [first-installation](first-installation.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/onboard-via-ai-assistant ## Goal Create a new POP account and activate SdI (Italy/San Marino) or PEPPOL (rest of the EU) entirely in chat with an AI assistant connected to the [remote MCP server](../integrations/mcp-remote.md) — without opening popapi.io or filling out any form. ## Prerequisites - An MCP client connected to `https://mcp.popapi.io/mcp` (see [mcp-remote](../integrations/mcp-remote.md)) — for this flow **you don't need a `license_key` yet**, so you can connect even without an account. - A valid, reachable email address. ## The flow (5 steps) The assistant will use these 5 tools, in order: 1. **`pop_onboarding_request_otp`** — ask the assistant to start registration with your email. If the account doesn't exist, it's created automatically. The OTP code is also sent by email, but the assistant already receives it in the response. 2. **`pop_onboarding_verify_otp`** — give the assistant the OTP code (expires in 10 minutes): in return you get a temporary `onboarding_token` (valid 30 minutes), which the assistant will use for you in the following steps. 3. **`pop_onboarding_get_status`** *(optional)* — to check where you stand before proceeding. 4. **`pop_onboarding_get_account_setup`** — the assistant retrieves the fields still to fill in (country, company name, VAT number, tax regime, etc.) and the allowed values (e.g. the list of tax regimes for your country). 5. **`pop_onboarding_save_account_setup`** — provide the missing data (in natural language, the assistant translates it); at this point you can also ask to activate SdI or PEPPOL in the same request. ## Activating SdI or PEPPOL in the same flow - **SdI** (IT/SM accounts only) — ask to activate it: the assistant sets `active_sdipop_integration = 1` and `active_peppol_integration = 0`. - **PEPPOL** (other EU countries) — ask to register the PEPPOL legal entity: you'll need address, city, zip code, and the PEPPOL scheme/identifier — the assistant retrieves these from the step-4 lookups if you don't know them off-hand. - SdI and PEPPOL are **mutually exclusive**: you can't activate both on the same account. ## After activation Once the wizard is complete, get your `license_key` from `Account > API` on popapi.io (see [get-your-license-key](get-your-license-key.md)) to start generating invoices — that's the key you'll use to authenticate "normal" calls (invoice creation), different from the `onboarding_token` used only during this flow. ## Good to know - None of the 5 onboarding tools require the `Authorization: Bearer` header — they only use `onboarding_token` (or nothing, in the first step). - If you have an administrator account, you won't receive an OTP: use your admin password as the "OTP" in step 2. - Once `wizard_completed` is true, calling save again doesn't overwrite anything: it just returns the current state. - PEPPOL fields, once the legal entity is registered, stay permanently locked (not self-editable). ## Common errors - **Expired OTP** — you waited more than 10 minutes between request and verification: restart from step 1. - **Expired `onboarding_token`** — more than half an hour has passed since step 2: there's no refresh, you restart from the OTP request. - **VAT number already in use** — 422 error during save: that VAT number is already linked to another account on the chosen environment (live/sandbox). - **Locked field can't be changed** — some fields stay fixed after the first save (e.g. country, or all PEPPOL fields after registration): open a support ticket to change them. ## Related configuration For the technical detail of the underlying protocol (same flow, direct REST calls) see [api/onboarding](../../api/onboarding.md). To connect the assistant see [mcp-remote](../integrations/mcp-remote.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/shopify-faq ## Goal Quickly get oriented on what POP for Shopify does (and doesn't do) before diving into the individual configuration guides. ## Before you start **Does POP calculate checkout taxes?** No. Shopify remains solely responsible for calculating and applying taxes. POP uses the tax data present in Shopify to generate and send documents (PDF/XML, SdI/PEPPOL/KSeF). **Where do I configure VAT, OSS, markets, and tax rules?** Always in Shopify Admin (Markets, Tax regions). For B2B, check the tax data on Company/Company Location where applicable. ## Customer tax data **Where does POP get the customer's tax data from?** From order/customer metafields `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), with a fallback to the order's customAttributes. Details and priority in [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **Are the metafields created automatically?** Yes, after the wizard and POP license are completed, it tries to create the missing definitions idempotently. If something is missing, the Home page shows a recovery section with a "Create missing metafields" button. ## Shopify Plus vs non-Plus **What's the difference in fiscal data collection at checkout?** On Shopify Plus, the native POP Checkout UI Extension is available. On non-Plus stores, the fields are added to the cart/cart drawer via a script pasted into the theme — see [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **Does POP support both B2B and B2C scenarios?** Yes, both; the fiscal correctness of the document still depends on the quality of the data collected in Shopify. ## Italy, SdI, and PEPPOL **Can Shopify's native Tax Code/PEC fields be removed from checkout?** No, Shopify applies them natively for Italy and they cannot be removed or modified by POP. They are still optional; disabling them requires a request to Shopify support. **Can I send to SdI with a store whose currency is not EUR?** No. SdI flows require the Shopify store's main currency to be EUR. **Is PEPPOL available for private customers?** No. Automatic sending to PEPPOL always skips private customers (B2C); downloading the PDF as a courtesy document remains available. Details in [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **Does POP validate the VAT number?** Yes, through the official VIES service. The final tax decision on VAT application still rests with the Shopify configuration. ## Plans and limits **How many documents can I generate per month?** It depends on the active plan: Free 20/month, Basic 40/month, Growth 100/month, Pro 400/month, Enterprise 2000/month. Once the limit is exceeded, generation shows a warning with a link to upgrade. ## Quick troubleshooting **I don't see all the fiscal fields on the order/customer:** 1. Check that the wizard and POP license are completed. 2. Check that the `pop_*` metafields have been created (otherwise use the recreation button on Home). 3. Check the checkout/theme configuration. 4. Check Markets/Tax in Shopify Admin. **The taxes on the invoice don't match expectations:** 1. Check the Shopify tax rules. 2. Check the customer type and saved fiscal data. 3. Check for a failed VAT validation. 4. Check the transmission channel (SdI/PEPPOL/KSeF) and that channel's specific constraints. ## Related configuration To go deeper, start with [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) and [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/what-the-plugin-does ## Goal Understand, before installing it, what the POP plugin actually does when you activate it on a WooCommerce store. ## What POP configures Once active, POP integrates with WooCommerce and automatically adds: 1. **Billing fields at checkout and in "My account"** — customer type (Individual / Company / Sole trader), VAT number, tax code, and a field for PEC or a 7-character SDI recipient code. Each of these fields is required or optional depending on the customer's country and the selected customer type, and is validated with a format check. 2. **Automatic generation of the XML document** for every order that enters "processing" or "completed" status — see [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). 3. **A dedicated settings panel** — `POP → Electronic Invoice - Settings` in `wp-admin`, with separate tabs for company data, checkout, numbering, documents, advanced options, and integrations. ## What it does NOT include by default - **Digital signature and transmission to SDI** are not automatic with installation alone: they require choosing a transmission channel (SdI via POP, PEPPOL, KSeF, or an add-on such as Fatture in Cloud, Aruba, or SdI via PEC) — see [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). - **Compatibility with custom checkouts** is not guaranteed: if the order/checkout flow is altered by another plugin or by custom code, POP might not be able to correctly read the billing fields. ## Verify After activation, open `POP → Electronic Invoice - Settings`: if you see the General, Checkout, Numeration, Documents, Advanced, Invoices, and Integrations tabs, the plugin is installed and working. ## Common errors - **The billing fields don't appear at checkout** — check that WooCommerce is active: without WooCommerce, POP doesn't add any field. - **A checkout customization plugin hides the POP fields** — compatibility with third-party checkout logic is not guaranteed: temporarily disable the other plugin to isolate the issue. ## Related configuration For installation and first-launch steps see [first-installation](first-installation.md); for the fields contract see [checkout-field-names](../configuration/checkout-field-names.md). --- ## Source: https://docs.popapi.io/en/guides/getting-started/xml-invoices-generated ## Goal Understand what POP produces when it generates an XML invoice for an order, and what's missing to send it to the SDI without an active transmission channel. ## What the plugin generates For every completed order, POP creates a **FatturaPA XML** file (`FPR12` format by default, the standard format for invoices to private individuals; the format changes if the document is addressed to a business recipient). You can download the files individually from the **Invoices** tab, or select several and export them in bulk as a `.zip` archive. ## What it does NOT do on its own - **The XML file generated by the plugin alone is not digitally signed.** The digital signature, if required by the chosen transmission channel, is applied by the channel itself (e.g. SdI via POP), not by the base XML generation. - **The file is not automatically transmitted to the SDI** unless you activate one of the transmission channels (SdI via POP, PEPPOL, KSeF, or an add-on such as Fatture in Cloud, Aruba, or SdI via PEC) — see [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). If you don't activate any channel, it's still possible to download the XML and transmit it yourself (e.g. via PEC, signing it with an external tool, following the guidelines of the Agenzia delle Entrate, Italy's Revenue Agency). ## Verify After an order moves to processing or completed, in `POP → Electronic Invoice - Settings > Invoices` you should see the XML document associated with the order, ready to download. ## Common errors - **The downloaded XML is rejected by an intermediary/external software because it's "not signed"** — expected: base XML generation does not include the signature; you need to sign it externally or activate a transmission channel that handles signing. - **The XML is missing for an order** — check the order status: generation happens when it moves to "processing" or "completed", see [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). - **You need to know where the XML/PDF files are physically stored on the server** — see [generated-files-storage](../configuration/generated-files-storage.md). ## Related configuration To choose a channel that automatically sends the XML to SDI/PEPPOL/KSeF see [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md); for the XML payload contract on the API side see [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/aruba-connect ## Goal Link WooCommerce to the Aruba electronic invoicing service and enable automatic invoice sending after an order is completed. ## Prerequisites - The **Aruba** addon installed and active. - An **Aruba Premium invoicing account**, or a basic account linked to a Premium account via delegation — this is a requirement of the Aruba account itself, not something the plugin checks. - Only **one** invoice-sending integration can be active at a time: if Fatture in Cloud or SDI via PEC is already active, deactivate it before connecting Aruba. ## Steps ### 1. Connect the account In the plugin's **Aruba** tab, enter the username and password of your Aruba invoicing account in the dedicated login panel. Nothing else is needed: the plugin authenticates directly with those credentials. ### 2. Configure automatic sending 1. **Order status that triggers sending** ("Enable auto-send for status:") — defaults to "Completed", but can be set to another WooCommerce order status. 2. **Enable automatic sending of invoices** ("Enable automatic sending") — once an order reaches the configured status, an event is scheduled that runs after a configurable delay in hours (default **12 hours**): the invoice is sent to Aruba, which forwards it to the SDI after its own checks. 3. If an invoice is invalid, sending stops and must be completed manually once the errors have been fixed. ### WP-Cron reliability Automatic-sending events are handled by **WP-Cron**, which only fires when someone visits a page on the site: on low-traffic sites, sending can be delayed. Add a system-level Cron job that calls it periodically (e.g. every 30 minutes): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` where `` is the domain's root directory. ### Diagnostic log To trace scheduling and execution of sends, add this to `wp-config.php`: ``` define("WP_FATT_ARUBA_LOG", true); ``` ## Verify With the log enabled, generate a test order and check in the log file that sending was scheduled and executed; then check that the document appears on the Aruba portal. ## Common errors - **Login doesn't work even with correct credentials** — verify that the account is actually Premium or properly delegated: a non-delegated basic account is not enabled for sending via API. - **Automatic sending doesn't start** — almost always WP-Cron isn't firing due to lack of traffic: add the system Cron job described above. - **The invoice stays stuck after being sent to Aruba** — Aruba flagged it as invalid during its validation check: fix the data and resend manually once the errors are resolved. ## Related configuration For the SDI delivery cycle and notification email logic, see [aruba-invoice-flow](aruba-invoice-flow.md). For the invoice data contract, see [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/aruba-invoice-flow ## Symptom After sending an invoice to Aruba it's unclear what happens in the background, or the customer receives (or doesn't receive) the email with the pro forma invoice. ## Cause ### The active cycle on the Aruba side Once an invoice is sent to Aruba, the "active cycle" follows these steps (managed by Aruba, not by the plugin): 1. The XML document is sent via web service to Aruba's channels. 2. Aruba PEC checks the formal compliance of the format. 3. Aruba PEC applies the electronic signature (qualified, optional for B2B/B2C) and transmits it to the SDI. 4. The SDI validates the invoice and forwards it to the recipient (via recipient code or PEC), or to a third party delegated by the recipient. 5. The SDI returns a rejection, non-delivery, or delivery notification to Aruba. 6. The document moves into mandatory legally-compliant digital storage. For the detailed meaning of the individual notification codes, refer to Aruba's documentation. ### When the pro forma invoice email is sent When the configured notification-checking time elapses, the plugin checks the status received from Aruba and automatically sends the customer the pro forma invoice email **only** if one of these conditions is met: - status **RC** (Consegnata / delivered) — the invoice was delivered by the SDI; or - status **MC** (Non Consegnata / not delivered), but **only for "private" customers**; or - status **RC or MC** when the recipient has a valid PEC/email address, or the SDI recipient code is set to `0000000`. Outside of these cases (e.g. a business customer with a specific recipient code and a status other than RC/MC) the automatic pro forma email is not sent: this isn't an error, it's the expected behavior. ## Fix - To send the pro forma anyway in a case not covered by the conditions above, use the manual **"Pro Forma"** button on the order/invoice. - If an order goes a long time without an RC/MC notification, check the status directly on the Aruba portal: the plugin only queries notifications already available there, it doesn't force a new transmission. ## Related configuration To connect the account and configure automatic sending, see [aruba-connect](aruba-connect.md). To understand an SDI rejection, see [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-auto-send ## Goal Enable automatic sending of invoices to Fatture in Cloud after an order is completed, and verify the flow with a test order before relying on the automation. ## Prerequisites - The [Fatture in Cloud connection](fatture-in-cloud-connect.md) already active. ## Steps ### Configure automatic sending In the **Fatture in Cloud** tab: 1. **Order status that triggers sending** ("Enable auto-send for status:") — defaults to "Completed", but can be set to another WooCommerce order status. 2. **Enable automatic sending of invoices** ("Enable automatic sending") — once an order reaches the configured status, an event is scheduled that runs after a configurable delay in hours (default **12 hours**). 3. When the delay elapses: the invoice is uploaded to Fatture in Cloud, then its formal validity is checked; only if valid is it forwarded to the SDI. If an invoice is invalid, sending stops and must be completed manually once the errors have been fixed. 4. **Disable automatic sending of invoices to the SDI** ("Disables the automatic sending of invoices to the SDI") — if enabled, stops the process after the upload/check on Fatture in Cloud and does not perform the automatic forwarding to the SDI (useful if you want Fatture in Cloud, not the plugin, to always decide when to send to the SDI). 5. **Email notification on failed creation** — there is a dedicated option ("Send an email to the WordPress installation administrator ... to report the failure to create the document on Fatture in Cloud") to receive an email if automatic invoice creation fails. ### WP-Cron reliability Automatic-sending events are handled by **WP-Cron**, which only fires when someone visits a page on the site. On low-traffic sites, sending can be delayed or not start at all. To make it reliable, add a real system-level Cron job (via hosting, VPS, or a dedicated server) that calls it periodically (e.g. every 30 minutes): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` where `` is the domain's root directory. ### Diagnostic log To trace the scheduling and execution of sends (including the order statuses passed through and the reason an automatic send was skipped), add this to `wp-config.php`: ``` define("WP_FATT_CLOUD_LOG", true); ``` ## Generating a test XML Before relying on the automation, verify the flow with a test order: 1. Make sure the addon is connected (see [fatture-in-cloud-connect](fatture-in-cloud-connect.md)). 2. **Temporarily disable** both "Enable automatic sending of invoices" and "Disable automatic sending of invoices to the SDI", so no send happens on its own. 3. Make a test purchase and move the order to the status configured as the trigger (default "Completed"). Go to the plugin's **Invoices** section: you'll find the generated XML, downloadable so you can check its structure. 4. Once you've checked the XML, use the **"Upload"** button on the invoice to send it manually to Fatture in Cloud: after sending you'll see it appear among the documents in your account. ## Verify - With the log enabled, the file records the creation, check, and sending (or the reason for the skip) for each order. - The document appears on Fatture in Cloud with a validity/sending status consistent with what's shown in the plugin. ## Common errors - **Automatic sending never starts** — almost always it's WP-Cron not firing due to lack of traffic: add the system Cron job described above. - **The invoice stays stuck after upload** — the formal check on Fatture in Cloud flagged it as invalid: fix the order/invoice data and resend manually. - **You want to test without risking a real send** — follow the "Generating a test XML" procedure above: with both automatic-sending options disabled, no document goes out on its own until you upload it manually. ## Related configuration For the invoice data contract (payload, field mapping), see [api/sdi](../../api/sdi.md). To understand an SDI rejection after forwarding, see [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-connect ## Goal Link your Fatture in Cloud account to the POP plugin, choose which documents to generate (invoices or orders) and, optionally, tag documents with a revenue center. ## Prerequisites - The **Fatture in Cloud** addon installed and active. - A Fatture in Cloud account with at least: a payment account (e.g. "Standard account") and the payment methods you use in WooCommerce (bank transfer, cash on delivery, cash, card) already created — these are prerequisites of the Fatture in Cloud account, not plugin settings. - Only **one** invoice-sending integration can be active at a time (Fatture in Cloud, Aruba, SDI via PEC, SDI via POP...): if another one is already active, deactivate it before connecting Fatture in Cloud. ## Steps You can connect your Fatture in Cloud account in two equivalent ways: from the WordPress plugin (which also lets you choose granular permissions, see below), or directly from the account panel on `popapi.io` (**My Account > Integrations > Fatture in Cloud > Connect**) — useful if you're not integrating through WordPress (e.g. direct API). Both paths show the same OAuth authorization popup (code + link). ### 1. Choose permissions and connect the account (WordPress plugin) In the plugin's **Fatture in Cloud** tab, before connecting, select the permissions to grant: - **Invoices** or **Orders** — these are two mutually exclusive permissions: selecting one automatically deselects the other. If you choose **Orders**, the plugin will create an order-list document on Fatture in Cloud instead of a proper invoice. - **Credit Note**, **Receipts**, **Clients** — additional optional permissions. - **Stock** — only needed if you'll use stock synchronization (see [fatture-in-cloud-warehouse-sync](fatture-in-cloud-warehouse-sync.md)). Click **Connect**: a popup opens with a code and an authorization link. Don't close the popup — open the link, authorize the app on Fatture in Cloud by entering the code shown, then return to the plugin: you'll see the message **"Access Token successful!"**. ### 2. Set the revenue center (optional) If you manage multiple businesses or business lines, fill in the **Revenue center** field (e.g. `e-commerce`): the value is added to every invoice/order created on Fatture in Cloud to identify the source of the sale. If you leave the field empty, no revenue center data is sent. ## Verify - In the plugin's Fatture in Cloud tab, the connection status shows as active (token saved). - Generate a test order (see [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md#generating-a-test-xml)) and check that the document appears on Fatture in Cloud in the chosen format (invoice or order). ## Common errors - **The authorization popup closes without completing the connection** — don't close or reload the page until **"Access Token successful!"** appears: the code shown expires if the procedure isn't completed in time. - **Invoices are created instead of orders (or vice versa)** — the two permissions are mutually exclusive on the Fatture in Cloud side: to change them you have to redo the connection choosing the correct permission, a separate setting after connecting isn't enough. - **The revenue center doesn't appear on the document** — verify you saved the field in the settings tab: if it's empty, the data simply isn't sent. ## Related configuration For the invoice data contract (payload, field mapping), see [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-corrispettivi ## Goal Generate a **corrispettivo** (Italian daily sales receipt for tax purposes) on Fatture in Cloud from an order with a document of type **receipt**, using the dedicated **POP to Fatture in Cloud (Corrispettivi)** add-on. ## Prerequisites - The **POP to Fatture in Cloud** add-on already connected and working (see [fatture-in-cloud-connect](fatture-in-cloud-connect.md)) — the Corrispettivi add-on is layered on top of the base one, it doesn't replace it and doesn't work without it. - Orders configured to generate a document of type **receipt** (not invoice). ## Steps 1. Install and activate the **POP to Fatture in Cloud (Corrispettivi)** add-on. 2. Verify that the base Fatture in Cloud add-on is already connected and configured correctly. 3. From this point on, orders with a document of type receipt generate a corrispettivo on Fatture in Cloud instead of a standalone POP receipt. ## Important limitation By its nature, Fatture in Cloud **does not handle the issuance of electronic corrispettivi** (the telematic transmission to the Agenzia delle Entrate, Italy's tax authority): the corrispettivo created by this add-on is a document internal to Fatture in Cloud, useful for bookkeeping, but it does not fulfill a telematic corrispettivi transmission obligation if your business is subject to one. Check with your accountant whether this limitation is relevant to your situation. ## Common errors - **The corrispettivo isn't created** — first check that the base Fatture in Cloud add-on is connected: without that connection active, the Corrispettivi add-on has nothing to rely on. - **You expected an automatic telematic transmission** — this isn't provided: see the limitation above. ## Related configuration For the base connection and payment method mapping, see [fatture-in-cloud-connect](fatture-in-cloud-connect.md) and [fatture-in-cloud-payment-methods](fatture-in-cloud-payment-methods.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-payment-methods ## Goal Make sure the POP add-on for Fatture in Cloud generates documents with the correct payment method, by mapping the gateways active on WooCommerce to the methods configured on Fatture in Cloud. ## Prerequisites - The **POP to Fatture in Cloud** add-on installed and active. - A Fatture in Cloud account. ## Steps 1. **Connect the account** — in POP's **Fatture in Cloud** tab, click **Connect**: a popup opens with a code and a link to authorize the OAuth connection. Don't close the popup until you see the confirmation "Access Token successful!". 2. **Select the company** — from the **"Set the company to link"** dropdown, choose the Fatture in Cloud company to connect (if your account manages more than one). 3. **Create a payment account on Fatture in Cloud** — on Fatture in Cloud, go to `Settings > Payment accounts` and create an account (e.g. "Standard account"), if one doesn't already exist. 4. **Create the base payment methods on Fatture in Cloud** — under `Settings > Payment methods`, create at least the base entries: Bank transfer, Check, Cash, Payment card (you can consolidate Stripe/PayPal/other card gateways under a single "Payment card" entry, or create one per gateway). 5. **Configure the payment methods on WooCommerce** — make sure `WooCommerce > Settings > Payments` lists all the gateways actually used on your store. 6. **Map the payments in POP's Fatture in Cloud tab** — set the global payment account, then match each WooCommerce gateway to the corresponding Fatture in Cloud payment method. ## Verify Generate a test document from the add-on for an order with a specific gateway: the document on Fatture in Cloud must show the mapped payment method, not a generic or empty value. ## Common errors - **"Payment account missing"** — you haven't selected/created the global payment account before mapping the methods: go back to step 3. - **The generated document has the wrong payment method** — check the gateway → method mapping: every WooCommerce gateway must point explicitly to the correct Fatture in Cloud method, there's no smart automatic fallback. - **You can't complete the OAuth connection** — don't close the popup before the confirmation message; if the code expires, repeat step 1. ## Related configuration To understand whether Fatture in Cloud is the best fit compared to SdI via POP, Aruba, or PEPPOL, see [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-pdf-email ## Goal Choose whether to attach to order emails the invoice PDF generated by Fatture in Cloud, or use the PDF generated by default by POP. ## Prerequisites - The [Fatture in Cloud connection](fatture-in-cloud-connect.md) already active. ## Steps 1. In the plugin's **Fatture in Cloud** tab, find the option **'Use the "Fatture in Cloud" PDF document as an attachment to the Invoice email'**. 2. **Enabled** — the PDF attached both to the manual "Invoice" email (an action available on the order) and to the automatic invoice email sent after delivery to the SDI (if SDI sending is active) is the one generated by Fatture in Cloud, retrieved from the document already uploaded to their system. 3. **Disabled** — the PDF generated internally by POP is used, without depending on Fatture in Cloud. ## Behavior when the document doesn't exist yet With the option **enabled**, if an order moves to "completed" but the invoice hasn't yet been uploaded to Fatture in Cloud (e.g. automatic sending hasn't run yet, see [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md)), the customer email **is not sent at all** — it doesn't fall back to POP's PDF, it simply waits until the Fatture in Cloud document exists. Once the document is present, sending resumes normally with the correct PDF attached. ## Verify Manually send the "Invoice" email from an order whose document is already uploaded to Fatture in Cloud and check the attachment: with the option enabled it must have Fatture in Cloud's layout, not POP's standard one. ## Common errors - **The customer email doesn't go out at all** — with the option enabled this is expected until the document has been uploaded to Fatture in Cloud: check the status of automatic sending or manually upload the invoice (see [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md)) before expecting the email. - **The attachment stays POP's even with the option enabled** — the Fatture in Cloud PDF only exists once the document has been uploaded to their system: if the PDF URL is missing from the order metadata, the plugin has nothing to retrieve. ## Related configuration For automatic sending and document generation, see [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/fatture-in-cloud-warehouse-sync ## Goal Link WooCommerce products to their Fatture in Cloud counterparts and keep stock in sync between the two systems. ## Prerequisites - The **Fatture in Cloud (Stock Management)** addon — it only works together with the base [Fatture in Cloud integration](fatture-in-cloud-connect.md). - While connecting to Fatture in Cloud you must also have granted the **Stock** permission (a write scope on stock): without this permission, the products-download button doesn't appear. ## Steps ### 1. Download/update products In the addon's tab, use the **"Get or Update products"** button to import the product list from Fatture in Cloud (the date of the last update is also shown). ### 2. Associate products You can link each WooCommerce product to a Fatture in Cloud product in two equivalent ways: - from the **"Associate the product"** selector on the WooCommerce product page (simple product or variation); - by entering in the WooCommerce product's **SKU** field the same code as the product on Fatture in Cloud — the match happens automatically by code correspondence, without needing the selector. ## What it syncs - Every time you update the stock of a WooCommerce product (simple or variation), the stock of the linked product on Fatture in Cloud is updated accordingly. - When a product goes back into stock after a refund, synchronization resumes. - When an invoice is uploaded, for every product line present in the document the stock on Fatture in Cloud is aligned with WooCommerce's. ## Verify - After updating the stock of a linked product, check the quantity on the corresponding product page in Fatture in Cloud: it must reflect the new value. ## Common errors - **The "Get or Update products" button doesn't appear** — the connected Fatture in Cloud account doesn't have write permission on stock: redo the connection including the Stock scope. - **The product doesn't sync** — it isn't associated with any Fatture in Cloud product: check the "Associate the product" selector, or that the SKU field matches exactly the code on Fatture in Cloud. - **Stock doesn't update on variations** — the association must be done per individual variation (SKU or selector), doing it on the parent product alone isn't enough. ## Related configuration For the base connection setup, see [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/france-peppol ## Goal Understand what's needed for electronic invoicing in France with POP and what to expect from activation. ## What you need - No minimum plan: activation and sending are available on every plan, including Free, using credits. - Account country set to France. - A valid French VAT number, or (if you don't have one) your **SIREN** number (9 digits) or **SIRET** (14 digits). ## How it works POP sends your invoices to France's official corridor (**gov-fr**), handled through our compliance partner: this is not the same generic PEPPOL network used for other European countries, but nothing changes in how you generate invoices. You don't need to look up or manually enter your SIREN in most cases: POP derives it automatically from your French VAT number (the last 9 digits). POP also checks that the entered VAT number is correct against the SIREN it contains, so typos get flagged right away instead of causing problems later. After activation you'll complete an identity verification (KYC) step on a page hosted directly by our compliance partner, not by the POP panel: a different step than Polish KSeF, where signing happens entirely inside the account panel. ## Steps 1. In the guided setup wizard (or the account panel, for an existing account with country France), confirm your **SIREN** number: in most cases it's already pre-filled, derived automatically from your VAT number. 2. Save: POP automatically registers your French Legal Entity. 3. Complete identity verification (KYC) on our compliance partner's external page. ## Current status The France corridor is **in beta**: it covers invoice generation and sending (e-invoicing). France's second requirement, **e-reporting** (for operations outside the internal B2B perimeter), isn't covered yet. ## Common errors - **"France Legal Entity is missing."**: activation isn't complete yet, check that the account has a valid French VAT number or a registered SIREN. - **"France integration is not active."**: the registration exists but the integration isn't active on the account yet. - **The VAT number is rejected**: the check digits don't match the embedded SIREN, verify you entered the correct number. ## Related configuration For the technical API contract, see [api/peppol](../../api/peppol.md). To choose between the available invoicing channels, see [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/ksef ## Goal Link your POP account to the KSeF system (Poland) to send FA(3) electronic invoices. ## Prerequisites - On WordPress: no minimum plan, activation and sending are available on every plan (including Free), using credits. On Shopify, the **Basic plan or higher** is required instead. - **NIP** (Polish VAT number) set in the account data. - **Live environment**: access to `podpis.gov.pl` with Profil Zaufany, or a KSeF PKI certificate (`PKCS#12` or `PEM`). - **Sandbox environment**: no prerequisites, the signature is simulated automatically. Live and sandbox are **separate** registrations: activating the sandbox doesn't automatically activate live, and vice versa. ## Steps (account panel) 1. **Register the legal entity**: address, city, postal code, notification email. The NIP and registered business name are read automatically from the account settings, they don't need to be re-entered. 2. **Authorize access**: - **Sandbox**: click "Start authorization" (a 10-minute window), then "Activate". - **Live with Profil Zaufany**: download the signature file, sign it on `podpis.gov.pl`, upload the signed XML, then "Activate". - **Live with PKI certificate**: upload the certificate name, passphrase, and certificate file. 3. **Active connection**: from this point you can send KSeF invoices via the POP API. If you're accessing for the first time with a Polish (`PL`) account, activation can also happen from the guided setup wizard, with the same two steps (registration + authorization). ## Credit cost Every KSeF document consumes **1 credit**, only for delivery: locally generating the XML never consumes a credit. ## Disconnecting - **Disconnect**: pauses sending while keeping the registration (you can reactivate it later). - **Delete connection**: also removes the local registration data. ## Common errors - **"KSeF Legal Entity is missing."**: the legal entity hasn't been registered (Step 1) before generating/sending a document, complete the registration in the account panel. - **KSeF onboarding not completed**: NIP or account data is missing, check the settings before proceeding with authorization. - **Sandbox active but no real sending happens**: expected, the sandbox doesn't actually deliver to KSeF, you need to switch to the live environment for actual sending. ## Related configuration For the API contract details (payload, FA(3) field mapping), see [api/ksef](../../api/ksef.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/mcp ## Goal Generate, submit, and check SdI, PEPPOL, KSeF, ZUGFeRD, and PDF invoices, plus sync documents to Zoho, directly from an AI assistant (e.g. Claude Desktop) via the official MCP server (`@getpopapi/pop-mcp`), without calling the REST API manually. This guide covers the **local** install (Node.js, stdio). If you'd rather connect your assistant without installing anything, there's also a **remote** MCP server already live — see [mcp-remote](mcp-remote.md). ## Prerequisites - Node.js >= 18. - A valid POP `license_key` (see [get-your-license-key](../getting-started/get-your-license-key.md)) — if you don't have an account yet, you can also get one through the headless flow (see [api/onboarding](../../api/onboarding.md)), without going through the browser login. - For SdI/PEPPOL submission: an active integration on your POP account. No minimum plan: sending is available on every plan, including Free, using credits. ## Installation ```bash npm install -g @getpopapi/pop-mcp ``` Alternatively, from source: clone the repository, `npm install`, `npm run build`, then point your client at the generated `dist/cli.js` file. ## Configuration The `license_key` is passed as an environment variable, never as a call parameter: ```bash export POP_API_KEY=your_license_key ``` Optional, to use the sandbox environment: `export POP_ENVIRONMENT=staging`. ## Connecting Claude Desktop Add to the configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, equivalent paths on Windows/Linux): ```json { "mcpServers": { "pop": { "command": "pop-mcp", "env": { "POP_API_KEY": "your_license_key" } } } } ``` ## Available tools (11) - **Creation** — `pop_create_sdi_invoice` (FatturaPA XML, optional SdI submission), `pop_create_peppol_invoice` (UBL 2.1, optional PEPPOL submission), `pop_create_ksef_invoice` (Polish FA(3) XML, optional KSeF submission), `pop_create_zugferd_invoice` (PDF/XML/hybrid-PDF bundle), `pop_create_pdf_invoice` (PDF with optional email delivery, up to 3 recipients). - **Zoho sync** — `pop_sync_zoho_document`: syncs an invoice or credit note to Zoho Books/Invoice via the account's native connector; by default it first checks the Zoho connector is active and connected (`GET /integration/zoho/status`), failing with a clear error instead of letting the sync fail on Zoho's side. - **Status and retrieval** — `pop_get_invoice_status` (SdI notifications), `pop_get_peppol_document`, `pop_get_sdi_document`. - **Validation and preservation** — `pop_verify_sdi_document`, `pop_preserve_document` (long-term legal archival). None of these require a minimum plan anymore. Every tool calls the same REST routes already documented in [api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md), and [api/zoho](../../api/zoho.md) — the MCP server doesn't introduce a different API contract, it only translates the assistant's requests into HTTP calls to POP. ## Verify Ask the assistant something like *"Create a FatturaPA invoice for 1000€ + 22% VAT to Rossi SRL (VAT IT12345678901)"*: if the setup is correct, the tool returns the generated XML (or a readable error, with cause and affected field). ## Common errors - **`unauthorized_user`** — `POP_API_KEY` missing or invalid: check it under `Account > API` on popapi.io. - **`integration_inactive`** — SdI or PEPPOL isn't active on the account: complete activation before using `submit_to_sdi`/`submit_to_peppol`. - **`pop_api_email_limit`** — more than 3 email recipients on `pop_create_pdf_invoice`: reduce to a maximum of 3. - **`pop_preserve_document` called at the wrong time** — only call it after `pop_get_invoice_status` returns status `RC` (Ricevuta di Consegna) or `MC` (Mancata Consegna), not for other statuses. - **"Zoho integration is not active for this account"** — returned by `pop_sync_zoho_document` before even calling Zoho, if the native connector isn't active/connected: complete activation from the POP account panel (see [guides/integrations/zoho](zoho.md)). ## Related configuration For the full data contract (`data` structure, required fields per document type), see [api/overview](../../api/overview.md) and the channel-specific pages ([api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md), [api/zoho](../../api/zoho.md)). --- ## Source: https://docs.popapi.io/en/guides/integrations/mcp-remote ## Goal Connect an AI assistant (Claude, or any MCP-speaking client) to POP's official remote MCP server (`https://mcp.popapi.io/mcp`), without installing Node.js or configuring anything locally — unlike the [local version](mcp.md), all you need here is a URL. ## Prerequisites - A valid POP `license_key` (see [get-your-license-key](../getting-started/get-your-license-key.md)) — or, if you don't have an account yet, you can create one **by talking to the assistant itself**: see [onboard-via-ai-assistant](../getting-started/onboard-via-ai-assistant.md). - A client that supports MCP over HTTP: Claude (remote connector), OpenAI Responses API, n8n, MCP Inspector, or a custom integration. ## How it works - Endpoint: `https://mcp.popapi.io/mcp` — Streamable HTTP transport. - The server is **stateless and multi-tenant**: there's no `license_key` configured server-side like in the local version. Every single request must carry your key as a header: ``` Authorization: Bearer your_license_key ``` - If the header is missing or malformed, the request fails with `401` (`unauthorized_user`) **before** calling the POP API. If the key is present but invalid, the request reaches POP and returns whatever error POP itself generates (e.g. `unauthorized_user`, `insufficient_level`). ## Connecting Claude Add a new remote connector pointed at `https://mcp.popapi.io/mcp`, with header `Authorization: Bearer your_license_key` — the exact steps depend on which version of Claude you're using (desktop or web): look for "connector" or "remote MCP" in settings. ## Trying it with MCP Inspector ```bash npx @modelcontextprotocol/inspector ``` Point it at `https://mcp.popapi.io/mcp`, with the same `Authorization: Bearer` header. ## Trying it with curl ```bash curl -X POST https://mcp.popapi.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer your_license_key" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Available tools (16) The same 11 tools from the [local version](mcp.md) (SdI/PEPPOL/KSeF/ZUGFeRD/PDF creation, Zoho sync, status, verification, preservation), plus **5 onboarding tools** (`pop_onboarding_request_otp`, `pop_onboarding_verify_otp`, `pop_onboarding_get_status`, `pop_onboarding_get_account_setup`, `pop_onboarding_save_account_setup`) that **don't require the Bearer header**: they use their own temporary `onboarding_token`, designed specifically for creating a brand-new account. See [onboard-via-ai-assistant](../getting-started/onboard-via-ai-assistant.md) for the full flow. ## Good to know - The server runs as a serverless function: it's stateless, every request is independent — don't expect it to remember earlier conversations beyond whatever the MCP client itself manages. - `https://mcp.popapi.io/health` is a status endpoint meant for monitoring, not for conversational use. ## Common errors - **Immediate `401 unauthorized_user`** — the `Authorization` header is missing or not in the `Bearer ` format: the server rejects it before even contacting POP. - **Key present but request rejected by POP** — the key is formally valid but POP rejects it (insufficient plan, integration not active): the returned error is POP's, not the MCP server's. - **Client can't find the right tool** — check that you connected the client to the `/mcp` URL (not the `https://mcp.popapi.io/` home page, which is just the informational landing page). ## Related configuration For the local install (stdio, via npm) see [mcp](mcp.md). For the full invoice data contract, see [api/overview](../../api/overview.md), [api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md), and [api/zoho](../../api/zoho.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/n8n ## Goal Generate SdI, PEPPOL, KSeF, or ZUGFeRD invoices, check their status, and validate EU VAT numbers inside an n8n workflow, without manually calling the REST API. ## Prerequisites - An n8n instance (cloud or self-hosted). - A valid POP `license_key` (see [get-your-license-key](../getting-started/get-your-license-key.md)). ## What the POP node offers The official node (`n8n-nodes-pop`) exposes two resources: - **Invoice** — Create SdI Invoice (XML), Create Peppol Invoice (UBL), Create KSeF Invoice (FA(3) XML), Create ZUGFeRD Invoice, Get Invoice Status, Get Peppol Document, Verify SdI Document (XML), **Sync Document to Zoho** (syncs an invoice or credit note to Zoho Books/Invoice via the native POP connector — requires Zoho already connected on the POP account, no minimum plan; optional connector-status check before sending). - **VAT Validation** — Validate VAT Number, via the EU's VIES service (not the POP API). Create KSeF Invoice shares the same invoice input form as the other creation operations, plus a **Submit via KSeF Provider** (Yes/No) option to send the document straight to the KSeF provider instead of only generating the XML locally — equivalent to setting `integration.use = ksef-via-pop` on the underlying REST request (see [api/ksef](../../api/ksef.md)). Create ZUGFeRD Invoice only generates the ZUGFeRD/Factur-X package (no send option: submission is always handled internally by POP, see [api/zugferd](../../api/zugferd.md)). It doesn't cover PDF: for that domain use the REST API directly (see [api/pdf](../../api/pdf.md)). For Zoho there are two distinct, non-equivalent paths: **Sync Document to Zoho** above (uses the Zoho connector already linked on your POP account, no separate OAuth setup in n8n) or the dedicated [n8n-zoho](n8n-zoho.md) package (self-hosted, Zoho OAuth credentials configured directly in n8n, routed through a signed webhook — install via npm only, it isn't approved/listed on n8n's official Community Nodes registry). Pick based on where you want the Zoho OAuth connection to live. ## Steps 1. Install the official node: . 2. Create a **POP API** credential with your `license_key` (a single field, sent as the `X-API-Key` header); n8n verifies it by calling `GET /account-profile`. 3. Add the POP node, choose the resource and operation (e.g. *Invoice → Create SdI Invoice (XML)*). 4. Choose the input mode: **Use Incoming JSON** (uses the incoming JSON as-is), **Form Fields** (fill in the fields in the node), **JSON**, or **Raw (XML/Other)**. 5. If you want POP to send the document immediately (not just generate it), enable **Send Invoice**: it automatically adds the `sdi-via-pop` or `peppol-via-pop` integration to the request. ## Verify Run the workflow once and check the node's output: on success it returns XML/JSON depending on the operation; on error, a `NodeApiError` with the URL, HTTP status, and response body — useful for immediately spotting which field failed validation. ## Common errors - **Node not authenticated** — the `license_key` in the credential is invalid or has been regenerated: update it from `Account > API`. - **Missing fields in the mapped payload** — same validation as the underlying REST API: check the guide for the specific route (e.g. [api/sdi](../../api/sdi.md)) for the required fields. - **Line discount not applied** — if you enable "Discount" on an order line, the "Discount Percent" field is required: without it, validation fails. - **VIES validation slow or failed** — the *Validate VAT Number* node automatically retries up to 5 times on transient VIES service failures (`MS_UNAVAILABLE`, `TIMEOUT`, etc.); a persistent failure after the retries indicates the VIES service is unreachable, not a POP configuration issue. - **The workflow stops on a single error** — if you want n8n to continue with the following items instead of stopping the workflow, enable "Continue On Fail" on the node: the error is attached to the output item instead of interrupting execution. ## Related configuration For the alternative Zoho path (self-hosted, OAuth configured in n8n, manual npm install only), see [n8n-zoho](n8n-zoho.md) (or [api/connectors](../../api/connectors.md) for the underlying routing mechanism). For details on the native connector used by **Sync Document to Zoho**, see [zoho](zoho.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/n8n-zoho ## Goal Automatically create invoices (`TD01`) and credit notes (`TD04`) in **Zoho Invoice** or **Zoho Books** from documents generated by POP, using the official npm package [`n8n-nodes-pop-zoho`](https://www.npmjs.com/package/@getpopapi/n8n-nodes-pop-zoho) on your own self-hosted n8n instance. This is a **separate, distinct package** from [`n8n-nodes-pop`](n8n.md) (which handles SdI/PEPPOL/VIES and, via its **Sync Document to Zoho** operation, also a simpler native Zoho sync — see [n8n](n8n.md)) — install both only if you need both capabilities, or prefer this path if you want the Zoho OAuth connection to live inside n8n itself. **Installation note**: this package is published on npm but is not approved/listed on n8n's official Community Nodes registry — n8n's **Settings → Community Nodes → Install** button will not find it. It must be installed manually (see below), and as a result **it doesn't work on n8n Cloud**, only on a self-hosted instance. ## Prerequisites - A **self-hosted n8n** instance (v2+), Node.js 18+. Not available on n8n Cloud (see note above). - A **Zoho Invoice** or **Zoho Books** account, with an OAuth2 application created in the Zoho API Console for your region, and tax rates configured in Zoho (one entry per percentage used in your POP payloads). - A POP account with the n8n connector enabled and a webhook already registered in the **Webhooks** panel. ## Steps 1. Manual install (n8n's "Community Nodes" installer won't find this package): ```bash git clone https://github.com/getpopapi/n8n-nodes-pop-zoho.git cd n8n-nodes-pop-zoho npm install npm run build ln -s $(pwd)/dist/nodes/PopZohoInvoice/PopZohoInvoice.node.js ~/.n8n/custom/PopZohoInvoice.node.js ln -s $(pwd)/dist/credentials/ZohoInvoiceOAuth2Api.credentials.js ~/.n8n/custom/ZohoInvoiceOAuth2Api.credentials.js ln -s $(pwd)/dist/nodes/PopZohoInvoice/pop-zoho-invoice.svg ~/.n8n/custom/pop-zoho-invoice.svg n8n start ``` 2. On the [Zoho API Console](https://api-console.zoho.com), create a **Server-based Application** with redirect URI `https:///rest/oauth2-credential/callback`. 3. In n8n, create a **Zoho OAuth2 (Invoice / Books)** credential: product, region, Organization ID (from Zoho → Settings → Organization Profile), Client ID/Secret from the app you just created. Click **Connect** to complete authorization. 4. Build the workflow: **Webhook node** (Authentication: `None`, Respond: `Using 'Respond to Webhook' Node`, path `webhook/zoho`) → **POP → Zoho** node → **Respond to Webhook**. 5. Copy the Webhook node's production URL and register it in POP's **Webhooks** panel, setting the **Connector** field to **"n8n Connector — Zoho"**. 6. In the POP → Zoho node, set the **License Key** (always the account's **default** key, from `popapi.io → Account → API → API Key (default)` — never a platform-specific Shopify/WooCommerce key) and click the refresh button to fetch the **RSA public key**. ## Verify Send a request with `environment: "sandbox"` (or enable **Dry Run** on the node): the response includes `dry_run: true` and the `zoho_body` that would have been sent to Zoho, without creating anything for real and without consuming quota. ## Good to know - The node's **Invoice Status** field controls the status of the invoice created in Zoho: if set to **Sent**, the node automatically performs the status transition Zoho requires after creation, instead of leaving the invoice in `draft`. ## Common errors - **`auth_error`** — the License Key in the node isn't the default one: POP always signs with the default key regardless of which platform generated the document. - **`tax_not_found`** — one of the tax rates used in your POP payloads isn't configured in Zoho → Settings → Taxes: add it. - **`contact_ambiguous`** — multiple Zoho contacts match the same VAT/email/name: resolve the duplicate in Zoho before retrying. - **`unsupported_doc_type`** — only `TD01` (invoice) and `TD04` (credit note) are supported in v1. ## Related configuration For the generic routing mechanism this node relies on (the `/connector/zoho` route, HMAC+RSA signing, POP-side error codes), see [api/connectors](../../api/connectors.md). To choose between this path and the other available channels, see [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/paid-member-subscriptions ## Goal Generate e-invoices for subscriptions sold through **Paid Member Subscriptions** (by Cozmoslabs), using POP as the invoicing engine instead of (or alongside) WooCommerce. Don't confuse it with [Paid Memberships Pro](paid-memberships-pro.md): these are two different membership plugins with similar names but separate POP integrations. ## Prerequisites - **Paid Member Subscriptions** (Cozmoslabs) plugin installed and active on the site. - The **"Tax & EU VAT"** module of Paid Member Subscriptions active: without it, POP can't show fiscal billing fields on subscription forms or account pages — this is a prerequisite specific to this integration, not required for PMPro. - POP installed with your sending channel (SdI via POP, Fatture in Cloud, Aruba, SdI via PEC...) already configured: the integration doesn't replace the sending channel, it adds a source of orders to invoice. ## Steps 1. Install and activate **POP** on the WordPress site. 2. In Paid Member Subscriptions, check that the **Tax & EU VAT** module is active — if it isn't, POP shows an explicit warning on forms and payment pages instead of the fiscal fields. 3. Go to **POP > Integrations** and activate the **Paid Member Subscriptions** card. Like PMPro, it isn't mutually exclusive with the other sending channels: you can keep it active alongside a regular WooCommerce store. 4. Once active, POP adds the same billing fields used in WooCommerce (customer type, SdI/PEC code, tax code/VAT number) to subscription forms and account pages, and uses that data to generate the invoice for every recorded payment. ## Verify After a test payment on a subscription plan, check that POP generated the document with the billing data entered and with VAT correctly calculated. ## Common errors - **Billing fields don't appear on the subscription form** — the most common cause is the **Tax & EU VAT** module not being active in Paid Member Subscriptions: enable it before checking anything else. - **Can't edit fiscal fields from the payment detail in admin** — same cause: without that module active, POP can't render the fields even on the admin side. - **Billing fields don't appear at all** — check that the integration is activated both on the POP side (`POP > Integrations > Paid Member Subscriptions`) and that the Cozmoslabs plugin is actually active: both conditions are required. ## Related configuration To activate a sending channel (required for POP to transmit the invoice to SdI or the chosen provider), see [sdi-via-pop](sdi-via-pop.md) or [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/paid-memberships-pro ## Goal Generate electronic invoices for memberships sold through **Paid Memberships Pro (PMPro)**, using POP as the invoicing engine instead of (or in addition to) WooCommerce. Don't confuse it with Cozmoslabs' [Paid Member Subscriptions](paid-member-subscriptions.md): these are two different membership plugins with similar names but separate POP integrations. ## Prerequisites - The **Paid Memberships Pro** plugin installed and active on the site. - POP installed with your sending channel (SDI via POP, Fatture in Cloud, Aruba, SDI via PEC...) already configured: the PMPro integration doesn't replace the sending channel, it's added as a source of orders to invoice. ## Steps 1. Install and activate **POP** on the WordPress site. 2. Go to **POP > Integrations** and activate the **Paid Memberships Pro** card. Unlike the sending channels (Fatture in Cloud/Aruba/SDI), this integration is **not** mutually exclusive with the others: you can keep it active alongside a regular WooCommerce store and its sending channel. 3. Once active, POP automatically adds to the PMPro checkout the same billing fields used in WooCommerce (customer type private/company/freelance, SDI code/PEC, fiscal code/VAT number), and will use that data to generate the invoice for every payment recorded by PMPro. ## Tax calculation The addon automatically calculates VAT on PMPro memberships using the rates configured in POP for the billing country: **no additional option needs to be enabled** for POP to generate the tax on the document — it's an always-on behavior of the addon, not a switch you flip. If under **PMPro > Settings > Advanced** you also have PMPro's native option for tax calculation at checkout, that concerns what the customer sees during payment (the amount shown at checkout), not whether POP calculates VAT on the invoice: these are two separate things, and the second doesn't depend on the first. ## Verify After a test payment on a PMPro membership level, check that POP generated the document with the billing data entered at checkout and with VAT correctly calculated. ## Common errors - **The billing fields don't appear at PMPro checkout** — verify that the integration is enabled both on the POP side (`POP > Integrations > Paid Memberships Pro`) and that PMPro is actually active: both conditions are required. - **VAT doesn't appear on the invoice** — it isn't tied to PMPro's native toggle under Settings > Advanced: instead check that the customer's billing country has a rate configured in POP. ## Related configuration To activate a sending channel (required for POP to transmit the invoice to the SDI or the chosen provider), see [sdi-via-pop](sdi-via-pop.md) or [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/peppol ## Goal Activate sending electronic invoices via the PEPPOL network directly from your WordPress or Shopify store. France uses a distinct corridor (gov-fr, not generic PEPPOL): see [france-peppol](france-peppol.md). ## Prerequisites - On WordPress: no minimum plan, activation and sending are available on every plan (including Free), using credits. On Shopify, the **Basic plan or higher** is required instead. - A complete address (street, city, postal code) for the legal entity — PEPPOL requires these fields to register the endpoint. - For Germany: you must explicitly choose the "document corridor" (`zugferd` or `peppol`) — without this choice, activation won't complete. ## Steps You can activate PEPPOL in three equivalent ways: 1. **Account panel** — on `popapi.io`, go to **My Account > Integrations**, open the PEPPOL tab and enable **"Activate PEPPOL"**. 2. **From the plugin/app, with an existing account** — on WordPress: the **General** tab, refresh the license information, then go to **Integrations** and click the PEPPOL card to activate it. 3. **Guided setup wizard on first access** — if you're setting up the account for the first time and your country uses the PEPPOL corridor, activation happens automatically when the wizard is completed. ## Automatic sending - **WordPress** — the **Advanced > Automatic invoice sending** tab: enable sending via WP-Cron in the background. - **Shopify** — automatic sending on paid orders is available on paid plans; it's disabled by default for private customers (PEPPOL is a B2B corridor). ## Manual sending Use the **"Send Invoice"** button in the invoices table to send a single document to the PEPPOL network. ## Common errors - **"This field is required when PEPPOL is enabled."** — the legal entity's address, city, or postal code is missing: complete them in the account panel before retrying. - **Activation blocked for Germany** — for `DE` accounts you need to choose the document corridor (`zugferd` or `peppol`) before activation succeeds. - **Automatic sending doesn't start for a private customer** — expected: PEPPOL is designed for business recipients, automatic sending to private customers is disabled by design. ## Related configuration For the API contract details (payload, UBL field mapping), see [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/sdi-via-pec ## Goal Send valid electronic invoices (B2B and B2C) to the Sistema di Interscambio (SDI, Italy's Exchange System) via a PEC mailbox (Posta Elettronica Certificata, Italy's certified email), using the **SDI via PEC** addon. ## Prerequisites - The **SDI via PEC** addon installed and active. - A PEC mailbox with SMTP access (host, port/security, username, password). - Only **one** invoice-sending integration can be active at a time: deactivate Fatture in Cloud or Aruba before activating this one. ## Steps ### 1. Configure the PEC mailbox (SMTP) In the plugin's **SDI via PEC** tab, enter your PEC mailbox parameters: SMTP host, connection security type, username and password. The plugin also tracks a password expiration date, useful as a reminder to renew it before it stops working. If your PEC provider requires two-factor authentication for SMTP access (e.g. Aruba PEC), you'll need to generate a dedicated application password from the provider's panel (for Aruba PEC: **account management > Password for mail programs**) and use that instead of the normal password — this is a requirement of the PEC provider, not a plugin setting. ### 2. Verify/customize the SDI recipient address The **PEC recipient address for the Sistema di Interscambio** field defaults to `sdi20@pec.fatturapa.it`; you can only override it if your case requires a different address. Note: this field, along with "Password for the sender's PEC address" and "Username for the sender's PEC address" further down, is shown in Italian in the plugin UI regardless of the site's language — there is no English label for these specific fields. ### 3. Configure automatic sending 1. **Order status that triggers sending** ("Enable auto-send for status:") — defaults to "Completed", can be set to another WooCommerce order status. 2. **Enable automatic sending** ("Enable automatic sending") — when a configurable delay in hours (default **12 hours**) elapses after the configured status is reached, the invoice is sent via PEC to the SDI. ### WP-Cron reliability Automatic events depend on **WP-Cron**, which only fires with traffic on the site. If your site gets little traffic, add a system Cron job (e.g. every 30 minutes): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` ### Diagnostic log To trace scheduling and execution of sends, add this to `wp-config.php`: ``` define("WP_FATT_SDI_LOG", true); ``` ## Manual sending Use the **"Send"** button on the invoice to transmit it immediately via PEC; the plugin marks it as sent once the operation completes. ## Verify Check the configured PEC mailbox: it must show the message sent to the SDI recipient, and the invoice in the plugin must show as sent. ## Common errors - **The SMTP connection fails with "invalid credentials"** — if you've enabled two-factor authentication on the PEC mailbox, the normal password isn't enough: generate a dedicated application password. - **Automatic sending doesn't start** — check WP-Cron/the system Cron job first; it's the most common cause. - **The SMTP password has expired** — the plugin tracks the expiration date you entered: if the provider changed it, update it in the SMTP configuration. ## Related configuration For the native alternative without a PEC mailbox, see [sdi-via-pop](sdi-via-pop.md). To understand an SDI rejection, see [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/sdi-via-pop ## Goal Activate **SDI via POP**, the native channel that sends electronic invoices to the Sistema di Interscambio (SDI, Italy's Exchange System) directly from the WordPress site through the POP plugin, without going through Fatture in Cloud, Aruba, or a PEC mailbox. ## Prerequisites - No minimum plan: activation is available on every plan, including Free. Sending uses the credits available on your account. - Only **one** invoice-sending channel can be active at a time: if Fatture in Cloud, Aruba, or SDI via PEC is already active, deactivate it before activating SDI via POP. ## Steps You can activate SDI via POP in two equivalent ways. ### From the account panel (popapi.io) After creating the account, go to **My Account > Integrations**, open the **SDI via POP** tab and enable **"Activate SDI via POP"**; you can also optionally enable digital signature and legal storage (conservazione sostitutiva). ### From the WordPress plugin If you've already completed the guided account setup: 1. Go to **POP > General** and refresh the license information to sync the connection. 2. Go to **POP > Integrations** and activate SDI via POP by clicking its card. If instead you're setting up the account for the first time, you can activate it directly from the company data section of the guided setup wizard: activation happens automatically when it's completed. ## Automatic and manual sending - **Manual sending** — the **"Send Invoice"** button in the invoices table; then use the **"Notifications"** button to manually check the outcome. - **Automatic sending** — the **POP > Advanced > Automatic invoice sending** tab: enable sending via WP-Cron in the background instead of synchronously on order status change. ## Verify After sending, check the outcome via the **"Notifications"** button on the invoice: it must show the status received from the SDI (delivered, rejected, etc.). ## Common errors - **Can't activate SDI via POP while another channel is active** — sending channels are mutually exclusive: first deactivate Fatture in Cloud, Aruba, or SDI via PEC from the same Integrations screen. - **Sending returns a generic error** — the most common causes reported by the system are: the channel doesn't match the active one, the integration isn't configured, an invalid action, or a document with an identifier that already exists. Verify that SDI via POP is actually the active channel and retry. ## Related configuration For the data contract (payload, field mapping), see [api/sdi](../../api/sdi.md). To understand an SDI rejection, see [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). For the alternative via a PEC mailbox, see [sdi-via-pec](sdi-via-pec.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/webhook ## Goal Automatically send every document generated by POP (XML or PDF) to an external tool: Zapier, Make (Integromat), a CRM, Google Drive, or a custom endpoint. ## Prerequisites - On WordPress: no minimum plan, webhook delivery is available on every plan (including Free), using credits. On Shopify, the **Basic plan or higher** is required instead. - An HTTP endpoint listening (the destination webhook URL). ## Steps 1. On `popapi.io`, go to **My Account > Integrations > POP to Webhook > Connect**. 2. Configure: - an identifying name - the destination webhook URL - the data format: **JSON** or **XML** - the activation switch 3. On **WordPress**: in the POP plugin go to **Advanced > Webhook**, enter the webhook ID created in the previous step, enable it, and — if you want background sending instead of synchronous — also enable automatic sending via CRON. 4. On **Shopify**: enter the webhook ID in the app settings; an icon will appear in the invoices list to send the data. ## Formats - **JSON** — designed for no-code platforms (Zapier, Make): the data is automatically flattened into a structure that's easy to map. - **XML** — suited to archiving or systems that require the FatturaPA standard; it can also be sent as an attachment. You can configure multiple webhooks with different URLs and formats at the same time. ## Common errors - **Invalid webhook URL** — verify the URL is publicly reachable and responds successfully (it's not enough for it to be syntactically correct). - **Unsupported data format** — only use `JSON` or `XML`; other formats are rejected. - **The webhook receives nothing in sandbox** — an expected limitation: webhook delivery isn't available in the sandbox environment (see [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Related configuration For the specific case of forwarding to n8n with a dedicated connector (e.g. Zoho), see [api/connectors](../../api/connectors.md) and [n8n](n8n.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/wordpress-invoice-abilities ## Goal Let an AI assistant connected to your WordPress site (or a command-line script) search invoices and credit notes **already generated** by POP on WooCommerce, Paid Memberships Pro, or Paid Member Subscriptions, and retrieve their XML, PDF, or structured data — without granting direct access to the database or the filesystem. This is a different mechanism from POP's hosted MCP server (see [mcp](mcp.md) and [mcp-remote](mcp-remote.md)): that one talks to the POP Cloud API and creates new documents for any platform; this one works **locally on your own WordPress site**, on orders your store has already invoiced, and doesn't generate anything new — it only serves already-cached documents. ## Prerequisites - pop-wordpress 6.9.11 or later. - For the **WP-CLI** path: no other dependency, just shell/SSH access to the site. - For the **AI assistant** path: the site needs a registered Abilities API (`wp_register_ability()` function available, typically via the "Abilities API" plugin) and an MCP server exposing the site's abilities (typically the "MCP Adapter" plugin) — pop-wordpress only registers its own abilities when these are present, and does nothing otherwise. ## What it exposes Four abilities, category `pop`: - `pop/search-invoices` — search invoices/credit notes by provider, customer, address, status, document type, or date range; returns document ids for use with the other three. - `pop/get-invoice-data` — structured document data (invoice number, status, total, currency, dates, active fiscal channel, formats available in cache). - `pop/get-invoice-xml` — cached XML (invoice/credit note). - `pop/get-invoice-pdf` — cached PDF metadata and URL. ## Steps ### AI assistant path (Abilities/MCP) 1. Install and activate the **Abilities API** and **MCP Adapter** plugins on the WordPress site, in addition to pop-wordpress. 2. Connect your AI assistant to the site's MCP server (address and authentication depend on the installed MCP Adapter plugin). 3. Ask your assistant something like *"Find July invoices for customer Smith"*: the assistant uses `pop/search-invoices`, then `pop/get-invoice-data`/`xml`/`pdf` on the document it found. By default, every ability requires the WordPress `manage_options` capability (filterable via `wc_el_inv-abilities-capability`), because it's reachable over HTTP. ### WP-CLI path ```bash wp popapi invoice search --customer="Smith" --date_from=2026-07-01 wp popapi invoice get --provider=woocommerce wp popapi invoice xml --raw wp popapi invoice pdf ``` - `search` accepts `--provider`, `--customer`, `--address`, `--status`, `--document_type`, `--date_from`, `--date_to`, `--limit` (default 10, capped at 50), `--offset`. - `get`/`xml`/`pdf` require `` as a positional argument, plus `--provider` (required when multiple providers are active on the site), `--document_type`, `--parent_id` (for credit notes). - All four accept `--format=table|csv|json|yaml|ids|count` and `--fields=`. - `xml --raw` prints only the XML content, with no metadata. WP-CLI commands do **not** enforce the `manage_options` gate: shell/WP-CLI access to the site is already a stronger trust boundary than a WordPress capability, so no `--user` is required. ## Verify `wp popapi invoice search --format=count` should return a number consistent with invoiced orders on the site. On an existing document, `wp popapi invoice get --provider=` should return structured data with no errors. ## Common errors - **`pop_ability_forbidden`** (403, AI path only) — the authenticated user lacks the required capability: check the role or the `wc_el_inv-abilities-capability` filter. - **`pop_ability_invalid_provider`** — the site has multiple providers active (e.g. WooCommerce and PMPro together) and you didn't specify `--provider`/`provider`: the message lists the active providers to choose from. - **`pop_ability_document_not_found`** — the document id doesn't exist for the given provider/type. - **`pop_ability_xml_not_found` / `pop_ability_pdf_not_found`** — the document has no cached XML/PDF: these abilities only serve already-generated documents, they don't create new ones on the fly. - **No ability registered (silent, no error)** — the Abilities API/MCP Adapter plugins are missing: the WP-CLI path remains available regardless of these plugins. ## Related configuration To generate or send new documents from an AI assistant (not just retrieve existing ones), see [mcp](mcp.md) or [mcp-remote](mcp-remote.md), which work at the POP Cloud API level and don't require extra WordPress plugins. --- ## Source: https://docs.popapi.io/en/guides/integrations/zoho ## Goal Sync invoices and credit notes generated by POP with **Zoho Invoice** or **Zoho Books**, without having to manage a webhook or an n8n workflow yourself. ## Prerequisites - An active Zoho Invoice or Zoho Books account. - On WordPress: no minimum plan, syncing is available on every plan (including Free), using credits. On Shopify, the **Basic plan or higher** is required instead. ## Activation (two steps) 1. **POP account** — go to `popapi.io > My Account > API Integrations` and complete the OAuth authorization towards Zoho. From here Zoho is one of the available sending channels: activating it as the primary channel automatically deactivates any other channel already active (SdI via POP, PEPPOL, KSeF, Fatture in Cloud, Aruba, SdI via PEC — they're all mutually exclusive). 2. **Plugin/app side** — authorizing the POP account alone isn't enough: it also needs to be enabled locally. ### WordPress On the **Integrations** tab, find the **"Zoho (via POP)"** card and click **Activate**. If the POP account hasn't completed authorization yet, the card shows *"Activate and connect Zoho in your POP account first."* — go back to step 1. ### Shopify Go to **Settings > Invoice Channel** and select the **"Zoho via POP"** option among the available channels (radio button selector). If the option is disabled with an "(unavailable)" badge, a banner explains why (e.g. the POP account isn't ready, or the active connector on the POP side isn't Zoho). ## Manual and automatic sending **WordPress:** - Manual — **"Create Zoho Invoice"** / **"Create Zoho Credit Note"** buttons on the order; after sending they become **"Zoho invoice created"** / **"Zoho credit note created"**. - Automatic — uses the same automatic-sending setting already available for other channels (an order status that triggers the send, with an optional delay in hours). **Shopify:** - Manual — **"Send invoice to Zoho"** / **"Send credit note to Zoho"** buttons on the Orders page. - Status shown in the table: **"Zoho: sent"** or **"Zoho: pending"**. ## Credit notes need the invoice synced to Zoho first A credit note cannot be sent to Zoho if the linked order doesn't already have a successfully synced Zoho invoice: - **WordPress** — the button stays blocked with: *"Zoho credit notes require a Zoho parent invoice reference on the original order. Create the Zoho invoice first."* - **Shopify** — same block, message: *"Send the parent invoice through Zoho before generating or sending the credit note."* Fix: send the original invoice to Zoho first, then the credit note. ## Sandbox - **WordPress** — a sandbox send doesn't create anything in Zoho: it returns a dry-run confirmation, *"Zoho sandbox dry run succeeded. No document was created in Zoho."* — this is expected behavior, not an error. - **Shopify** — a queued auto-send is blocked with: *"Zoho auto-send is disabled while POP sandbox mode is active. Switch the environment back to live to process queued invoices."* ## Verify After activation, check in the plugin/app that the Zoho status shows connected and that the linked product (Zoho Invoice or Zoho Books) is correctly indicated, not "not available". ## Common errors - **The product shows "not available"** — the OAuth authorization wasn't completed or has expired: redo step 1 from the account panel. - **I activated Zoho and another channel deactivated itself** — expected behavior: the main channels are mutually exclusive. - **The credit-note send button stays blocked** — see the section above: the original order is missing its linked Zoho invoice. - **"The previous Zoho send may have timed out..."** (WordPress) — the previous send may not have gotten a response in time: if the document was actually created in Zoho, confirm and save the returned ID manually; otherwise cancel and retry. - **Sync fails due to a missing contact** — check the auto-create-contacts option; if disabled, the contact must already exist in Zoho before syncing. ## Related configuration To choose between this channel and the others available, see [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). For endpoint details, see [api/zoho](../../api/zoho.md). --- ## Source: https://docs.popapi.io/en/guides/integrations/zugferd ## Goal Choose which document corridor to use for a German (`DE`) account: **ZUGFeRD/Factur-X** or **PEPPOL**. The choice is mandatory for `DE` accounts and determines which format POP generates. ## Prerequisites - A POP account with country set to `DE`. ## Steps 1. The choice is made **only from the POP account panel** (the onboarding wizard or `account-setup`): there is no dedicated control in either the WordPress plugin or the Shopify app: both only show the current active status (a badge), read-only. 2. If you don't choose explicitly, for a `DE` account with no registered PEPPOL legal entity, the default value is **`zugferd`**. 3. To switch to `peppol`, register a PEPPOL legal entity (see [integrations/peppol](peppol.md)): from that point the corridor is automatically forced to `peppol` and **can no longer switch back to `zugferd`**, the choice locks as soon as a PEPPOL legal entity exists (live or sandbox). ## Verify In the WordPress plugin, the **ZUGFeRD** section in settings shows the current status and credit consumption; in the Shopify app a "ZUGFeRD active" badge appears when the corridor is `zugferd`. In both cases the value shown reflects what's set in the account panel, it isn't editable from there. ## Using ZUGFeRD once it's active (WordPress) When the account's corridor is `zugferd`, the WordPress plugin replaces the separate XML/PDF buttons with a dedicated experience, both in the order list and in the order detail: - **ZUGFeRD button**: downloads the hybrid PDF (the one with embedded XML), meant for everyday use. - **ZIP download**: downloads all three files (hybrid PDF, standard PDF, EN16931 XML) in a single archive. It's served from the local cache and **doesn't consume additional credits** beyond the initial generation. - **Order-completed email**: the hybrid PDF is automatically attached to the order-completed email. Resending that email from the order detail doesn't delete the already-generated cached files, you can resend it as many times as needed without regenerating the bundle. ## Good to know - Every ZUGFeRD bundle generated consumes **1 credit** (generation itself is the only billed action, unlike XML/UBL/KSeF where generation is free and only sending consumes a credit); re-downloading the same bundle from the cache (including the ZIP) doesn't consume further credits. - On Shopify, automatic generation on paid orders **does not include** ZUGFeRD documents: when the corridor is `zugferd`, automatic sending is explicitly skipped, because the bundle is made up of 3 files (visual PDF, EN16931 XML, hybrid PDF) and requires a manual action to choose what to generate. - See [api/zugferd](../../api/zugferd.md) for the API contract of the generated bundle. ## Common errors - **"Germany requires a document corridor selection."**: a `DE` account hasn't chosen a corridor yet, go to the wizard/account panel and select `zugferd` or `peppol`. - **"Invalid Germany document corridor. Allowed values: zugferd, peppol."**: a value other than the two allowed ones was sent, use exactly `zugferd` or `peppol`. - **Can't switch back to ZUGFeRD after activating PEPPOL**: expected behavior, once a PEPPOL legal entity is registered, the corridor stays locked to `peppol`. --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/admin-error-email-notifications ## Symptom The WordPress site's administrator email address (`admin_email`) automatically receives an email when something goes wrong generating or transmitting an invoice, without anyone having explicitly requested it. ## Cause This isn't an optional add-on you enable: it's a behavior **built into the POP plugin**, always active, designed to flag problems immediately without having to check the logs manually. The emails are sent to the site's admin address (`get_bloginfo('admin_email')`) in these cases: - **Account setup not completed** — if the wizard hasn't been completed (the link to the POP account is missing) and the site still tries to generate a document, a "Complete Your Account Setup" email arrives with the steps to complete the configuration. - **POP API error** — any error response from the generation/send-document calls generates an email with the subject and technical context of the error. - **Overquota** — if the account has run out of available credits, a dedicated "POP API overquota block" email arrives. - **Rejection by SDI** — if a rejection notification (type `NS`) arrives for an invoice sent to the SDI, an email arrives with the subject "POP - SDI Reject Notification" and the order details. ## Fix There's nothing to "enable": these notifications are automatic. If you receive them, act on the cause stated in the body of the email: 1. **Account setup not completed** → go to `POP → Electronic Invoice - Settings`, tab **General**, and complete/link the account (or restart the wizard). 2. **Generic API error or overquota** → check the technical message included in the email: it states the status code and the context of the failed call; check the account's plan and remaining credits. 3. **SDI rejection** → open the invoice indicated and check the rejection details before correcting and resending. If you **don't want to receive these emails** at that address, the only lever is to change the WordPress site's `admin_email` (a general WordPress setting, not a POP option): there is no dedicated toggle in POP to disable them individually. ## Related configuration For the checklist to follow when an SDI invoice is rejected see [sdi-invoice-rejected](sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/credit-note-generation ## Symptom A refund generates a credit note XML that doesn't match what was refunded, or the document is rejected/not generated correctly. ## Cause The most common causes: - **The credit note was generated before the original invoice was actually sent** — a credit note only makes sense if it's linked to an invoice that has already been issued/sent: it must carry the reference (number and date) of the linked invoice. - **The refund was recorded only as an amount, without restocking/reversing the quantities** — if you only enter the refunded amount without cancelling the quantities of the products involved, the document doesn't correctly reflect what was returned/cancelled. ## Fix 1. Check that the original invoice was actually sent before proceeding with the refund: if it wasn't, consider correcting/sending the original invoice first. 2. When recording the refund in WooCommerce, **reverse the quantities** of the affected products (don't just enter a free-form refund amount): that's what allows the document to correctly reflect the cancelled lines. 3. After the refund, POP automatically generates the credit note XML linked to the order (see [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md) for the exact trigger). Download it from the **Invoices** tab. 4. If you use a transmission channel/add-on connected to an external accounting system, sending the credit note to that system may require a manual upload, separate from the document generation itself: check the specific behavior of the active channel. ## Related configuration For the exact credit note payload requirements (`connected_invoice_data.id`/`date`) on the API side, see [api/sdi](../../api/sdi.md); to understand when the order actually generates the XML see [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/delete-an-invoice ## Symptom There's no "delete invoice" button in the **Invoices** tab or in POP's document list. ## Cause Invoices generated by POP are **structurally linked to the order** that originated them: they don't exist as independent entities in the database. If the order doesn't exist (or is deleted), the associated invoice no longer exists either. This is true whether you're using the POP plugin alone or with a transmission channel/add-on active (Fatture in Cloud, Aruba, etc.) for the document generation part on the WordPress side. ## Fix To "delete" an invoice, delete the linked WooCommerce order: 1. Go to `WooCommerce > Orders`. 2. Find the order corresponding to the invoice number to remove. 3. Move it to trash or delete it permanently, following the standard WooCommerce procedure. **Before doing this, consider the tax implications**: if the invoice had already been sent/transmitted (e.g. to the SDI, or uploaded to a connected external accounting system), deleting the local order **does not cancel** the transmission that already took place. For a document that has already been transmitted, the correct route is a credit note, not deletion — see [credit-note-generation](credit-note-generation.md). ## Related configuration To understand when the invoice number is assigned (and therefore which order it "originates" from) see [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/quota-and-overquota ## Symptom A document generation request fails with a quota-related error, or the WordPress plugin shows a warning that the plan's included quota has been exhausted. ## Cause Every POP plan includes a number of monthly operations ("credits") consumed on use. Locally generating a document (XML, PDF, UBL, FA(3)) never consumes a credit: only the following operation, when there is one, consumes it, i.e. sending to a channel (SdI, PEPPOL, KSeF, Zoho, Fatture in Cloud, Aruba, SdI via PEC), webhook delivery, emailing the PDF, or legal preservation. When the included quota runs out: - if your plan **does not** include overquota (extra use beyond what's included), new requests are rejected until the cycle renews or you upgrade; - if your plan **does** include overquota and it's enabled on your account, extra usage continues but may be billed automatically, up to a monthly cap configured on your account. ## Check your account status `GET /wp-json/api/v2/overquota-policy` (authenticated with your `license_key`) returns the full status: included quota (`included_quota`), quota already used (`used_quota`), whether overquota is enabled (`overquota_enabled`/`effective_overquota_enabled`), the rate per extra request configured on your account (`rate_eur`), and the monthly cap (`monthly_cap_eur`), plus a readable status message (`status_message`) with the suggested action (`suggested_action`). ## Fix - **Quota exhausted, overquota not enabled**: wait for the monthly cycle to renew, or upgrade the plan from `popapi.io > Account`. - **Overquota enabled but you've reached the configured monthly cap**: extra requests are blocked until the cycle renews or the cap is raised, contact support to review your account's monthly cap. - **No valid payment method on file**: chargeable overquota requires a valid Stripe payment method saved on the account, add one from the account panel before extra usage can continue. - **You have an overquota balance to settle**: if an overquota order from a previous cycle has been unpaid for more than 30 days, new chargeable overquota is blocked until you settle it, check `settlement_pending` in the `overquota-policy` response or the payment status from the account panel. - **You don't know whether overquota is enabled on your account**: it's not a self-service option from the plugin, contact support to enable it or change its limits. ## Related configuration See [api/overview](../../api/overview.md) for API call authentication. --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/sdi-invoice-rejected ## Symptom The call to `create-xml` (or the linked SdI submission) returns a JSON error instead of the expected XML/outcome, or the document is rejected before it's sent. ## Causes - **Tax regime mismatch** — if both the payload and the account have `tax_regime` set, the two values must match. If they don't, generation fails. - **Credit note on a free plan** — free plans cannot create credit notes (`type: credit_note`). - **Credit note without a reference to the linked invoice** — credit notes require `connected_invoice_data.id` and `connected_invoice_data.date` to be populated. - **Missing recipient routing** — either `transmitter_data.sdi_code` or `transmitter_data.recipient_pec` is required; without one of the two, the submission cannot be routed. - **Incomplete payload** — required fields missing in the shared payload (e.g. supplier/customer data, document total, at least one line in `order_items`). ## Fix 1. Check the `tax_regime` configured on the account (POP panel) and align it with the one sent in the payload, or omit the field from the payload if it's not necessary. 2. If you're generating a credit note, check the active plan and the presence of `connected_invoice_data.id`/`date`. 3. Check that the payload contains `sdi_code` or `recipient_pec` for the recipient. 4. Re-read the JSON error response: the message indicates which validation failed — no need to guess, the response body is the primary source. 5. Try again in sandbox first (see [use-sandbox-environment](../configuration/use-sandbox-environment.md)) to isolate the problem without touching production data. ## Related configuration For the canonical payload field names and documented error codes, see [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/sepa-direct-debit-payments ## Symptom A customer pays for a subscription/membership via **SEPA Direct Debit (SDD)** (direct SEPA debit on an IBAN): the order immediately shows as "processing" and access is activated, but the payment doesn't show as "completed" for a number of days. ## Cause This isn't an error: it's the standard behavior of an **SDD** mandate. Unlike card or bank transfer, an SDD debit requires a waiting period (typically around **14 days**) before the funds are actually withdrawn from the customer's account, because the mandate has to be confirmed by the bank. During this period: - the order shows as "processing" on the payment platform's side; - access/membership is still activated right away, so the customer doesn't have to wait; - the customer receives an initial activation confirmation email, and a second one at the end of the verification period when the payment actually shows as completed. This behavior depends on the payment gateway (e.g. Stripe SDD) and SEPA rules, not on a POP invoicing plugin setting: SDD is not a payment method managed or configured by POP. ## Fix No action is needed to make the payment "complete sooner": it's a constraint of the SEPA system, not something that can be sped up on the site's side. If a customer reports the delay: 1. Confirm that they have received (or will receive) the mandate confirmation email from the bank/ gateway. 2. Reassure them that access is already active in the meantime. 3. If after about 14 days the payment still doesn't show as completed, check the mandate's status directly in the payment gateway's panel (not in POP, which doesn't handle this flow). ## Related configuration This behavior concerns the payment gateway/subscription, not the POP plugin's e-invoicing settings: there is no POP configuration page for SDD. --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/shopify-billing-address-override ## Symptom A Shopify order has an incorrect billing address (street, city, ZIP, name...) and it needs to be corrected before generating/sending the fiscal document, but Shopify doesn't allow editing the billing address of an order that's already been created. ## Cause Shopify doesn't expose an interface to edit the billing address after the order has been created. POP works around this limitation with a set of dedicated order metafields that, when populated, override the corresponding data at document generation time. ## Fix 1. In Shopify Admin, go to **Settings > Custom data > Orders** and create the definitions for the following metafields (namespace `app`, type "Single line text"): - `pop_billing_first_name` - `pop_billing_last_name` - `pop_billing_company` - `pop_billing_address1` - `pop_billing_address2` - `pop_billing_city` - `pop_billing_province` - `pop_billing_zip` - `pop_billing_country` 2. Open the affected order and populate **only** the fields that need correcting: you don't need to fill them all in, even a single field is enough. 3. Save: POP merges field by field — the metafields you set override the order's original data, the other fields keep their original values (billing address, or failing that, the customer/shipping address). 4. Regenerate the document: it will immediately use the corrected address. ## Related configuration This mechanism corrects the **customer's** address on a single order. To permanently replace the **seller/issuer's** address on all documents, see [shopify-seller-fiscal-data](../configuration/shopify-seller-fiscal-data.md). For the general management of customer fiscal data (VAT number, tax code, customer type), see [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/en/guides/troubleshooting/shopify-order-edit-invoice-mismatch ## Symptom You edited an order on Shopify (product swapped, quantity or amount changed) before the invoice was sent through an official channel, but the downloaded PDF/XML still shows the old data. Or: you see a "Credit notes" button on an order where no real refund was ever issued. ## Cause Shopify doesn't always notify POP in real time when you edit an order. So when you request the document again (downloading it, or on payment if sending is automatic), POP checks whether the order was changed since the last generation: if so, it doesn't trust the stored file and generates a new one with the updated data, reusing the same invoice number and progressive already assigned (no new document identity). This check only applies as long as the invoice hasn't already been sent through an official channel (SdI, PEPPOL, KSeF, Zoho) or by email: from that point on the document is protected, and any correction requires a credit note, so an already-issued fiscal document is never rewritten. An edit that only reduces quantities (with no real money moved) creates a "technical" refund record in Shopify that looks identical to a real refund: POP now tells them apart and no longer generates a spurious credit note for these cases. ## Fix 1. After editing the order, **reopen/re-download the document** from the Orders page (or wait for the automatic trigger, e.g. on payment): this is when POP checks alignment and regenerates if needed. Editing the order alone doesn't update the existing file. 2. Check whether the document has already been sent through an official channel: if so, the invoice stays as issued and the correction must go through a credit note from the Orders page (dedicated button, generated from a real Shopify refund). 3. Note: regenerating a document because the order changed consumes a plan credit, same as a new generation. ## Related configuration For the credit note payload requirements (`connected_invoice_data.id`/`date`) on the API side, see [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/es/guides/getting-started/choosing-an-invoicing-integration ## Objetivo Entender qué canal de transmisión activar para tu tienda, entre los disponibles en POP. **Los canales son mutuamente excluyentes**: solo puedes tener uno activo a la vez (activar uno desactiva automáticamente los demás). ## Canales disponibles | Canal | Para quién | Dependencias externas | Notas | | --- | --- | --- | --- | | **SdI via POP** | Quienes quieren el flujo más simple para Italia: ningún servicio externo que configurar | Ninguna | Transmisión directa al SdI, notificaciones gestionadas dentro de POP, verificación automática del código fiscal/número de IVA del destinatario. | | **SdI via PEC** | Volúmenes bajos, quienes ya tienen un buzón PEC (correo certificado) y no quieren cuentas externas adicionales | Buzón PEC | El XML se envía por correo PEC; las notificaciones de resultado deben comprobarse manualmente en el buzón PEC — POP no las gestiona automáticamente. | | **Fatture in Cloud** | Quienes ya usan Fatture in Cloud para contabilidad/facturación | Suscripción activa de Fatture in Cloud | Pasa por la API oficial de Fatture in Cloud; requiere mapear los [métodos de pago](../integrations/fatture-in-cloud-payment-methods.md) y una cuenta de saldo antes del primer envío. | | **Aruba Business** | Quienes ya usan Aruba como proveedor de facturación electrónica | Activación de API en Aruba | Menos flexibilidad de configuración que las demás opciones. | | **PEPPOL** | Ventas B2B al extranjero (red PEPPOL) | Ninguna | No es una alternativa al SdI para Italia: es el corredor para la facturación electrónica intracomunitaria. Cubre 28 países (lista completa en [api/peppol](../../api/peppol.md)) — **España está excluida** (corredor Facturae, aún no compatible), al igual que Irlanda del Norte y Liechtenstein. | | **KSeF** | Ventas hacia Polonia | NIP polaco (número fiscal) | Consulta [activación de KSeF](../integrations/ksef.md) — requiere un registro dedicado independiente del SdI/PEPPOL. | | **Zoho (nativo)** | Quienes usan Zoho Invoice/Zoho Books y quieren una sincronización gestionada directamente por POP | Autorización OAuth a Zoho | Consulta [activación de Zoho](../integrations/zoho.md). No requiere tu propia instancia de n8n. Para cuentas registradas en los Emiratos Árabes Unidos, Arabia Saudí, Baréin, Kuwait, Omán o Catar, este es el **único** canal disponible: estos países no tienen ninguna red oficial de facturación electrónica compatible (sin SdI/PEPPOL/KSeF). | Si prefieres gestionar tú mismo la lógica de sincronización en tu propia instancia autoalojada de n8n (más control/personalización), también existe un paquete dedicado — consulta [sincronización con Zoho vía n8n](../integrations/n8n-zoho.md). ## Cómo elegir - **Solo vendes en Italia y todavía no usas un sistema de contabilidad externo** → SdI via POP: es el camino con menos pasos de configuración, y las notificaciones permanecen dentro de POP. - **Ya usas Fatture in Cloud o Aruba para la contabilidad** → conecta esa integración en lugar de duplicar datos en otro sitio, pero prevé tiempo para completar el mapeo necesario (cuentas, métodos de pago). - **Muy pocos documentos al mes y quieres coste/servicios adicionales cero** → SdI via PEC, sabiendo que tendrás que comprobar manualmente los resultados en el buzón PEC. - **Tu tienda tiene sede en Italia o San Marino** → mantente en SdI (vía POP o vía PEC) incluso para clientes empresariales extranjeros: PEPPOL nunca se activa en este caso, independientemente del país del cliente. Las facturas a clientes extranjeros siguen pasando por SdI, con el código de destinatario convencional para destinatarios no italianos. - **Tu tienda tiene sede en un país de la UE distinto de Italia/San Marino cubierto por PEPPOL** (lista completa en [api/peppol](../../api/peppol.md)) y vendes B2B → usa PEPPOL: es el canal equivalente a SdI para la facturación electrónica en esos países. - **Vendes en Polonia** → necesitas KSeF, independientemente del canal elegido para Italia. - **Tu cuenta está registrada en los Emiratos Árabes Unidos, Arabia Saudí, Baréin, Kuwait, Omán o Catar** → Zoho nativo es la única opción: no hay otro canal disponible para estos países. ## Bueno saberlo - No se admite activar SdI via POP y PEPPOL al mismo tiempo: si ambos acaban activos, prevalece el activado más recientemente y el otro se desactiva automáticamente. - Puedes cambiar de canal más adelante, pero hay que rehacer la configuración del nuevo canal (credenciales, mapeos) — no existe migración automática de datos entre una integración y otra. ## Configuración relacionada Para los detalles de activación de cada canal, consulta las guías dedicadas en esta misma sección («Integraciones»). --- ## Source: https://docs.popapi.io/es/guides/getting-started/shopify-faq ## Objetivo Orientarte rápidamente sobre lo que POP para Shopify hace (y no hace) antes de entrar en las guías de configuración individuales. ## Antes de empezar **¿POP calcula los impuestos en el checkout?** No. Shopify sigue siendo el único responsable de calcular y aplicar los impuestos. POP usa los datos fiscales presentes en Shopify para generar y enviar los documentos (PDF/XML, SdI/PEPPOL/KSeF). **¿Dónde configuro el IVA, el OSS, los mercados y las reglas fiscales?** Siempre en Shopify Admin (Markets, Tax regions). Para B2B, revisa los datos fiscales en Company/Company Location cuando corresponda. ## Datos fiscales del cliente **¿De dónde obtiene POP los datos fiscales del cliente?** De los metacampos (metafields) de pedido/cliente `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), con respaldo en los customAttributes del pedido. Detalles y prioridad en [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **¿Se crean los metacampos automáticamente?** Sí, una vez completados el asistente y la licencia de POP, el sistema intenta crear las definiciones que falten de forma idempotente. Si falta algo, la página de inicio muestra una sección de recuperación con un botón «Crear metacampos que faltan». ## Shopify Plus frente a no-Plus **¿Cuál es la diferencia en la recopilación de datos fiscales en el checkout?** En Shopify Plus está disponible la extensión nativa POP Checkout UI Extension. En tiendas no-Plus, los campos se añaden al carrito/cajón del carrito mediante un script pegado en el tema — consulta [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **¿POP admite escenarios tanto B2B como B2C?** Sí, ambos; la corrección fiscal del documento sigue dependiendo de la calidad de los datos recopilados en Shopify. ## Italia, SdI y PEPPOL **¿Se pueden quitar del checkout los campos nativos de Shopify Tax Code/PEC?** No, Shopify los aplica de forma nativa para Italia y POP no puede eliminarlos ni modificarlos. Siguen siendo opcionales; desactivarlos requiere una solicitud al soporte de Shopify. **¿Puedo enviar al SdI con una tienda cuya moneda no sea EUR?** No. Los flujos del SdI requieren que la moneda principal de la tienda Shopify sea EUR. **¿PEPPOL está disponible para clientes particulares?** No. El envío automático a PEPPOL siempre omite a los clientes particulares (B2C); la descarga del PDF como documento de cortesía sigue disponible. Detalles en [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **¿POP valida el número de IVA?** Sí, a través del servicio oficial VIES. La decisión fiscal final sobre la aplicación del IVA sigue dependiendo de la configuración de Shopify. ## Planes y límites **¿Cuántos documentos puedo generar al mes?** Depende del plan activo: Free 20/mes, Basic 40/mes, Growth 100/mes, Pro 400/mes, Enterprise 2000/mes. Al superar el límite, la generación muestra un aviso con un enlace para actualizar el plan. ## Resolución rápida de problemas **No veo todos los campos fiscales en el pedido/cliente:** 1. Comprueba que el asistente y la licencia de POP estén completados. 2. Comprueba que se hayan creado los metacampos `pop_*` (si no, usa el botón de recreación en la página de inicio). 3. Comprueba la configuración del checkout/tema. 4. Comprueba Markets/Tax en Shopify Admin. **Los impuestos de la factura no coinciden con lo esperado:** 1. Comprueba las reglas fiscales de Shopify. 2. Comprueba el tipo de cliente y los datos fiscales guardados. 3. Comprueba si ha fallado la validación del IVA. 4. Comprueba el canal de transmisión (SdI/PEPPOL/KSeF) y sus restricciones específicas. ## Configuración relacionada Para profundizar, empieza por [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) y [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/es/guides/integrations/webhook ## Objetivo Enviar automáticamente cada documento generado por POP (XML o PDF) a una herramienta externa: Zapier, Make (Integromat), un CRM, Google Drive o un endpoint personalizado. ## Requisitos previos - POP **plan Basic o superior** — el envío por webhook no está disponible en el plan gratuito. - Un endpoint HTTP a la escucha (la URL del webhook de destino). ## Pasos 1. En `popapi.io`, ve a **Mi cuenta > Integraciones > POP to Webhook > Conectar**. 2. Configura: - un nombre identificativo - la URL del webhook de destino - el formato de datos: **JSON** o **XML** - el interruptor de activación 3. En **WordPress**: en el plugin de POP ve a **Avanzado > Webhook**, introduce el ID del webhook creado en el paso anterior, actívalo y —si quieres un envío en segundo plano en lugar de síncrono— activa también el envío automático mediante CRON. 4. En **Shopify**: introduce el ID del webhook en la configuración de la app; aparecerá un icono en la lista de facturas para enviar los datos. ## Formatos - **JSON** — pensado para plataformas no-code (Zapier, Make): los datos se aplanan automáticamente en una estructura fácil de mapear. - **XML** — adecuado para archivo o sistemas que requieren el estándar FatturaPA; también puede enviarse como adjunto. Puedes configurar varios webhooks con diferentes URL y formatos al mismo tiempo. ## Errores comunes - **URL de webhook no válida** — verifica que la URL sea accesible públicamente y responda con éxito (no basta con que sea sintácticamente correcta). - **Formato de datos no compatible** — usa únicamente `JSON` o `XML`; otros formatos se rechazan. - **El webhook no recibe nada en sandbox** — limitación esperada: el envío por webhook no está disponible en el entorno sandbox (consulta [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Configuración relacionada Para el caso específico del reenvío a n8n con un conector dedicado (p. ej. Zoho), consulta [api/connectors](../../api/connectors.md) y [n8n](n8n.md). --- ## Source: https://docs.popapi.io/fr/guides/getting-started/choosing-an-invoicing-integration ## Objectif Comprendre quel canal de transmission activer pour votre boutique, parmi ceux disponibles dans POP. **Les canaux sont mutuellement exclusifs** : vous ne pouvez en avoir qu'un seul actif à la fois (l'activation de l'un désactive automatiquement les autres). ## Canaux disponibles | Canal | Pour qui | Dépendances externes | Notes | | --- | --- | --- | --- | | **SdI via POP** | Ceux qui veulent le flux le plus simple pour l'Italie : aucun service externe à configurer | Aucune | Transmission directe au SdI, notifications gérées dans POP, vérification automatique du code fiscal/numéro de TVA du destinataire. | | **SdI via PEC** | Faibles volumes, ceux qui ont déjà une boîte PEC (courrier certifié) et ne veulent pas de comptes externes supplémentaires | Boîte PEC | Le XML est envoyé par e-mail PEC ; les notifications de résultat doivent être vérifiées manuellement dans la boîte PEC — elles ne sont pas gérées automatiquement par POP. | | **Fatture in Cloud** | Ceux qui utilisent déjà Fatture in Cloud pour la comptabilité/facturation | Abonnement Fatture in Cloud actif | Passe par l'API officielle de Fatture in Cloud ; nécessite de mapper les [méthodes de paiement](../integrations/fatture-in-cloud-payment-methods.md) et un compte de solde avant le premier envoi. | | **Aruba Business** | Ceux qui utilisent déjà Aruba comme fournisseur de facturation électronique | Activation API sur Aruba | Moins de flexibilité de configuration que les autres options. | | **PEPPOL** | Ventes B2B à l'étranger (réseau PEPPOL) | Aucune | Ce n'est pas une alternative au SdI pour l'Italie : c'est le corridor pour la facturation électronique intra-UE. Couvre 28 pays (liste complète dans [api/peppol](../../api/peppol.md)) — **l'Espagne est exclue** (corridor Facturae, non encore pris en charge), tout comme l'Irlande du Nord et le Liechtenstein. | | **KSeF** | Ventes vers la Pologne | NIP polonais (numéro fiscal) | Voir [activation KSeF](../integrations/ksef.md) — nécessite un enregistrement dédié distinct du SdI/PEPPOL. | | **Zoho (natif)** | Ceux qui utilisent Zoho Invoice/Zoho Books et veulent une synchronisation gérée directement par POP | Autorisation OAuth vers Zoho | Voir [activation Zoho](../integrations/zoho.md). Ne nécessite pas votre propre instance n8n. Pour les comptes enregistrés aux Émirats arabes unis, en Arabie saoudite, à Bahreïn, au Koweït, à Oman ou au Qatar, c'est le **seul** canal disponible : ces pays n'ont pas de réseau officiel de facturation électronique pris en charge (pas de SdI/PEPPOL/KSeF). | Si vous préférez gérer vous-même la logique de synchronisation sur votre propre instance n8n auto-hébergée (plus de contrôle/personnalisation), un package dédié existe aussi — voir [synchronisation vers Zoho via n8n](../integrations/n8n-zoho.md). ## Comment choisir - **Vous vendez uniquement en Italie et n'utilisez pas déjà un système de comptabilité externe** → SdI via POP : c'est le chemin avec le moins d'étapes de configuration, et les notifications restent dans POP. - **Vous utilisez déjà Fatture in Cloud ou Aruba pour la comptabilité** → connectez cette intégration plutôt que de dupliquer les données ailleurs, mais prévoyez du temps pour compléter le mapping requis (comptes, méthodes de paiement). - **Très peu de documents par mois et vous voulez zéro coût/service supplémentaire** → SdI via PEC, en sachant que vous devrez vérifier manuellement les résultats dans la boîte PEC. - **Votre boutique est basée en Italie ou à Saint-Marin** → restez sur SdI (via POP ou via PEC) même pour les clients professionnels étrangers : PEPPOL ne s'active jamais dans ce cas, quel que soit le pays du client. Les factures vers l'étranger passent toujours par SdI, avec le code destinataire conventionnel pour les destinataires non italiens. - **Votre boutique est basée dans un pays de l'UE autre que l'Italie/Saint-Marin couvert par PEPPOL** (liste complète dans [api/peppol](../../api/peppol.md)) et vous vendez en B2B → utilisez PEPPOL : c'est le canal équivalent au SdI pour la facturation électronique dans ces pays. - **Vous vendez en Pologne** → vous avez besoin de KSeF, quel que soit le canal choisi pour l'Italie. - **Votre compte est enregistré aux Émirats arabes unis, en Arabie saoudite, à Bahreïn, au Koweït, à Oman ou au Qatar** → Zoho natif est la seule option : aucun autre canal n'est disponible pour ces pays. ## Bon à savoir - L'activation simultanée de SdI via POP et de PEPPOL n'est pas prise en charge : si les deux se retrouvent actifs, le dernier activé prévaut et l'autre est automatiquement désactivé. - Vous pouvez changer de canal plus tard, mais la configuration du nouveau canal (identifiants, mappings) doit être refaite — il n'y a pas de migration automatique des données entre une intégration et une autre. ## Configuration associée Pour le détail d'activation de chaque canal, voir les guides dédiés dans cette même section (« Intégrations »). --- ## Source: https://docs.popapi.io/fr/guides/getting-started/shopify-faq ## Objectif Se familiariser rapidement avec ce que POP pour Shopify fait (et ne fait pas) avant de se plonger dans les guides de configuration individuels. ## Avant de commencer **POP calcule-t-il les taxes au checkout ?** Non. Shopify reste seul responsable du calcul et de l'application des taxes. POP utilise les données fiscales présentes dans Shopify pour générer et envoyer les documents (PDF/XML, SdI/PEPPOL/KSeF). **Où configurer la TVA, l'OSS, les marchés et les règles fiscales ?** Toujours dans Shopify Admin (Markets, Tax regions). Pour le B2B, vérifiez les données fiscales sur Company/Company Location le cas échéant. ## Données fiscales du client **D'où POP tire-t-il les données fiscales du client ?** Des métachamps (metafields) de commande/client `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), avec un repli sur les customAttributes de la commande. Détails et priorité dans [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **Les métachamps sont-ils créés automatiquement ?** Oui, une fois l'assistant et la licence POP terminés, le système tente de créer les définitions manquantes de manière idempotente. Si quelque chose manque, la page d'accueil affiche une section de récupération avec un bouton « Créer les métachamps manquants ». ## Shopify Plus vs non-Plus **Quelle est la différence dans la collecte des données fiscales au checkout ?** Sur Shopify Plus, l'extension native POP Checkout UI Extension est disponible. Sur les boutiques non-Plus, les champs sont ajoutés au panier/tiroir de panier via un script collé dans le thème — voir [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **POP prend-il en charge les scénarios B2B et B2C ?** Oui, les deux ; la conformité fiscale du document dépend toujours de la qualité des données collectées dans Shopify. ## Italie, SdI et PEPPOL **Les champs natifs Shopify Tax Code/PEC peuvent-ils être retirés du checkout ?** Non, Shopify les applique nativement pour l'Italie et ils ne peuvent être ni retirés ni modifiés par POP. Ils restent optionnels ; les désactiver nécessite une demande au support Shopify. **Puis-je envoyer au SdI avec une boutique dont la devise n'est pas EUR ?** Non. Les flux SdI exigent que la devise principale de la boutique Shopify soit EUR. **PEPPOL est-il disponible pour les clients particuliers ?** Non. L'envoi automatique vers PEPPOL exclut toujours les clients particuliers (B2C) ; le téléchargement du PDF en tant que document de courtoisie reste disponible. Détails dans [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **POP valide-t-il le numéro de TVA ?** Oui, via le service officiel VIES. La décision fiscale finale sur l'application de la TVA reste de la responsabilité de la configuration Shopify. ## Plans et limites **Combien de documents puis-je générer par mois ?** Cela dépend du plan actif : Free 20/mois, Basic 40/mois, Growth 100/mois, Pro 400/mois, Enterprise 2000/mois. Une fois la limite dépassée, la génération affiche un avertissement avec un lien pour passer à un plan supérieur. ## Dépannage rapide **Je ne vois pas tous les champs fiscaux sur la commande/le client :** 1. Vérifiez que l'assistant et la licence POP sont terminés. 2. Vérifiez que les métachamps `pop_*` ont été créés (sinon utilisez le bouton de recréation sur la page d'accueil). 3. Vérifiez la configuration du checkout/thème. 4. Vérifiez Markets/Tax dans Shopify Admin. **Les taxes sur la facture ne correspondent pas aux attentes :** 1. Vérifiez les règles fiscales Shopify. 2. Vérifiez le type de client et les données fiscales enregistrées. 3. Vérifiez l'absence d'échec de validation de la TVA. 4. Vérifiez le canal de transmission (SdI/PEPPOL/KSeF) et ses contraintes spécifiques. ## Configuration associée Pour aller plus loin, commencez par [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) et [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/fr/guides/integrations/france-peppol ## Objectif Comprendre ce dont vous avez besoin pour facturer électroniquement en France avec POP et ce à quoi vous attendre lors de l'activation. ## Ce qu'il vous faut - Aucun plan minimum : l'activation et l'envoi sont disponibles sur tous les plans, y compris Free, à la consommation de crédits. - Le pays du compte défini sur France. - Un numéro de TVA français valide, ou (si vous n'en avez pas) votre numéro **SIREN** (9 chiffres) ou **SIRET** (14 chiffres). ## Comment ça marche POP envoie vos factures vers le corridor officiel français (**gov-fr**), géré via notre partenaire de conformité : ce n'est pas le même réseau PEPPOL générique utilisé pour les autres pays européens, mais cela ne change rien à la façon dont vous générez vos factures. Vous n'avez pas besoin de chercher ou de saisir manuellement votre SIREN dans la plupart des cas : POP le déduit automatiquement de votre numéro de TVA français (les 9 derniers chiffres). POP vérifie également que le numéro de TVA saisi correspond bien au SIREN qu'il contient, afin que les erreurs de saisie soient signalées immédiatement plutôt que de poser problème plus tard. Après l'activation, vous devrez compléter une vérification d'identité (KYC) sur une page gérée directement par notre partenaire de conformité, et non par le panneau POP : une étape différente de celle utilisée pour le KSeF (Pologne), où la signature se fait entièrement dans le panneau de compte. ## Étapes 1. Dans l'assistant de configuration guidée (ou dans le panneau de compte, pour un compte existant avec le pays France), confirmez votre numéro **SIREN** : dans la plupart des cas, il est déjà pré-rempli, déduit automatiquement de votre numéro de TVA. 2. Enregistrez : POP enregistre automatiquement votre entité légale française. 3. Complétez la vérification d'identité (KYC) sur la page externe de notre partenaire de conformité. ## État actuel Le corridor France est **en version bêta** : il couvre la génération et l'envoi des factures (e-invoicing). La seconde obligation française, l'**e-reporting** (pour les opérations hors du périmètre B2B interne), n'est pas encore couverte. ## Erreurs courantes - **« France Legal Entity is missing. »** : l'activation n'est pas encore terminée, vérifiez que le compte dispose d'un numéro de TVA français valide ou d'un SIREN enregistré. - **« France integration is not active. »** : l'enregistrement existe mais l'intégration n'est pas encore active sur le compte. - **Le numéro de TVA est rejeté** : les chiffres de contrôle ne correspondent pas au SIREN qu'il contient, vérifiez que vous avez saisi le bon numéro. ## Configuration associée Pour les détails techniques du contrat API, voir [api/peppol](../../api/peppol.md). Pour choisir entre les canaux de facturation disponibles, voir [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/fr/guides/integrations/peppol ## Objectif Activer l'envoi de factures électroniques via le réseau PEPPOL directement depuis votre boutique WordPress ou Shopify. ## Prérequis - Sur WordPress : aucun plan minimum, l'activation et l'envoi sont disponibles sur tous les plans (y compris Free), à la consommation de crédits. Sur Shopify, le **plan Basic ou supérieur** reste requis. - Une adresse complète (rue, ville, code postal) pour l'entité légale — PEPPOL exige ces champs pour enregistrer le point d'accès (endpoint). - Pour l'Allemagne : vous devez choisir explicitement le « corridor de document » (`zugferd` ou `peppol`) — sans ce choix, l'activation ne pourra pas se terminer. ## Étapes Vous pouvez activer PEPPOL de trois façons équivalentes : 1. **Panneau de compte** — sur `popapi.io`, allez dans **Mon compte > Intégrations**, ouvrez l'onglet PEPPOL et activez **« Activer PEPPOL »**. 2. **Depuis le plugin/l'app, avec un compte existant** — sur WordPress : onglet **Général**, actualisez les informations de licence, puis allez dans **Intégrations** et cliquez sur la carte PEPPOL pour l'activer. 3. **Assistant de configuration guidée au premier accès** — si vous configurez le compte pour la première fois et que votre pays utilise le corridor PEPPOL, l'activation se fait automatiquement à la fin de l'assistant. ## Envoi automatique - **WordPress** — onglet **Avancé > Envoi automatique des factures** : activez l'envoi via WP-Cron en arrière-plan. - **Shopify** — l'envoi automatique sur les commandes payées est disponible sur les plans payants ; il est désactivé par défaut pour les clients particuliers (PEPPOL est un corridor B2B). ## Envoi manuel Utilisez le bouton **« Envoyer la facture »** dans le tableau des factures pour envoyer un seul document au réseau PEPPOL. ## Erreurs courantes - **« This field is required when PEPPOL is enabled. »** — l'adresse, la ville ou le code postal de l'entité légale sont manquants : complétez-les dans le panneau de compte avant de réessayer. - **Activation bloquée pour l'Allemagne** — pour les comptes `DE`, vous devez choisir le corridor de document (`zugferd` ou `peppol`) avant que l'activation puisse réussir. - **L'envoi automatique ne démarre pas pour un client particulier** — comportement attendu : PEPPOL est conçu pour les destinataires professionnels, l'envoi automatique aux clients particuliers est désactivé par conception. ## Configuration associée Pour le détail du contrat API (payload, mapping des champs UBL), voir [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/fr/guides/integrations/webhook ## Objectif Envoyer automatiquement chaque document généré par POP (XML ou PDF) vers un outil externe : Zapier, Make (Integromat), un CRM, Google Drive, ou un endpoint personnalisé. ## Prérequis - POP **plan Basic ou supérieur** — l'envoi par webhook n'est pas disponible sur le plan gratuit. - Un endpoint HTTP à l'écoute (l'URL webhook de destination). ## Étapes 1. Sur `popapi.io`, allez dans **Mon compte > Intégrations > POP to Webhook > Connecter**. 2. Configurez : - un nom identifiant - l'URL webhook de destination - le format des données : **JSON** ou **XML** - l'interrupteur d'activation 3. Sur **WordPress** : dans le plugin POP, allez dans **Avancé > Webhook**, saisissez l'ID du webhook créé à l'étape précédente, activez-le, et — si vous voulez un envoi en arrière-plan plutôt que synchrone — activez aussi l'envoi automatique via CRON. 4. Sur **Shopify** : saisissez l'ID du webhook dans les paramètres de l'app ; une icône apparaîtra dans la liste des factures pour envoyer les données. ## Formats - **JSON** — conçu pour les plateformes no-code (Zapier, Make) : les données sont automatiquement aplaties dans une structure facile à mapper. - **XML** — adapté à l'archivage ou aux systèmes exigeant le standard FatturaPA ; peut aussi être envoyé en pièce jointe. Vous pouvez configurer plusieurs webhooks avec des URL et formats différents en même temps. ## Erreurs courantes - **URL de webhook invalide** — vérifiez que l'URL est accessible publiquement et répond avec succès (il ne suffit pas qu'elle soit syntaxiquement correcte). - **Format de données non pris en charge** — utilisez uniquement `JSON` ou `XML` ; les autres formats sont rejetés. - **Le webhook ne reçoit rien en sandbox** — limitation attendue : l'envoi par webhook n'est pas disponible dans l'environnement sandbox (voir [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Configuration associée Pour le cas particulier du transfert vers n8n avec un connecteur dédié (ex. Zoho), voir [api/connectors](../../api/connectors.md) et [n8n](n8n.md). --- ## Source: https://docs.popapi.io/it/api/connectors L'API connector inoltra un payload POP a un servizio esterno tramite un webhook n8n registrato. Attualmente supporta lo slug `zoho` (Zoho Invoice / Zoho Books). Per il lato `zoho`, non serve costruire la logica da zero: esiste un pacchetto ufficiale, [`n8n-nodes-pop-zoho`](https://www.npmjs.com/package/@getpopapi/n8n-nodes-pop-zoho), che gira su una tua istanza n8n self-hosted, verifica la firma della richiesta e crea la fattura/nota di credito su Zoho — vedi [guides/integrations/n8n-zoho](../guides/integrations/n8n-zoho.md) per l'installazione. Se invece preferisci la sincronizzazione gestita direttamente da POP senza dover gestire un'istanza n8n tua, vedi [api/zoho](zoho.md). ## Endpoint - `GET /wp-json/api/v2/connector/pubkey` — chiave pubblica RSA per configurare il nodo n8n (nessuna auth) - `POST /wp-json/api/v2/connector/{slug}` — inoltra il payload (auth standard `X-API-Key`) ## Cosa serve - `integration.use` deve essere `n8n-zoho` per il connector Zoho - `integration.id` — ID del webhook, dallo stesso registro dei webhook standard, con `Connector type = n8n Connector — Zoho`, abilitato ## Errori lato POP | Codice | Status | Causa | | --- | --- | --- | | `connector_not_found` | 404 | slug sconosciuto nell'URL | | `missing_integration_id` | 400 | `integration.id` non fornito | | `connector_webhook_not_found` | 404 | nessun webhook registrato per quell'`integration.id` | | `connector_webhook_disabled` | 422 | webhook disabilitato nel pannello account | | `connector_unreachable` | 502 | l'URL webhook n8n non ha risposto | | `connector_invalid_response` | 502 | n8n ha risposto con contenuto non JSON | In `environment: sandbox` non vengono effettuate chiamate reali a Zoho e non si consuma quota. Per generare fatture SdI/PEPPOL o validare partite IVA da n8n (pacchetto diverso, flusso diverso da questo connector), vedi [guides/integrations/n8n](../guides/integrations/n8n.md). --- ## Source: https://docs.popapi.io/it/api/ksef Route principale: `POST /wp-json/api/v2/create-ksef-xml` — genera XML FA(3) localmente. Con `integration.use = ksef` nel payload, genera e invia in un solo passo tramite KSeF via POP. Route di supporto (account connessi): `POST /wp-json/api/v2/ksef/document-get` (stato documento), `POST /wp-json/api/v2/ksef/upo-get` (ricevuta UPO). ## Cosa serve - fornitore con paese `PL` e NIP polacco valido - `customer_type` deve essere `company` o `freelance` (non `private`) - invio tramite KSeF via POP richiede ente legale registrato e onboarding completato; su Shopify serve inoltre il piano `Basic` o superiore (su WordPress, API diretta, n8n e MCP l'invio non richiede più un piano a pagamento, usa i crediti disponibili) ## Output - generazione locale: XML grezzo - invio KSeF via POP (`integration.use = ksef`): JSON - `ksef/upo-get`: XML grezzo; `ksef/document-get`: JSON - errori: sempre JSON ## Da sapere - codici pagamento supportati: `MP01`, `MP02`, `MP03`, `MP05`, `MP08` - varianti fiscali supportate: IVA standard, esente, reverse charge, intra-UE 0% (`ZERO_WDT`), export 0% (`ZERO_EXPORT`) - per note di credito, imposta `type = credit_note` nel payload condiviso - `integration.use` accetta anche l'alias `ksef-via-pop` - `ksef/document-get` restituisce lo stato provider (`in_queue`, `processing`, `valid`, `invalid`, `rejected`, `blocked`, `approved`, `draft`) tradotto in un messaggio leggibile - errori pubblici principali: `insufficient_level` (solo Shopify, piano sotto `Basic`), `pop_api_ksef_legal_entity_missing` (legal entity non registrata), `pop_api_ksef_onboarding_required` (onboarding incompleto), `pop_api_ksef_generation_failed` (XML FA(3) non generabile) - `connector_exclusive_channel_active` (403) — l'invio KSeF è bloccato mentre Zoho è il canale di fatturazione attivo e connesso sull'account; la generazione locale dell'XML non è comunque interessata --- ## Source: https://docs.popapi.io/it/api/onboarding Base path: `onboarding/v1`. Flusso headless, indipendente dal login via browser/tema, pensato per MCP, LLM e integrazioni esterne. ## Flusso ``` POST /request-otp → POST /verify-otp → GET /status → GET /account-setup → POST /account-setup ``` Dopo `verify-otp`, tutte le chiamate richiedono `onboarding_token` (header `X-Onboarding-Token` o query `onboarding_token`), valido 1800 secondi — non è una credenziale permanente. ## Passi 1. `POST /request-otp` — valida l'email, crea l'account se non esiste, genera OTP. 2. `POST /verify-otp` — verifica OTP (o password admin), restituisce `onboarding_token` e `next_action` (se `completed`, l'account è già configurato). 3. `GET /status` — stato corrente del wizard. 4. `GET /account-setup` — payload completo: valori salvati, lookup, capability. 5. `POST /account-setup` — salva la configurazione, attiva SdI/PEPPOL/KSeF/ZUGFeRD in base al paese. ## Da sapere - il flusso copre varianti per IT/SM (SdI), altri paesi UE (PEPPOL) e Germania (corridoio ZUGFeRD/PEPPOL) - `configurations` restituito da `GET /account-setup` contiene solo valori salvati e coerenti - questo stesso flusso è esposto anche come 5 strumenti MCP (`pop_onboarding_*`) sul [server MCP remoto](../guides/integrations/mcp-remote.md), pensati per farsi guidare da un assistente AI invece di chiamare le route direttamente — vedi [onboard-via-ai-assistant](../guides/getting-started/onboard-via-ai-assistant.md) - per i paesi GCC senza una rete di fatturazione elettronica ufficiale (AE, SA, BH, KW, OM, QA), l'unico canale di fatturazione disponibile è il connector nativo Zoho (`configurations.connector`) — nessun canale fiscale ufficiale SdI/PEPPOL/KSeF è previsto per questi account - `general_store_vat_number` valida il formato per IT, SM e altri 33 paesi; il messaggio di errore 422 include un esempio di formato specifico per paese quando il valore non corrisponde - attivare un'integrazione non coerente con il paese dell'account restituisce un 422 esplicito (es. `active_sdipop_integration: 1` su un account non IT/SM, `active_peppol_integration: 1` su un paese non PEPPOL, `active_ksef_integration: 1` su un paese diverso da PL) --- ## Source: https://docs.popapi.io/it/api/overview POP Cloud API genera documenti fiscali (SdI, PEPPOL, KSeF, PDF, ZUGFeRD) da un unico payload condiviso e, quando serve, li consegna tramite integrazioni attive (webhook, SdI, PEPPOL, KSeF, Fatture in Cloud). ## Base URL - Produzione: `https://popapi.io/wp-json/api/v2/` - Sandbox (per test, nessun credito consumato): `https://sandbox.popapi.io/wp-json/api/v2/` ## Autenticazione Header `X-API-Key: ` (preferito). Il `license_key` si ottiene da `Account > API` dopo l'attivazione. In alternativa esiste `license_key` in body/query, ma è deprecato. ## Primi passi 1. Ottieni il `license_key`. 2. Verifica con `GET /account-profile`. 3. Invia una richiesta di generazione documento con un payload `data` reale. 4. Aggiungi eventuali integrazioni di delivery solo dopo che la generazione locale funziona. ## Endpoint principali | Dominio | Guida | Route | | --- | --- | --- | | SdI / FatturaPA | [api/sdi](sdi.md) | `POST /create-xml` | | PEPPOL BIS / UBL | [api/peppol](peppol.md) | `POST /create-ubl` | | KSeF FA(3) | [api/ksef](ksef.md) | `POST /create-ksef-xml` | | PDF | [api/pdf](pdf.md) | `POST /create-pdf` | | ZUGFeRD / Factur-X | [api/zugferd](zugferd.md) | `POST /create-zugferd` | | Onboarding | [api/onboarding](onboarding.md) | `onboarding/v1/*` | | Connector (n8n) | [api/connectors](connectors.md) | `POST /connector/{slug}` | ## Fonte completa Reference completo: [Postman collection](https://www.postman.com/getpopapi/pop-api-public-docs/). --- ## Source: https://docs.popapi.io/it/api/pdf `POST /wp-json/api/v2/create-pdf` genera il PDF del payload condiviso POP. ## Cosa serve - payload `data` valido; `data.pdf` estende il payload solo per il rendering (billing, shipping, logo, header, footer) — non sostituisce i dati fiscali comuni - se presente in entrambi, `tax_regime` deve corrispondere a quello dell'account - invio email richiede `data.pdf.email_invoice` con almeno un destinatario in `to` (max 3) ## Output - default: PDF in streaming - con `data.pdf.email_invoice`: JSON (non lo stream del file) ## Consegna email - `to` — destinatari principali, visibili tra loro - `bcc` — copia silenziosa (max 3), non visibile a `to`; se usato, la risposta include `bcc_to` accanto a `sent_to` - per inviare una copia interna senza esporla al cliente, usa `bcc`, non aggiungere l'indirizzo a `to` --- ## Source: https://docs.popapi.io/it/api/peppol `POST /wp-json/api/v2/create-ubl` genera XML UBL PEPPOL BIS dal payload condiviso POP. ## Cosa serve - payload `data` valido, licenza autenticata abilitata - PEPPOL è un corridoio B2B: il destinatario deve essere un soggetto business ## Output - successo: XML UBL grezzo - errore (validazione, quota, webhook, integrazione): JSON strutturato ## Consegna XML generato può essere inviato a integrazioni PEPPOL attive o a webhook configurati. ## Da sapere - l'instradamento del destinatario non usa `sdi_type`; deriva da identificativi VAT/registrazione e, quando possibile, da lookup nella directory PEPPOL - `purchase_order_data.id` diventa `OrderReference` (spesso necessario per soddisfare `PEPPOL-EN16931-R003` in invio a validazione provider) - `connected_invoice_data.id`/`date` diventano `BillingReference` per le note di credito - `connector_exclusive_channel_active` (403): l'invio PEPPOL è bloccato mentre Zoho è il canale di fatturazione attivo e connesso sull'account; la generazione locale UBL non è comunque interessata - `country_not_eligible_for_peppol`: il paese registrato sull'account non è un paese PEPPOL supportato - generazione e invio via WordPress, API diretta, n8n o MCP non richiedono più un piano a pagamento: ogni piano, incluso Free, può inviare usando i propri crediti disponibili. Su Shopify l'invio richiede ancora il piano Basic o superiore - paesi PEPPOL attualmente supportati (28): AT, BE, BG, CY, CZ, DE, DK, EE, FI, FR, GR, HR, HU, IE, IS, LT, LU, LV, MT, NL, NO, PT, RO, SE, SI, SK, CH, GB. **Esclusi deliberatamente**: Spagna (corridoio Facturae, non ancora supportato), Irlanda del Nord (non abilitata nel catalogo paesi), Liechtenstein (nessuno schema di identificativo endpoint PEPPOL configurato) - **Francia (gov-fr, beta)**: quando il paese del trasmittente è `FR`, la richiesta viene instradata automaticamente al corridoio gov-fr invece del PEPPOL generico: stesso contratto pubblico (`integration.use = peppol`), nessun valore diverso da passare. Il corridoio ha una propria Legal Entity e propri messaggi di errore (`"France Legal Entity is missing."`, `"France integration is not active."` al posto degli equivalenti PEPPOL). Il SIREN richiesto per la Legal Entity viene derivato automaticamente dalla partita IVA francese sull'account (ultime 9 cifre); un campo opzionale `fr_siren` nel payload di account-setup permette di forzarne uno diverso. Copre solo e-invoicing: l'e-reporting francese non è ancora implementato. Vedi [france-peppol](../guides/integrations/france-peppol.md) per la guida di attivazione. --- ## Source: https://docs.popapi.io/it/api/sdi `POST /wp-json/api/v2/create-xml` genera XML FatturaPA / SdI dal payload condiviso POP. ## Cosa serve - payload `data` valido, licenza autenticata abilitata - se presente in entrambi, `tax_regime` del payload deve corrispondere a quello dell'account - instradamento destinatario tramite `transmitter_data.sdi_code` oppure `transmitter_data.recipient_pec` ## Output - successo: XML grezzo - errore (validazione, quota, webhook, integrazione): JSON strutturato ## Consegna XML generato può essere inviato a integrazioni SdI attive o a webhook configurati. ## Da sapere - `purchase_order_data.id` aggiunge `DatiOrdineAcquisto` - le note di credito richiedono `connected_invoice_data.id` e `date` - in sandbox, `invoice_number` viene prefissato con `SANDBOX-` - `connector_exclusive_channel_active` (403) — l'invio SdI è bloccato mentre Zoho è il canale di fatturazione attivo e connesso sull'account; la generazione locale dell'XML non è comunque interessata - `country_not_eligible_for_sdi` — il paese registrato sull'account non è IT o SM - generazione e invio via WordPress, API diretta, n8n o MCP non richiedono più un piano a pagamento: ogni piano, incluso Free, può inviare usando i propri crediti disponibili. Su Shopify l'invio richiede ancora il piano Basic o superiore --- ## Source: https://docs.popapi.io/it/api/zoho L'integrazione nativa Zoho è uno dei canali di invio POP (come SdI via POP, PEPPOL, KSeF): sincronizza direttamente un documento verso Zoho Invoice o Zoho Books via OAuth, **senza** passare da un webhook n8n gestito dall'utente. È un canale distinto dal [connector generico](connectors.md), che invece inoltra il payload a un webhook n8n che tu stesso configuri e gestisci — usa questa pagina se ti serve la sincronizzazione diretta, l'altra se vuoi instradare tramite un tuo workflow n8n. ## Endpoint - `GET /wp-json/api/v2/integration/zoho/status` — stato della connessione (regione, prodotto, org ID, scadenza token, stato fattura di default, auto-creazione contatti). - `POST /wp-json/api/v2/integration/zoho/sync` — sincronizza un documento verso Zoho. - `GET /wp-json/api/v2/integration/oauth/callback` — callback OAuth usato durante l'autorizzazione (gestito automaticamente dal flusso di connessione, non da chiamare manualmente). ## Cosa serve - Attivazione del canale Zoho dal pannello account POP (è uno dei canali di invio mutuamente esclusivi: attivarlo disattiva automaticamente gli altri). - Autorizzazione OAuth completata — lo stato "connected" in `integration/zoho/status` deve risultare `true` prima di poter sincronizzare. - Nessun piano a pagamento richiesto su WordPress, API diretta, n8n o MCP: la sincronizzazione usa i crediti disponibili. Su Shopify serve ancora il piano Basic o superiore. ## Da sapere - Ogni documento sincronizzato in ambiente live consuma **1 credito**. - `zoho_product` indica se l'account è collegato a Zoho Invoice o Zoho Books. - `zoho_create_contact_if_missing` controlla se un contatto Zoho mancante viene creato automaticamente durante la sincronizzazione, invece di fallire. - `payment_terms` viene derivato automaticamente da `payment_data.payment_due_days`. - I metadati fiscali/di pagamento senza un campo Zoho dedicato (`nature`, `ref_normative` e i valori chiave di `payment_data`) vengono copiati automaticamente nelle `notes` della fattura Zoho. - Per mappare quegli stessi valori su campi personalizzati Zoho, passa `integration.custom_fields_map` (oggetto con `label` o `customfield_id` per campo) — l'integrazione nativa crea solo documenti, non aggiorna contatti Zoho esistenti. - **Note di credito** — richiedono che l'ordine collegato abbia già una fattura sincronizzata con successo su Zoho; senza quel riferimento la richiesta fallisce con errore 422 ("Zoho credit notes require a Zoho parent invoice reference on the original order."). - **Sandbox** — una richiesta con `environment: sandbox` non crea nulla su Zoho: restituisce una risposta di successo con conferma di dry-run, senza toccare l'account Zoho reale. ## Errori comuni | Codice | Causa | | --- | --- | | `no_connector_configured` | Nessun connector nativo attivo sull'account | | `unsupported_doc_type` | `doc_type` diverso da `TD01`/`TD04` | | `missing_connected_invoice` | Nota di credito senza `connected_invoice_data.id` | | `tax_not_found` | Un'aliquota di `order_items[].rate` non è configurata su Zoho | | `contact_not_found` | Cliente non trovato e auto-creazione disattivata | | `contact_ambiguous` | Più contatti Zoho corrispondono alla stessa P.IVA/email/nome | | `zoho_region_not_configured` / `zoho_organization_not_configured` | Regione o Organization ID mancanti nelle impostazioni account | | `zoho_api_error` | Errore generico restituito da Zoho e inoltrato da POP | ## Configurazione correlata Per l'attivazione lato pannello account e lo stato mostrato nel plugin/app, vedi [integrations/zoho](../guides/integrations/zoho.md). --- ## Source: https://docs.popapi.io/it/api/zugferd `POST /wp-json/api/v2/create-zugferd` genera un bundle ZUGFeRD/Factur-X dal payload condiviso POP. ## Output Sempre JSON, con tre allegati in base64: - `attachments.pdf` — PDF visuale - `attachments.xml` — XML EN16931 CII - `attachments.hybrid_pdf` — PDF ibrido con XML incorporato ## Da sapere - non esiste consegna in uscita (webhook/integrazioni) su questa route - supporta generazione solo-payload via RapidAPI (`X-RapidAPI-Key` senza `X-API-Key` POP); in questa modalità il payload deve contenere tutti i campi richiesti esplicitamente - in sandbox, `invoice_number` viene prefissato con `SANDBOX-` - varianti fiscali supportate: IVA standard, reverse charge, intra-UE 0%, export 0%, esente, fuori campo generale; non supportate: OSS, regime del margine, split payment ## Verifica lato consumer Usa `validation.hybrid_pdf.has_embedded_xml` e `validation.hybrid_pdf.embedded_xml_matches` nella risposta come check immediato che l'XML sia incorporato correttamente nel PDF ibrido. --- ## Source: https://docs.popapi.io/it/guides/changelog/shopify-app ## Dove guardare A differenza del plugin WordPress, l'app POP for Shopify non ha oggi un changelog pubblico per versione: il listing sullo Shopify App Store non pubblica note di rilascio. Le novità e le correzioni non sono quindi consultabili in autonomia — se hai bisogno di sapere se un comportamento specifico è già stato corretto o quando è stata introdotta una funzionalità, apri un ticket di supporto indicando la versione installata (vedi sotto). ## Come sapere quale versione hai installata La versione dell'app installata è visibile nella schermata **Settings** dell'app POP, insieme allo stato delle integrazioni attive (SdI, PEPPOL, KSeF, Zoho). ## Quando contattare il supporto - Se riscontri un comportamento che sospetti sia già stato corretto in una versione più recente. - Prima di aprire un ticket per un bug: indica la versione installata, velocizza la diagnosi. - Dopo un annuncio di nuove funzionalità (es. nuovo canale di invio o nuova valuta supportata), per capire se richiede una modifica alla tua configurazione. ## Configurazione correlata Per la configurazione delle singole funzionalità, parti da [shopify-faq](../getting-started/shopify-faq.md). --- ## Source: https://docs.popapi.io/it/guides/changelog/wordpress-plugin ## Dove guardare Il changelog completo del plugin WordPress (voci per versione, categorizzate in genere come Added, Fixed, Improved, Changed) non viene duplicato qui perché cambia ad ogni rilascio: consultalo direttamente nella pagina **Changelog** della scheda del plugin su WordPress.org, generata dalla sezione `== Changelog ==` del `readme.txt` del plugin stesso — quella è l'unica fonte sempre aggiornata. ## Come sapere quale versione hai installato In `wp-admin > Plugin`, la versione installata è indicata accanto al nome del plugin POP. La stessa versione è visibile anche nella schermata delle impostazioni del plugin. ## Quando serve aggiornare - Se riscontri un comportamento che il changelog indica come già corretto in una versione più recente di quella installata. - Prima di aprire un ticket di supporto per un bug: verifica che non sia già stato risolto in una versione successiva. Per la procedura di aggiornamento, vedi la guida di installazione/aggiornamento del plugin. --- ## Source: https://docs.popapi.io/it/guides/configuration/checkout-field-names ## Obiettivo Conoscere i nomi tecnici (`name`/meta key) dei campi che POP aggiunge al checkout WooCommerce, utili se personalizzi il tema, un plugin di checkout custom, o leggi i meta dell'ordine via codice. ## Campi aggiunti | Campo | Cosa contiene | | --- | --- | | `billing_choice_type` | Scelta documento: `receipt` (ricevuta) o `invoice` (fattura). Visibile solo se la scelta è abilitata (vedi sotto). | | `billing_invoice_type` | Tipo cliente: `private` (privato), `company` (azienda) o `freelance` (libero professionista) — chiavi fisse, anche se personalizzi le etichette. | | `billing_sdi_type` | Un unico campo per **PEC oppure codice destinatario SDI a 7 caratteri** (non sono due campi separati). | | `billing_vat_number` | Partita IVA. | | `billing_tax_code` | Codice fiscale. | Sui campi `billing_sdi_type`, `billing_vat_number` e `billing_tax_code` viene applicato un controllo di formato (RegEx) oltre all'eventuale obbligatorietà, che varia in base a paese e tipo cliente. ## Dove si configurano visibilità/etichette Tutti questi comportamenti si impostano in `POP → Electronic Invoice - Settings`, tab **Checkout**: - **Customer type list** — personalizza le etichette di `billing_invoice_type` (le chiavi `private`, `company`, `freelance` restano fisse); formato: una riga per voce, `chiave:Etichetta`. - **Activate the choice of receipt** — mostra/nasconde il campo `billing_choice_type`. - **Disable PEC/unique code field** — nasconde `billing_sdi_type` (il codice destinatario viene impostato automaticamente a `0000000`). - **Disable Fiscal Code** — nasconde `billing_tax_code` per aziende e liberi professionisti. - **VAT number and tax code for non-EU customers** — mostra/nasconde questi campi per clienti extra-UE. - **Position of the fields (e-invoice) in the checkout form** — posiziona il blocco campi in alto o in basso nel form. ## Verifica Ispeziona l'HTML del checkout (o i meta dell'ordine in `wp-admin > Ordini`) e controlla che i nomi dei campi corrispondano esattamente a quelli in tabella. ## Errori comuni - **Un plugin/tema personalizzato non trova il campo PEC** — probabilmente cerca `billing_pec`: il nome corretto è `billing_sdi_type` (usato sia per PEC che per il codice SDI). - **Cerchi `billing_cf`** — il nome effettivo è `billing_tax_code`. - **I meta salvati sull'ordine non coincidono con quanto scritto in checkout** — se usi un plugin di checkout personalizzato, la compatibilità con questi campi non è garantita: POP non può gestire logiche di terze parti che alterano il flusso ordine. ## Configurazione correlata Per aggiungere logica custom basata su questi campi (es. tramite gli hook `wc_el_inv-*`) vedi [custom-code-snippets](custom-code-snippets.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/custom-code-snippets ## Obiettivo Aggiungere una piccola personalizzazione (es. modificare un filtro POP) senza toccare `functions.php` del tema e senza creare un plugin dedicato. ## Prerequisiti - Accesso amministratore a `wp-admin`. - Uno snippet PHP valido da inserire (scritto da te o fornito dal supporto POP). ## Passi 1. Installa il plugin gratuito **Code Snippets** da `wp-admin > Plugin > Aggiungi nuovo`, poi attivalo. 2. Nel menu laterale, apri **Snippets > Aggiungi nuovo**. 3. Assegna un titolo descrittivo (es. "POP - disabilita numero fattura per pagamento X"). 4. Incolla il codice PHP nell'area dedicata. **Non** inserire il tag ` Require all denied Deny from all ``` Questo blocca l'accesso diretto via browser su server **Apache**. Il file viene generato automaticamente alla prima scrittura in ciascuna cartella: non serve crearlo a mano. ## Protezione su NGINX (richiede intervento manuale) Su server **NGINX** (es. Kinsta, WPEngine, VPS con NGINX) le direttive `.htaccess` non vengono lette: serve una regola equivalente nella configurazione del sito, ad esempio: ``` location ~ ^/wp-content/uploads/pop-(pdf|xml|ubl|ksef|zugferd|invoice)/.*$ { return 403; } ``` Dopo averla aggiunta, riavvia NGINX per applicarla. ## Verifica Prova ad aprire direttamente nel browser l'URL di un file generato (es. `https://tuosito.it/wp-content/uploads/pop-pdf/2026/07/documento.pdf`): deve restituire un errore **403 (accesso negato)**, non il file. ## Errori comuni - **Il file è scaricabile pubblicamente su NGINX** — l'`.htaccess` generato da POP non ha effetto su NGINX: serve la regola `location` manuale sopra, applicata dal tuo hosting/provider. - **Non sai se il tuo hosting usa Apache o NGINX** — chiedi al provider: la differenza cambia completamente il metodo di protezione da applicare. - **La cartella `pop-invoice` è vuota** — è normale se non hai attivato l'opzione di salvataggio locale opzionale in **Advanced**: i download dalla tab Invoices usano comunque la cache `pop-xml`/`pop-pdf`. ## Configurazione correlata Per il formato e i limiti dell'XML generato vedi [xml-invoices-generated](../getting-started/xml-invoices-generated.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/import-export-settings ## Obiettivo Replicare la configurazione di POP (opzioni salvate nelle tab General, Numeration, Documents, ecc.) su un'altra installazione WordPress, senza reinserire manualmente ogni campo. ## Prerequisiti - Accesso amministratore a entrambe le installazioni (origine e destinazione). - POP installato e attivo su entrambe. ## Passi 1. Sull'installazione di **origine**, vai su `POP → Electronic Invoice - Settings`, tab **Advanced**, sezione **Import/Export** (raggiungibile anche dal link nella barra di navigazione interna della tab). 2. Copia l'intero contenuto del campo **Export options** (di sola lettura): è la serializzazione delle opzioni correnti del plugin. 3. Sull'installazione di **destinazione**, apri la stessa tab **Advanced > Import/Export**. 4. Incolla il testo copiato nel campo **Import options**. 5. Salva la pagina (pulsante di salvataggio della tab Advanced). ## Verifica Dopo il salvataggio, ricarica la tab e controlla che i valori nelle altre tab (General, Numeration, Documents...) corrispondano a quelli dell'installazione di origine. ## Errori comuni - **Le impostazioni non cambiano dopo l'import** — assicurati di aver salvato la pagina (non basta incollare il testo): il salvataggio avviene solo al submit del form della tab Advanced. - **Alcune impostazioni "premium" (numerazione nota di credito, ecc.) restano bloccate dopo l'import** — se il piano dell'account di destinazione non le abilita, i valori importati per quei campi vengono ignorati. - **Vuoi copiare solo alcune impostazioni, non tutte** — l'import/export sostituisce l'intera collezione di opzioni testuale: non è pensato per un merge selettivo di singoli campi. - **Dati specifici dell'account** (licenza, ID account POP) — l'import/export riguarda le opzioni del plugin salvate localmente; licenza e collegamento account restano legati a ciascuna installazione e vanno comunque completati con il wizard, vedi [first-installation](../getting-started/first-installation.md). ## Configurazione correlata Per la procedura di aggiornamento vedi [update-plugin](update-plugin.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/invoice-numbering-and-order-status ## Obiettivo Capire esattamente quando POP assegna il numero fattura e quando genera l'XML, per evitare disallineamenti tra numerazione e data dei documenti. ## Quando viene assegnato il numero fattura Il numero viene assegnato al **primo passaggio dell'ordine** a stato **"In lavorazione"** oppure **"Completato"** (qualunque dei due arrivi prima). Da quel momento l'ordine ha già un numero progressivo, anche se il documento non è ancora stato inviato al cliente. ## Quando viene generato l'XML Per default l'XML viene generato quando l'ordine raggiunge lo stato **"Completato"** (comportamento personalizzabile via filtro per sviluppatori, non tramite un'opzione in UI). Per i **rimborsi**, POP genera automaticamente l'XML della nota di credito nel momento in cui il rimborso viene registrato su WooCommerce — non serve un'azione manuale per la sola generazione del documento. > Se usi un add-on di trasmissione a un gestionale esterno (es. Fatture in Cloud, Aruba), l'**invio** al > software esterno può richiedere comunque un caricamento manuale dalla tab "Fatture" a seconda della > configurazione dell'add-on: verifica il comportamento specifico nella configurazione dell'add-on > attivo, perché può differire da quanto descritto qui per il flusso nativo. ## La data della fattura dipende da quando viene inviata Questo è il punto che genera più confusione: - Se la fattura viene inviata **mentre l'ordine è ancora "in lavorazione"**, la data del documento resta quella del passaggio in lavorazione. - Se **non viene inviata** finché l'ordine è "in lavorazione" e viene inviata solo al completamento, la data si aggiorna al giorno del completamento. **Esempio di disallineamento:** 1. 04/01 — Ordine #101 passa in lavorazione → fattura n. 1 generata, non ancora inviata. 2. 07/01 — Ordine #102 passa in lavorazione → fattura n. 2 generata **e inviata** con data 07/01. 3. 04/03 — Ordine #101 viene completato e la fattura n. 1 viene inviata solo ora → la data si aggiorna al 04/03. Risultato: la fattura n. 2 ha una data (07/01) precedente alla n. 1 (04/03), pur avendo numero inferiore. ## Verifica Prima di inviare fatture in blocco, controlla dalla tab **Invoices** che numerazione e data siano coerenti (numero crescente = data crescente). ## Errori comuni - **Numerazione e data non in ordine cronologico** — evita di lasciare ordini "in lavorazione" a lungo prima di inviare la fattura; se sai che un ordine resterà in lavorazione per molto tempo, valuta di non portarlo in quello stato finché non sei pronto a gestirlo. - **L'XML del rimborso non compare** — controlla che il rimborso sia stato effettivamente registrato su WooCommerce (non solo un rimborso esterno annotato a parte). - **L'XML non arriva al gestionale esterno collegato tramite add-on** — la generazione del documento e il suo invio al software esterno sono due passaggi distinti quando è attivo un add-on: verifica se serve un caricamento manuale. ## Configurazione correlata Per la nota di credito e i suoi requisiti vedi [credit-note-generation](../troubleshooting/credit-note-generation.md); per dove/come vengono salvati i file XML vedi [generated-files-storage](generated-files-storage.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/order-completed-emails ## Obiettivo Gestire le email automatiche che POP aggiunge alle email transazionali di WooCommerce, ognuna con un documento diverso allegato. ## Cosa aggiunge il plugin POP registra **3 email aggiuntive** nell'elenco email di WooCommerce (`WooCommerce > Impostazioni > Email`), tutte innescate quando l'ordine passa a stato **"Completato"**: | Email | Allegato | | --- | --- | | Send Invoice XML on order completed | Fattura XML | | Send Invoice PDF on order completed | Fattura PDF | | Send Receipt PDF on order completed | Ricevuta PDF | Ognuna è una email WooCommerce a sé stante: puoi attivarla/disattivarla e personalizzarne oggetto/intestazione indipendentemente dalle altre, esattamente come le email standard di WooCommerce (nuovo ordine, ordine completato, ecc.). ## Prerequisiti - WooCommerce con le email transazionali funzionanti (SMTP configurato se necessario). - L'ordine deve avere un totale diverso da zero: se hai attivato l'opzione che blocca la fattura sugli ordini a importo zero, questi ordini non generano né numero né allegati. ## Passi 1. Vai su `WooCommerce > Impostazioni > Email`. 2. Individua le tre voci sopra elencate tra le email disponibili. 3. Attiva quelle che ti servono e personalizza oggetto/intestazione se necessario. 4. Salva. ## Verifica Genera un ordine di test e portalo a "Completato": dovresti ricevere (o vedere in log/coda email) le email attivate, ciascuna con il rispettivo allegato. ## Errori comuni - **Il cliente riceve il documento sbagliato o nessun allegato** — controlla che l'email specifica sia attiva in `WooCommerce > Impostazioni > Email` e che il documento (XML/PDF) sia stato effettivamente generato per quell'ordine. - **Vuoi allegare anche una fattura pro-forma all'email di ordine completato standard (non queste 3 email dedicate)** — è un'opzione distinta, vedi [pro-forma-invoice-email](pro-forma-invoice-email.md). - **Le email non partono affatto** — verifica prima che WooCommerce riesca a inviare email in generale (problema di consegna SMTP, non specifico di POP). ## Configurazione correlata Per l'invio della fattura/ricevuta pro-forma tramite l'email standard di ordine completato vedi [pro-forma-invoice-email](pro-forma-invoice-email.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/pro-forma-invoice-email ## Obiettivo Allegare automaticamente il PDF (fattura o ricevuta, in base alla scelta del cliente) all'email standard "ordine completato" di WooCommerce. ## Prerequisiti - WooCommerce con l'email "ordine completato" attiva. ## Passi 1. Vai su `POP → Electronic Invoice - Settings`, tab **Documents**, sezione **PDF Documents**. 2. Attiva l'opzione **Proforma invoice via email** ("Active the sending of the invoice/receipt in PDF format via e-mail upon completion of the order"). 3. Salva. Da questo momento il PDF viene allegato all'email di ordine completato di WooCommerce quando l'ordine raggiunge quello stato. ## Verifica Completa un ordine di test e controlla che l'email "ordine completato" arrivi con il PDF allegato. ## Errori comuni - **Il PDF non risulta più allegato dopo aver attivato "Generate proforma in HTML"** — è un comportamento atteso, non un bug: l'opzione HTML (pensata solo come fallback quando la generazione PDF ha problemi) mostra il documento in formato HTML ma **non lo allega** all'email. Se ti serve l'allegato PDF, non attivare questa opzione insieme a "Proforma invoice via email". - **L'allegato manca solo per alcuni ordini** — verifica che l'ordine abbia raggiunto effettivamente lo stato "Completato" e che non sia un ordine a importo zero (se hai attivato il blocco fatturazione per ordini a zero). - **Vuoi anche un'email dedicata separata con solo l'XML o solo il PDF fattura** — sono email WooCommerce distinte, vedi [order-completed-emails](order-completed-emails.md). ## Configurazione correlata Per le tre email dedicate con XML/PDF fattura/PDF ricevuta vedi [order-completed-emails](order-completed-emails.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/reverse-charge ## Obiettivo Applicare correttamente (o rimuovere) l'IVA in fattura in base al paese/tipo del cliente, per le vendite verso l'estero (UE ed extra-UE). ## Prerequisiti - Piano POP che include il reverse charge (funzionalità a pagamento: senza un piano abilitato i campi restano visibili ma disabilitati). - Aliquote IVA configurate in WooCommerce (`WooCommerce > Impostazioni > Imposte`) — passaggio non gestito da POP ma necessario perché tutto funzioni. ## Passi 1. Vai su `POP → Electronic Invoice - Settings`, tab **Checkout**, sezione **Reverse Charge**. 2. Attiva **"Activate reverse charge (globally)"** (oppure attivalo per singolo prodotto, se preferisci non applicarlo globalmente). 3. Attiva **"Activate VIES validation"**: è un passaggio **necessario**, non opzionale — il reverse charge non si attiva senza la validazione VIES della partita IVA del cliente. Se il tuo hosting non riesce a validare la partita IVA, verifica che l'estensione PHP `SoapClient` sia attiva sul server (chiedilo al tuo hosting). 4. In **"Tax classes"**, seleziona la classe di imposta a aliquota zero da usare per il reverse charge: POP individua automaticamente tra le classi imposta configurate in WooCommerce quelle con aliquota pari a 0% (di solito la classe si chiama "Zero rate", ma il nome non è vincolante: conta l'aliquota). 5. Imposta codice natura e riferimento normativo per ciascuno dei 5 scenari gestiti: **Privati UE**, **Aziende UE con VIES validato**, **Aziende UE senza VIES validato**, **Privati extra-UE**, **Aziende extra-UE**. Confrontati con il tuo commercialista per i valori corretti caso per caso. 6. Se usi un add-on di trasmissione verso un gestionale esterno, assicurati che gli stessi codici natura siano configurati anche in quel gestionale. ## Verifica Effettua un acquisto di prova con una partita IVA UE reale e valida: se tutto è configurato correttamente, l'IVA viene rimossa dal carrello e la fattura riporta il codice natura previsto per lo scenario corrispondente. ## Errori comuni - **Il sito non riesce a validare la partita IVA del cliente** — probabile problema lato server: verifica che `SoapClient` sia disponibile (necessario per interrogare il servizio VIES). - **Il reverse charge non si attiva pur avendolo spuntato** — controlla che anche "Activate VIES validation" sia attivo: senza VIES, il reverse charge resta inattivo per design. - **Non trovi una classe imposta a aliquota zero da selezionare** — il menu mostra solo classi con aliquota 0% effettivamente configurate in WooCommerce: creane una in `Impostazioni > Imposte` se non esiste ancora. ## Configurazione correlata Per la tabella dei codici natura da applicare in base al regime fiscale del venditore vedi [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-auto-email-invoice ## Obiettivo Attivare l'invio automatico via email del PDF fattura, capire da quale indirizzo arriva e dove vanno le risposte del cliente. ## Prerequisiti - Un piano a pagamento (Basic o superiore): l'invio automatico non è disponibile sul piano Free. - Accesso a **Settings** nell'app POP for Shopify. ## Passi POP ha due impostazioni email distinte, non intercambiabili: 1. **Invio automatico via email** (card "Invio automatico via email") — se attiva, POP invia il PDF all'indirizzo email dell'ordine ogni volta che un documento viene generato, sia manualmente dall'app Orders sia automaticamente. Qui puoi anche impostare: - **Email di risposta** — l'indirizzo a cui arrivano le risposte del cliente (non è fisso: è configurabile per negozio). - **Email di copia per il merchant** — se impostata, ogni invio (manuale o automatico) manda anche una copia in BCC a questo indirizzo, invisibile al cliente. 2. **Invio automatico PDF al pagamento** (card separata) — controlla se, quando un ordine viene pagato, il PDF venga inviato automaticamente al cliente e/o in copia al merchant. Il toggle per il merchant richiede che l'email di copia sopra sia già configurata. ## Verifica - Genera un documento da un ordine di test e controlla che il PDF arrivi all'email associata all'ordine. - Rispondi all'email ricevuta e verifica che la risposta raggiunga l'indirizzo impostato in **Email di risposta** (se non impostato, la mail parte comunque da `noreply@popapi.io`). - Se hai impostato l'email di copia merchant, controlla che ogni invio produca anche una BCC su quella casella. ## Errori comuni - **Il cliente non riceve il PDF** — verifica di essere su un piano a pagamento e che **Invio automatico via email** (o **Invio automatico PDF al pagamento**, a seconda del trigger) sia attivo. - **Le risposte del cliente vanno perse** — imposta **Email di risposta**: di default le email partono da `noreply@popapi.io`, un indirizzo non monitorato. - **Il merchant non riceve la copia** — controlla che **Email di copia per il merchant** sia valorizzata; senza quel valore il toggle "copia al merchant" nell'invio automatico al pagamento non ha effetto. ## Configurazione correlata Per personalizzare il contenuto del PDF stesso (footer, logo), vedi [shopify-customize-invoice-pdf](shopify-customize-invoice-pdf.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-bank-transfer-payment ## Obiettivo Far comparire automaticamente i dati bancari nel documento generato quando il metodo di pagamento dell'ordine è un bonifico. ## Prerequisiti - Accesso a **Settings > Pagamento con bonifico bancario** nell'app POP for Shopify. ## Passi 1. Compila **Beneficiario** con lo stesso nome presente nelle impostazioni di pagamento di Shopify. 2. Compila **Nome banca** e **IBAN**. 3. Facoltativo: imposta **Giorni di pagamento** (es. 30) per indicare la scadenza del bonifico in fattura. POP rileva automaticamente se un ordine è stato pagato tramite bonifico/bank transfer (in base al metodo o gateway di pagamento Shopify usato in fase di checkout) e, solo in quel caso, inserisce beneficiario, banca e IBAN configurati nell'XML e nel PDF, per SdI e PEPPOL. Per ordini pagati con altri metodi (carta, PayPal, contrassegno, addebito diretto...) questi campi non vengono inseriti. ## Verifica - Genera un documento per un ordine pagato con bonifico e controlla che beneficiario, banca e IBAN compaiano nella sezione pagamento del PDF/XML. - Genera un documento per un ordine pagato con carta e verifica che questi campi non compaiano. ## Errori comuni - **I dati bancari non compaiono in un ordine pagato con bonifico** — verifica che il gateway/metodo di pagamento Shopify usato sia effettivamente riconosciuto come bonifico/bank transfer; metodi di pagamento personalizzati con nomi non standard potrebbero non essere rilevati. - **I dati compaiono su un ordine pagato diversamente** — non dovrebbe succedere: verifica il metodo di pagamento effettivo dell'ordine in Shopify Admin. ## Configurazione correlata Per il contratto del blocco pagamento nel payload, vedi [api/sdi](../../api/sdi.md) e [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-checkout-vat-tax-code-fields ## Obiettivo Configurare se e quando richiedere Partita IVA e Codice Fiscale ai clienti in checkout, distinguendo tra clienti UE ed extra-UE. Questa sezione riguarda solo store **Shopify Plus**: per store non-Plus, i campi fiscali si aggiungono al carrello tramite script embed, con una configurazione separata (vedi [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Prerequisiti - Store su **Shopify Plus** (la sezione **Settings > Checkout** non è visibile su piani non-Plus, dato che controlla una Checkout UI Extension disponibile solo su Plus). ## Passi Nella sezione **Checkout**: 1. **Partita IVA e codice fiscale per clienti UE** — scegli se rendere i campi **obbligatori** (utile per B2B o quando servono dati fiscali completi) o **non obbligatori** (checkout più semplice). 2. **Partita IVA e codice fiscale per clienti extra-UE** — scegli se **mostrare** i campi (per esigenze fiscali o verifiche manuali) o **non mostrarli** (se non rilevanti ai fini IVA). Questi due toggle controllano solo la Checkout UI Extension di Shopify Plus. Su store non-Plus i campi obbligatori/opzionali si configurano separatamente nello script embed (vedi [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Verifica - Da un negozio di test, avvia un checkout con un indirizzo di fatturazione UE e verifica che il campo P.IVA/CF risulti obbligatorio o facoltativo secondo l'impostazione. - Ripeti con un indirizzo extra-UE e verifica che i campi compaiano o meno secondo l'impostazione. ## Errori comuni - **I clienti italiani vedono comunque i campi Codice Fiscale/PEC nativi di Shopify** — sono campi applicati nativamente da Shopify per l'Italia e non possono essere rimossi o modificati da POP; sono comunque opzionali. Per disattivarli serve una richiesta specifica al supporto Shopify. - **I campi non appaiono affatto in checkout** — verifica che la Checkout Extension sia attiva. Su store non-Plus, questa sezione delle impostazioni non è nemmeno visibile: usa lo script di embed sul carrello invece (vedi [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md)). ## Configurazione correlata Per come questi dati vengono poi letti e prioritizzati da POP in fase di fatturazione, vedi [shopify-fiscal-data-management](shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-customize-invoice-pdf ## Obiettivo Personalizzare l'aspetto del PDF fattura generato da POP: testo del footer, logo e (opzionale) nome del file scaricato. ## Prerequisiti - Un piano a pagamento: la personalizzazione PDF non è disponibile sul piano Free. - Accesso a **Settings > Personalizzazione PDF** nell'app POP for Shopify. ## Passi 1. **Testo del footer** — inserisci note legali, coordinate bancarie o link utili da mostrare in fondo al PDF. 2. **Logo fattura** — carica un'immagine da mostrare in testa al PDF: - formati accettati: **PNG, JPG o SVG**; - per PNG/JPG: **massimo 600px** di lato e **massimo 500KB**; - dopo il caricamento, l'URL del logo compare nel campo "URL del logo" (puoi anche rimuoverlo con **Rimuovi logo**). 3. **Usa il numero fattura nel nome del PDF** (toggle opzionale) — se attivo, il nome del file download/email usa partita IVA + numero fattura; la chiave di archiviazione interna resta invariata. ## Da sapere - **Lingua del titolo documento** — il titolo "Fattura"/"Nota di credito" sul PDF segue automaticamente la lingua/locale Shopify del cliente (tedesco, inglese, spagnolo, francese, francese-Belgio, italiano o olandese), non il paese del merchant. Se il locale del cliente non rientra tra questi, il titolo torna in inglese. Non è configurabile — è un comportamento automatico su ogni documento. ## Verifica - Genera un documento di prova e controlla che footer e logo compaiano nel PDF. - Se hai attivato il toggle sul nome file, scarica il PDF e verifica che il nome contenga partita IVA e numero fattura. ## Errori comuni - **"Carica un'immagine PNG, JPG o SVG."** — il file caricato non è in uno dei formati accettati. - **"Il logo deve pesare meno di 500KB."** — comprimi l'immagine prima di ricaricarla. - **"Il logo deve avere massimo {max}px per lato."** — ridimensiona il PNG/JPG entro il limite indicato prima del caricamento. - **Non vedo queste opzioni** — la personalizzazione PDF richiede un piano a pagamento. ## Configurazione correlata Per l'invio automatico del PDF così personalizzato, vedi [shopify-auto-email-invoice](shopify-auto-email-invoice.md). Per il formato dei documenti PDF, vedi [api/pdf](../../api/pdf.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-file-progressive-number ## Obiettivo Capire cos'è il "progressivo file" e gestirne il reset (automatico o manuale), separatamente dal numero fattura legale. ## Prerequisiti - Accesso a **Settings > Progressivo file** nell'app POP for Shopify. ## Cos'è Il progressivo file è il contatore usato nel nome del file XML/PDF generato da POP — non è il numero fattura legale (per quello vedi [shopify-invoice-numbering](shopify-invoice-numbering.md)). È rilevante soprattutto per l'invio allo SdI, che richiede nomi file con progressivi ordinati; per PEPPOL non è obbligatorio ma è comunque consigliato mantenerlo ordinato per coerenza amministrativa. ## Passi Nella card **Progressivo file**: 1. **Reset automatico al cambio anno** — se attivo, il contatore riparte da `00001` al primo documento generato dell'anno successivo. 2. **Resetta progressivo adesso** — reset manuale immediato, utile dopo una migrazione o dopo test in sandbox. Usalo solo dopo aver inviato tutti i documenti dell'anno precedente. La card mostra sempre lo stato attuale ("Stato attuale: anno {anno}, contatore {contatore}") e la data dell'ultimo reset. ## Verifica - Dopo un reset manuale, genera un nuovo documento e controlla che il contatore nel nome file riparta da `00001`. - Con il reset automatico attivo, verifica che il primo documento generato nel nuovo anno solare riparta da `00001` senza intervento manuale. ## Errori comuni - **"Reset the document progressive for {anno} in Settings before generating new files."** — POP blocca la generazione perché il progressivo dell'anno corrente non è stato ancora inizializzato/resettato: vai in Settings ed esegui **Resetta progressivo adesso**. - **Il progressivo non si azzera a gennaio** — verifica che **Reset automatico al cambio anno** sia attivo; se disattivo il contatore continua a incrementare oltre il cambio anno. - **Confusione con il numero fattura** — se il numero che vedi in fattura non cambia dopo un reset qui, stai probabilmente cercando l'impostazione sbagliata: il numero fattura si configura separatamente in [shopify-invoice-numbering](shopify-invoice-numbering.md). ## Configurazione correlata Vedi [api/sdi](../../api/sdi.md) per i requisiti di nomenclatura file richiesti dal Sistema di Interscambio. --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-fiscal-data-management ## Obiettivo Capire da dove POP legge i dati fiscali del cliente (tipo cliente, P.IVA, Codice Fiscale, PEC) e dove correggerli manualmente prima di fatturare. ## Prerequisiti - Accesso a Shopify Admin (ordine e/o cliente). ## Passi POP usa due meccanismi per i dati fiscali del cliente su un ordine: 1. **Metafield ordine `app.pop_*`** — campi strutturati creati automaticamente da POP (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), popolati da checkout (Checkout Extension su Shopify Plus, script embed su non-Plus) o dalla rilevazione automatica dai dati cliente. Se pinnati in Shopify Admin, sono visibili e modificabili direttamente dall'operatore. 2. **customAttributes dell'ordine** ("Additional details") — meccanismo storico, non strutturato, usato come fallback quando i metafield non sono valorizzati. **Priorità**: quando POP genera un documento, legge prima i metafield ordine `app.pop_*`; ricorre ai customAttributes solo se i metafield corrispondenti sono assenti. I metafield **cliente** (stesso namespace/chiavi) salvano gli stessi dati sul profilo cliente per precompilare i checkout successivi. ### Correggere un dato fiscale prima di fatturare 1. Apri l'ordine in Shopify Admin. 2. Modifica il metafield ordine `app.pop_*` interessato (deve essere pinnato per essere visibile). 3. Salva: la generazione successiva userà subito il valore aggiornato. Se i metafield non risultano creati (es. wizard/licenza POP non completati), l'app mostra nella Home una sezione di recovery con un pulsante per ricrearli manualmente. ## Verifica - Genera un documento per un ordine con metafield `app.pop_vat` valorizzato diverso dal customAttribute corrispondente: il documento deve usare il valore del metafield. - Dopo aver modificato un metafield ordine pinnato, rigenera il documento e verifica che il nuovo valore sia stato usato. ## Errori comuni - **Non vedo i campi fiscali sull'ordine o sul cliente** — verifica che wizard/licenza POP siano completati e che i metafield `pop_*` risultino creati; se mancanti, usa il pulsante di ricreazione dalla Home. - **Ho corretto il customAttribute ma la fattura non cambia** — i metafield ordine hanno sempre priorità: correggi il metafield, non il customAttribute. - **Store non-Plus, POS o ordini manuali** — su questi canali i dati potrebbero non essere raccolti in checkout: vanno inseriti manualmente nei metafield ordine prima della fatturazione (vedi [shopify-non-plus-billing-fields](shopify-non-plus-billing-fields.md) per la raccolta via tema). ## Configurazione correlata Per l'indirizzo di fatturazione del **cliente** su un ordine specifico, vedi [shopify-billing-address-override](../troubleshooting/shopify-billing-address-override.md). Per l'indirizzo del **venditore**, vedi [shopify-seller-fiscal-data](shopify-seller-fiscal-data.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-invoice-numbering ## Obiettivo Configurare il numero fattura inviato nei documenti SdI e PEPPOL: cifre, azzeramento annuale, prefisso, suffisso e numero di partenza. ## Prerequisiti - Accesso a **Settings > Numerazione fatture** nell'app POP for Shopify. ## Passi Nella card **Numerazione fatture**: 1. **Numero di cifre** — imposta il padding numerico (es. `4` → il numero 13 diventa `0013`). 2. **Azzera la numerazione ad ogni cambio anno** — se attivo, il contatore riparte da 1 al primo gennaio. 3. **Prefisso fattura** — testo prima del numero (es. `POP-0013`). 4. **Suffisso** — testo dopo il numero (es. `0013-A`); disattivato automaticamente se usi l'anno come suffisso. 5. **Imposta l'anno come suffisso** — aggiunge l'anno al numero (es. `0013/2025`), con formato breve (`/YY`) o lungo (`/YYYY`) a scelta. Nella sotto-sezione **Prossimo numero disponibile** puoi impostare manualmente il prossimo numero fattura e l'anno di riferimento del progressivo (utile dopo una migrazione o per allinearti a una numerazione già in uso altrove) e confermare con **Imposta manualmente**. ## Verifica - Genera un documento di prova (in sandbox, vedi [use-sandbox-environment](../configuration/use-sandbox-environment.md)) e controlla che il numero fattura rispetti cifre, prefisso e suffisso configurati. - Dopo un'impostazione manuale del numero, il primo documento generato deve usare esattamente quel numero. ## Errori comuni - **"Errore nella numerazione delle fatture: {messaggio}"** — la generazione del numero fattura ha fallito lato POP; riprova, e se persiste verifica che non ci sia un numero manuale incoerente impostato di recente. - **Il numero non si azzera all'anno nuovo** — controlla che **Azzera la numerazione ad ogni cambio anno** sia attivo; questa impostazione è indipendente dal reset del [progressivo file](shopify-file-progressive-number.md). - **Confondere questa numerazione con il "progressivo file"** — la numerazione fattura è il numero legale del documento (SdI/PEPPOL); il progressivo file è un contatore separato usato solo nel nome del file generato. Vedi [shopify-file-progressive-number](shopify-file-progressive-number.md). ## Configurazione correlata Per il contratto dei campi numero fattura nel payload, vedi [api/sdi](../../api/sdi.md) e [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-non-plus-billing-fields ## Obiettivo Aggiungere i campi fiscali POP (tipo cliente, P.IVA, Codice Fiscale, PEC/SDI) al carrello e/o cart drawer su uno store Shopify **non-Plus** (Basic/Grow/Advanced), senza Checkout UI Extension. ## Prerequisiti - Account Shopify non-Plus. - Accesso al codice del tema (`theme.liquid` o sezione del carrello). ## Passi 1. Incolla lo script `pop-noplus-embed.js` (fornito da POP, caricato da `pub.popapi.io`) poco prima di `` in `theme.liquid`, o nella sezione/template del carrello, **preceduto** dal blocco `window.POP_EMBED_CONFIG` con i tuoi parametri. 2. Esempio di configurazione completa per uno store italiano (`mode: 'sdi'`), con testi personalizzati: ```html ``` 3. Salva il tema. ## Personalizzare i testi (`labels`) Ogni testo visibile è sovrascrivibile tramite `labels: {...}` — se ometti una chiave, resta il valore di default (in inglese, salvo `toggle.label` e `taxCodeOptOut.label/note` che di default sono già in italiano): | Chiave | Default | Cosa controlla | | --- | --- | --- | | `title` | "Electronic invoicing details" | Titolo del blocco campi | | `customerType` | "Customer type" | Etichetta del select tipo cliente | | `private` / `company` / `freelance` | "Private" / "Company" / "Freelance" | Opzioni del select tipo cliente | | `vat` | "VAT number" ("VAT/NIP" in modalità `ksef`) | Etichetta campo Partita IVA | | `taxCode` | "Tax code" | Etichetta campo Codice Fiscale (solo `sdi`) | | `pec` | "PEC or Recipient code" | Etichetta campo PEC/SDI (solo `sdi`) | | `vatPlaceholder` | `IT12345678901` (`PL1234567890` in `ksef`, `DE123456789` in `zugferd`) | Placeholder campo P.IVA | | `taxPlaceholder` | `RSSMRA80A01H501Z` | Placeholder campo Codice Fiscale | | `pecPlaceholder` | `you@pec.it / Z4G7P1Q` | Placeholder campo PEC/SDI | | `errorVat`, `errorTax`, `errorRequiredVat`, `errorPec` | messaggi in inglese | Messaggi di validazione per ciascun campo | | `globalError` | "Complete billing details to proceed to checkout." | Messaggio mostrato se il checkout viene bloccato per dati mancanti | ## Alternativa senza script esterno Se preferisci un form autonomo (HTML+CSS+JS inline, senza caricare uno script esterno da `pub.popapi.io`), sono disponibili snippet drop-in pronti per copia-incolla, uno per modalità, nel repository pubblico [`pop-snippets-library`](https://github.com/getpopapi/pop-snippets-library/tree/main/shopify/non-plus): `cart-attributes-for-sdi.liquid`, `cart-attributes-for-peppol-b2b.liquid` e `cart-attributes-for-peppol-b2b-b2c.liquid`. Coprono meno casi (nessun supporto `zugferd`/`ksef` dedicato) ma non richiedono di gestire `POP_EMBED_CONFIG`. ## Verifica 1. Aggiungi un prodotto al carrello. 2. Apri la pagina carrello (o il cart drawer, a seconda di dove hai inserito i container). 3. Compila i campi (es. Partita IVA). 4. Procedi al checkout. 5. Controlla che POP riceva i dati al momento della generazione della fattura (vedi [shopify-fiscal-data-management](shopify-fiscal-data-management.md) per dove verificarli sull'ordine). ## Errori comuni - **I campi non compaiono su una pagina** — se il container CSS indicato (`cartContainerSelector` o `drawerContainers`) non esiste in quella pagina, lo script semplicemente non mostra nulla: non è un errore, verifica il selettore. - **Passare da "azienda" a "privato" non svuota i campi** — è il comportamento atteso solo se il cambio non viene intercettato: in `peppol`/`zugferd` il cambio a "privato" svuota la P.IVA, in `sdi` svuota anche PEC/SDI, sincronizzando subito gli attributi carrello. - **Store Shopify Plus** — non serve modificare il tema: usa la Checkout Extension nativa POP invece dello script embed. ## Configurazione correlata Su store non-Plus, obbligatorietà e opzioni dei campi si configurano qui nello script embed (`customerOptions`, `taxCodeOptOut`), non nella sezione **Settings > Checkout** (quella riguarda solo Shopify Plus, vedi [shopify-checkout-vat-tax-code-fields](shopify-checkout-vat-tax-code-fields.md)). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-order-metafields-reporting ## Obiettivo Rendere numero fattura, numero nota di credito e stato di invio POP leggibili da app di reporting Shopify di terze parti (es. Report Pundit), senza export manuali né l'integrazione a pagamento "POP to Webhook". ## Cosa serve - Nessuna configurazione: i metafield vengono creati automaticamente al primo caricamento dell'app POP dopo l'aggiornamento (funziona anche su installazioni già esistenti). - Per leggerli da un'app terza (es. Report Pundit): mappa i seguenti metafield nella configurazione di quell'app. ## Metafield disponibili Tutti sotto il namespace `app`, visibili nativamente nella pagina ordine di Shopify Admin (sono "pinned"): | Chiave | Tipo | Contenuto | | --- | --- | --- | | `app.pop_fattura_numero` | testo | Numero fattura (es. `0787/2026`) | | `app.pop_fattura_status` | testo | Stato del canale attivo per la fattura (es. `RC`, `MC`, `NS`, `sent`, `valid`) | | `app.pop_nota_credito_numero` | JSON | `{ "": "" }`, una voce per ogni nota di credito sull'ordine | | `app.pop_nota_credito_status` | JSON | `{ "": "" }`, stesso schema | ## Da sapere - Il numero fattura viene pubblicato **indipendentemente** dall'invio a un canale ufficiale (SdI, PEPPOL, ecc.): anche gli store solo-PDF o su mercati senza canale ufficiale ottengono il metafield popolato. - Se lo stato passa a `NS` (non spedibile), il numero fattura resta invariato: cambia solo lo stato. - Un ordine può avere più note di credito (rimborsi multipli): ogni nota di credito ha la propria voce nel JSON, indicizzata per id del rimborso. ## Verifica 1. Genera una fattura (o nota di credito) su un ordine di test dopo l'aggiornamento. 2. Apri l'ordine in Shopify Admin: i metafield `app.pop_fattura_numero` e `app.pop_fattura_status` devono comparire nella sezione metafield, con i valori attesi. 3. Configura la tua app di reporting per leggere questi metafield sull'ordine. ## Errori comuni - **Gli ordini vecchi non hanno il metafield valorizzato**: atteso, i metafield vengono popolati solo dalle fatture generate dopo l'aggiornamento, non retroattivamente. Per un ordine specifico, rigenera il documento per farlo comparire. - **I metafield non compaiono affatto sulla pagina ordine**: riapri l'app POP da Shopify Admin, le definizioni dei metafield vengono create al primo caricamento dopo l'aggiornamento. ## Configurazione correlata Per capire quando POP genera effettivamente la fattura o la nota di credito su Shopify, vedi [shopify-faq](../getting-started/shopify-faq.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-reverse-charge ## Obiettivo Configurare i codici di esenzione/natura IVA per l'inversione contabile, per ciascuna delle categorie cliente gestite da POP. ## Prerequisiti - Accesso a **Settings > Inversione Contabile** nell'app POP for Shopify. ## Passi POP gestisce l'inversione contabile su cinque categorie cliente, ciascuna con una coppia di campi **Tipo** (codice natura per SdI, es. `N2.1`, oppure codice VATEX per PEPPOL a seconda del canale di invio) e **Descrizione** (motivazione dell'esenzione): 1. Privati UE 2. Azienda UE (P.IVA validata VIES) — SdI/PEPPOL 3. Azienda UE (P.IVA non validata VIES) — SdI/PEPPOL 4. Privati extra-UE 5. Aziende extra-UE — SdI/PEPPOL Per gli store che inviano a KSeF, il campo Tipo per le categorie UE/extra-UE mostra un suggerimento del valore accettato (`zero_wdt` per UE, `zero_export` per extra-UE). 1. Per ogni categoria, compila **Tipo** e **Descrizione** secondo il regime fiscale applicabile. 2. Salva le impostazioni: verranno usate automaticamente in fase di generazione documento in base al canale (SdI, PEPPOL o KSeF) e al tipo di cliente/paese rilevato sull'ordine. ## Verifica - Genera un documento di prova per un ordine con cliente UE con P.IVA validata VIES e controlla che XML/PDF riportino il codice natura e la descrizione configurati per quella categoria. - Ripeti per un cliente privato extra-UE e verifica la categoria corrispondente. ## Errori comuni - **PEPPOL non invia a clienti privati** — indipendentemente dai codici di inversione contabile configurati, l'invio PEPPOL automatico salta sempre i clienti privati (B2C); resta disponibile il download del PDF come documento di cortesia. - **Il codice non corrisponde a quanto atteso da SdI/PEPPOL** — verifica di aver usato il formato corretto per il canale attivo (natura SdI vs VATEX PEPPOL): lo stesso campo Tipo viene interpretato in modo diverso a seconda del canale di invio. ## Configurazione correlata Per il contratto dei campi di esenzione IVA nel payload, vedi [api/sdi](../../api/sdi.md) e [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-seller-fiscal-data ## Obiettivo Sostituire l'indirizzo di fatturazione predefinito di Shopify con i dati fiscali corretti del venditore nei documenti generati da POP (PDF, XML SdI, UBL PEPPOL). ## Prerequisiti - Accesso a **Settings > Dati fiscali del venditore** nell'app POP for Shopify. ## Passi Compila tutti i campi della sezione **Dati fiscali del venditore**: - Email di fatturazione - Telefono - Indirizzo (riga 1) ed eventualmente riga 2 - CAP - Città - Provincia (codice ISO a 2 lettere) - Paese (codice ISO a 2 lettere) L'override si attiva solo se **tutti** i campi obbligatori sono compilati: la card mostra un badge **"Override attivo"** quando la configurazione è completa, **"Override non completo"** in caso contrario. Se anche un solo campo manca, POP usa l'indirizzo di fatturazione configurato su Shopify al suo posto (campo per campo: un valore mancante qui non azzera gli altri, ricade sempre sul dato Shopify corrispondente). ## Verifica - Con tutti i campi compilati, genera un documento di prova e controlla che l'indirizzo emittente nel PDF/XML corrisponda ai dati inseriti qui, non a quelli del negozio Shopify. - Svuota un singolo campo (es. Città) e verifica che il documento successivo usi il valore Shopify solo per quel campo specifico. ## Errori comuni - **Il documento mostra ancora l'indirizzo Shopify** — controlla il badge: se mostra "Override non completo" manca almeno un campo obbligatorio. - **Provincia o Paese rifiutati** — vanno inseriti come codice ISO a 2 lettere (es. `MI`, `IT`), non per esteso. ## Configurazione correlata Questa impostazione riguarda solo l'indirizzo del **venditore/emittente**. Per i dati fiscali del **cliente** (P.IVA, Codice Fiscale, tipo cliente) vedi [shopify-fiscal-data-management](shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/shopify-zero-amount-orders ## Obiettivo Configurare come POP tratta gli ordini Shopify con totale a zero (sconti al 100%, coupon, articoli omaggio) per evitare fatture inutili o numerazioni sprecate. ## Prerequisiti - Accesso a **Settings > Documenti** nell'app POP for Shopify. ## Passi Nella sezione **Documenti** dell'app sono disponibili due opzioni indipendenti: 1. **Disabilita documento** — se attiva, quando il totale ordine è zero POP non genera né il documento né un numero fattura per quell'ordine. 2. **Rimuovi prodotti** — rimuove dalla fattura le sole righe con totale zero (es. omaggi, articoli a sconto 100%), mantenendo il documento per il resto dell'ordine. Le due opzioni sono indipendenti: puoi attivarle entrambe, singolarmente, o nessuna delle due. ## Verifica - Con **Disabilita documento** attivo, un ordine a totale zero mostra nella tabella Ordini il messaggio "Il totale dell'ordine è 0. La generazione di documenti è disabilitata." e i pulsanti di generazione restano inattivi per quell'ordine. - Con **Rimuovi prodotti** attivo, genera un documento su un ordine con almeno una riga a prezzo zero e verifica che quella riga non compaia nel PDF/XML risultante. ## Errori comuni - **Il documento non viene creato e non capisco perché** — controlla se **Disabilita documento** è attivo: è il comportamento atteso per ordini a totale zero, non un errore. - **Le righe omaggio compaiono comunque in fattura** — verifica che **Rimuovi prodotti** sia attivo; se disattivato, tutte le righe (anche a prezzo zero) restano in fattura. ## Configurazione correlata Vedi [shopify-invoice-numbering](shopify-invoice-numbering.md) per capire come la numerazione fattura si comporta quando un documento viene saltato per totale zero. --- ## Source: https://docs.popapi.io/it/guides/configuration/tax-regime-invoicing-rules ## Obiettivo Orientarsi su come cambia il trattamento IVA in fattura in base al regime fiscale impostato nella tab **General** e al tipo di cliente. > Gli esempi sono illustrativi: la configurazione di nature IVA e riferimenti normativi va sempre > confermata con il proprio commercialista, perché varia in base al regime, al tipo di operazioni e > alle modalità di vendita. ## Regola verificata nel plugin: Forfettario/Minimi e tasse WooCommerce Se il regime fiscale impostato è **RF19 (Forfettario)** o **RF02 (Regime dei minimi)**, le tasse WooCommerce devono restare **disattivate** (`WooCommerce > Impostazioni > Imposte`). Se le lasci attive, il plugin genera un avviso in `wp-admin`: con le tasse attive in questi regimi, gli ordini generati risultano incoerenti col regime fiscale selezionato, con rischio di fatture non valide. ## Riferimento per tipo di cliente | Cliente | Regime Ordinario | Regime Forfettario/Minimi | | --- | --- | --- | | Italiano (Azienda o Privato) | IVA 22% | Nessuna IVA — natura **N2.2** | | Azienda UE, iscritta VIES | Reverse charge — natura **N2** (art. 7-ter) | Nessuna IVA né reverse charge — natura **N2.2** | | Privato UE o azienda UE non iscritta VIES | IVA italiana ordinaria | Nessuna IVA — natura **N2.2** | | Azienda extra-UE | Non soggetta — natura **N2** (art. 7-quater) | Nessuna IVA — natura **N2.2** | | Privato extra-UE | Non soggetta — natura **N2** (art. 7-quater) | Nessuna IVA — natura **N2.2** | Per aziende/privati UE, in fattura elettronica vanno indicati anche codice destinatario (7 X di default se assente), codice paese cliente, partita IVA (o `9999999999` se non disponibile per privati) e CAP (`00000` se non disponibile) — il codice fiscale non va inserito per clienti esteri. ## Regime OSS per vendite B2C intra-UE Solo per chi è in **Regime Ordinario**: superata la soglia di 10.000€/anno di vendite B2C intra-UE, serve registrarsi al regime OSS (One Stop Shop) e applicare l'IVA del paese del cliente, con codice natura **N7**. Chi è in Regime Forfettario non applica l'OSS: resta sempre **N2.2**. ## Verifica Genera un ordine di prova per ciascuno scenario rilevante per il tuo negozio (es. cliente UE con/senza VIES) e controlla che natura e riferimento normativo in fattura corrispondano alla tabella concordata con il tuo commercialista. ## Errori comuni - **Notice "For RF19/RF02 (Forfettario/Minimi), taxes must be disabled"** — disattiva le tasse in WooCommerce: è un requisito, non un suggerimento, per questi due regimi. - **Codice natura sbagliato per un cliente UE** — verifica se la partita IVA è validata dal VIES: cambia la natura da applicare (N2 vs N2.2 a seconda del regime, ma con condizioni diverse VIES/non-VIES). - **Serve applicare il reverse charge** — vedi [reverse-charge](reverse-charge.md) per come configurarlo operativamente in POP. ## Configurazione correlata Per l'attivazione tecnica del reverse charge vedi [reverse-charge](reverse-charge.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/transmitter-data ## Obiettivo Compilare, se necessario, i dati del **trasmittente**: il soggetto che invia materialmente il file XML al Sistema di Interscambio, che può essere l'azienda stessa oppure un intermediario che opera per suo conto. ## Prerequisiti - Wizard di configurazione iniziale completato (vedi [first-installation](../getting-started/first-installation.md)). ## Passi 1. Vai su `POP → Electronic Invoice - Settings`, tab **General**, sezione **Transmission Data**. 2. Compila, se rilevante per il tuo caso, i campi (tutti **opzionali**): - **Transmitter ID** — partita IVA del trasmittente/intermediario. - **Transmitter Phone number**. - **Transmitter email address**. 3. Salva. Se non compili nulla, il canale di invio usato userà i valori di default previsti dal canale stesso (es. i propri dati come trasmittente diretto). ## Verifica Genera un documento di prova e verifica, nell'XML generato, che il blocco dati trasmittente rifletta i valori inseriti (o resti vuoto/di default se non li hai compilati). ## Errori comuni - **I campi risultano disabilitati/non modificabili** — dopo aver completato il wizard e collegato l'account (licenza attiva), i dati aziendali e del trasmittente in **General** diventano di sola lettura in `wp-admin`: eventuali modifiche successive vanno gestite dal pannello dell'account POP, non da qui. - **Usi l'add-on Aruba o un altro canale che agisce da intermediario per conto tuo** — in quel caso il canale può gestire i propri dati trasmittente in autonomia (es. il proprio codice fiscale come intermediario abilitato): verifica la documentazione specifica dell'add-on/canale attivo, perché può differire da quanto configurato qui nella tab General. - **Non sai se ti serve compilare questi campi** — se non usi un intermediario per l'invio (es. invii tramite SdI via POP direttamente come azienda), puoi lasciarli vuoti. ## Configurazione correlata Per la scelta del canale di trasmissione vedi [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/update-plugin ## Obiettivo Aggiornare il plugin POP alla versione più recente senza interrompere la generazione delle fatture. ## Prerequisiti - Accesso amministratore a `wp-admin`. - Idealmente, un ambiente di staging speculare al sito di produzione dove testare l'aggiornamento prima. ## Passi 1. Vai su `wp-admin > Plugin`. 2. Individua "POP – European e-invoicing compliance for e-commerce" (o "ex-WooPop"): se è disponibile un aggiornamento, WordPress lo segnala nella stessa riga. 3. Clicca **Aggiorna ora**. WordPress scarica e sostituisce i file del plugin mantenendo le impostazioni salvate (le opzioni sono salvate nel database, non nei file del plugin). 4. Al termine, apri `POP → Electronic Invoice - Settings` per verificare che le tab si aprano correttamente e che i dati precedentemente configurati (General, Numeration, Documents...) siano ancora presenti. ## Verifica - La versione mostrata in `wp-admin > Plugin` (accanto al nome del plugin) corrisponde alla release scaricata. - Genera un ordine di prova (o in sandbox) per confermare che XML e PDF vengono ancora prodotti correttamente dopo l'aggiornamento. ## Errori comuni - **Dopo l'update una impostazione sembra sparita o diversa** — controlla il changelog della versione installata prima di aprire un ticket: alcune opzioni vengono rinominate o spostate tra tab quando cambia la struttura delle impostazioni. Vedi [changelog/wordpress-plugin](../changelog/wordpress-plugin.md) per dove trovare le note di rilascio. - **Comportamento diverso rispetto a prima dell'update** — verifica se il changelog lo indica come modifica intenzionale, prima di considerarlo un bug. - **Vuoi rimandare un aggiornamento importante** — testalo prima in staging: non è possibile garantire compatibilità universale con ogni combinazione di temi/plugin di terze parti installati sul tuo e-commerce. ## Configurazione correlata Per i requisiti minimi supportati dalla versione corrente vedi [minimum-requirements](../getting-started/minimum-requirements.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/use-sandbox-environment ## Obiettivo Eseguire richieste di test verso l'API POP senza consumare crediti dell'account. ## Prerequisiti - Una `license_key` valida (vedi [get-your-license-key](../getting-started/get-your-license-key.md)). ## Passi Puoi attivare la sandbox in due modi equivalenti: 1. **Parametro esplicito** — invia `"environment": "sandbox"` nel body verso `https://popapi.io/wp-json/api/v2/...`. 2. **Gateway sandbox** — chiama `https://sandbox.popapi.io/wp-json/api/v2/...` senza specificare `environment`: il gateway lo forza automaticamente. Se invii comunque `environment` esplicito, quello ha priorità. Tutte le route di generazione documento (SdI, PEPPOL, KSeF, PDF, ZUGFeRD, Facturae legacy) accettano `environment: sandbox`. ## Verifica - Le richieste sandbox non consumano credito. - Sulle route XML, `invoice_number` viene restituito con prefisso `SANDBOX-`. ## Errori comuni - **Il webhook configurato non riceve nulla in sandbox** — la consegna via webhook non è disponibile in sandbox: è un limite atteso, non un errore di configurazione. - **La consegna a Fatture in Cloud non parte in sandbox** — stesso motivo: non supportata in sandbox. - **L'invio email PDF non funziona in sandbox** — non è un limite: la consegna email PDF è consentita anche in sandbox. ## Configurazione correlata Vedi [api/sdi](../../api/sdi.md) e le altre pagine `api/*` per il comportamento specifico di ogni route in sandbox. --- ## Source: https://docs.popapi.io/it/guides/configuration/virtual-stamp-duty ## Obiettivo Aggiungere automaticamente la marca da bollo virtuale (2€) sulle fatture emesse senza IVA quando l'importo supera la soglia di legge, ed eventualmente addebitarla al cliente. ## Prerequisiti - Negozio con paese fatturazione **Italia o San Marino**: l'opzione è visibile solo in questo caso. - Fatture emesse senza applicazione dell'IVA (es. regime Forfettario/Minimi, o comunque nature IVA che escludono l'imposta). ## Passi 1. Vai su `POP → Electronic Invoice - Settings`, tab **Documents**, sezione **Stamp duty**. 2. Attiva **"Add virtual stamp duty on invoices"**. Il bollo (2€) viene applicato automaticamente quando la fattura/PDF viene emessa senza IVA e l'importo dell'ordine supera **77,47€**. 3. Se vuoi che sia il cliente a pagarlo (anziché assorbirlo tu come venditore), attiva anche **"Stamp duty charged to the customer"**: in questo caso l'importo viene aggiunto anche al carrello, a carico del cliente. ## Verifica Genera un ordine di prova senza IVA con totale superiore a 77,47€: la fattura deve mostrare la voce del bollo (2€). Se hai attivato l'addebito al cliente, verifica anche che l'importo compaia nel carrello prima del checkout. ## Errori comuni - **Non vedo l'opzione del bollo tra le impostazioni** — è visibile solo se il paese del negozio è Italia o San Marino: per altri paesi l'opzione non compare. - **Il bollo non viene applicato pur avendo attivato l'opzione** — controlla che la fattura sia effettivamente senza IVA (o a IVA zero) e che l'importo dell'ordine superi 77,47€: sotto questa soglia, o con IVA applicata, il bollo non scatta. - **Il cliente non vede l'addebito nel carrello** — verifica di aver attivato anche l'opzione specifica "a carico del cliente", non solo quella base: sono due checkbox distinte. ## Configurazione correlata Per capire quando una fattura risulta "senza IVA" in base al regime fiscale, vedi [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/it/guides/configuration/woocommerce-tax-settings ## Obiettivo Configurare le tasse in WooCommerce in modo da minimizzare differenze di arrotondamento tra i totali dell'ordine e quelli mostrati nella fattura elettronica. ## Cosa consiglia WooCommerce WooCommerce stesso consiglia di impostare i prezzi dei prodotti **al netto dell'IVA** (non IVA inclusa), proprio per evitare arrotondamenti imprecisi in fase di scorporo dell'imposta durante la generazione dei documenti fiscali. Non è un requisito imposto da POP: è la raccomandazione ufficiale di WooCommerce nella sua guida alla configurazione tasse. Se preferisci comunque lavorare con prezzi IVA inclusa, WooCommerce lo permette (tab **Imposte**, opzione "Sì, inserirò i prezzi inclusivi di imposte"), e POP gestisce anche questo caso. ## Perché possono comparire piccole differenze in fattura Un e-commerce è pensato per vendere, non per emettere documenti fiscali: quando i prezzi sono IVA inclusa, alcuni ricalcoli sono inevitabili per produrre un documento fiscalmente corretto: - **Totale di riga** — nel documento fiscale viene ricalcolato come prezzo unitario netto (al netto di eventuali sconti) per la quantità ordinata; può differire di pochi centesimi dal totale mostrato nell'ordine WooCommerce (che parte da un prezzo IVA inclusa). - **Totale IVA per aliquota** — viene ricalcolato come percentuale × imponibile aggregato per quell'aliquota; se il totale IVA dell'ordine WooCommerce differisce di pochi centesimi, la fattura usa il valore corretto dal punto di vista contabile. Queste differenze non sono un errore del plugin: garantiscono che la fattura rispetti le regole fiscali italiane anche quando il negozio lavora con prezzi IVA inclusa. ## Se vuoi passare a prezzi IVA esclusa su un catalogo già impostato IVA inclusa 1. Fai un backup completo del sito. 2. Esporta i prodotti in CSV con lo strumento nativo di WooCommerce. 3. Aggiorna i prezzi al netto delle imposte nel file esportato. 4. Reimporta i prodotti. ## Verifica Confronta il totale IVA di un ordine di test con quello riportato nella fattura generata: eventuali differenze di pochi centesimi sono attese e documentate qui, non un malfunzionamento. ## Errori comuni - **Il totale IVA in fattura non coincide esattamente con l'ordine** — vedi la spiegazione sopra: è un effetto dell'arrotondamento in scorporo IVA, non un bug. - **Vuoi eliminare del tutto le differenze** — l'unica strategia efficace è lavorare con prezzi IVA esclusa, come raccomandato da WooCommerce; non esiste un metodo di scorporo che, partendo dal prezzo lordo, ricostruisca sempre esattamente il prezzo netto originale. ## Configurazione correlata Per la vendita a clienti esteri (reverse charge) vedi [reverse-charge](reverse-charge.md); per i codici natura da usare in base al regime fiscale vedi [tax-regime-invoicing-rules](tax-regime-invoicing-rules.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/anonymous-generation ## Obiettivo Generare un documento fiscale (fattura, nota di credito o PDF) chiamando l'API POP senza aver ancora creato un account, per provare il formato di output prima di decidere se collegare un account vero. ## Cosa serve - Nessuna `license_key`: basta omettere il campo (o il header `X-API-Key`) dalla richiesta. - Un payload `data` valido, come per una chiamata autenticata. ## Cosa copre - Route disponibili: `create-xml` (SdI), `create-ubl` (PEPPOL), `create-ksef-xml` (KSeF), `create-zugferd` (ZUGFeRD), `create-pdf`. - Solo **generazione locale** del documento: nessun invio a un canale esterno (SdI, PEPPOL, KSeF, Zoho, Fatture in Cloud, Aruba, SdI via PEC). Per inviare un documento serve un account POP con un'integrazione attiva. - Limite: **1000 generazioni al mese per sito**, condiviso tra tutte le route sopra. ## Come viene identificato il chiamante Senza un account non c'è un `user_id` da usare: il limite mensile è tracciato per combinazione di `site_url` (se presente nel payload) e indirizzo IP della richiesta. Includere `site_url` nel payload rende il conteggio stabile anche se l'IP cambia (es. dietro un proxy o CDN). ## Verifica Chiama una delle route sopra senza `license_key`: se sotto il limite mensile, ottieni l'XML/PDF generato normalmente, come con un account autenticato. ## Errori comuni - **`pop_api_generation_rate_limit`** (429): limite mensile di generazioni anonime raggiunto per questo sito/IP, collega un account POP per continuare oltre le 1000 generazioni. - **L'invio a un canale fallisce**: atteso, la generazione anonima copre solo l'output locale del documento, non l'invio. Serve un account con l'integrazione desiderata attiva. ## Configurazione correlata Per collegare un account vero e sbloccare l'invio ai canali ufficiali, vedi [get-your-license-key](get-your-license-key.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/choosing-an-invoicing-integration ## Obiettivo Capire quale canale di invio attivare per il tuo store, tra quelli disponibili in POP. **I canali sono mutuamente esclusivi**: puoi averne attivo uno solo alla volta (l'attivazione di uno disattiva automaticamente gli altri). ## I canali disponibili | Canale | Per chi | Dipendenze esterne | Note | | --- | --- | --- | --- | | **SdI via POP** | Chi vuole il flusso più semplice per l'Italia: nessun servizio esterno da configurare | Nessuna | Trasmissione diretta a SdI, notifiche gestite dentro POP, verifica automatica del codice fiscale/partita IVA del destinatario. | | **SdI via PEC** | Piccoli volumi, chi ha già una casella PEC e non vuole account esterni aggiuntivi | Casella PEC | L'XML viene inviato via email PEC; le notifiche di esito vanno controllate manualmente nella casella PEC, non sono gestite automaticamente da POP. | | **Fatture in Cloud** | Chi usa già Fatture in Cloud per contabilità/fatturazione | Abbonamento Fatture in Cloud attivo | Passa dalle API ufficiali Fatture in Cloud; richiede la mappatura di [metodi di pagamento](../integrations/fatture-in-cloud-payment-methods.md) e conto di saldo prima del primo invio. | | **Aruba Business** | Chi usa già Aruba come fornitore di fatturazione elettronica | Attivazione API su Aruba | Meno margine di configurazione rispetto alle altre opzioni. | | **PEPPOL** | Vendite B2B verso l'estero (rete PEPPOL) | Nessuna | Non è un'alternativa a SdI per l'Italia: è il corridoio per la fatturazione elettronica intra-UE. Copre 28 paesi (elenco completo in [api/peppol](../../api/peppol.md)) — **Spagna esclusa** (corridoio Facturae, non ancora supportato), Irlanda del Nord e Liechtenstein esclusi. | | **KSeF** | Vendite verso la Polonia | NIP polacco | Vedi [attivazione KSeF](../integrations/ksef.md) — richiede una registrazione dedicata separata da SdI/PEPPOL. | | **Zoho (nativo)** | Chi usa Zoho Invoice/Zoho Books e vuole la sincronizzazione gestita direttamente da POP | Autorizzazione OAuth verso Zoho | Vedi [attivazione Zoho](../integrations/zoho.md). Non richiede un'istanza n8n propria. Per account con paese Emirati Arabi Uniti, Arabia Saudita, Bahrein, Kuwait, Oman o Qatar è l'**unico** canale disponibile: questi paesi non hanno una rete di fatturazione elettronica ufficiale supportata (niente SdI/PEPPOL/KSeF). | Se invece preferisci gestire tu la logica di sincronizzazione su una tua istanza n8n self-hosted (più controllo/personalizzazione), esiste anche un pacchetto dedicato — vedi [sincronizzazione Zoho via n8n](../integrations/n8n-zoho.md). ## Come scegliere - **Vendi solo in Italia e non usi già un gestionale esterno** → SdI via POP: è il percorso con meno passaggi di configurazione e le notifiche restano dentro POP. - **Usi già Fatture in Cloud o Aruba per la contabilità** → collega quell'integrazione invece di duplicare i dati altrove, ma preventiva il tempo per completare la mappatura richiesta (conti, metodi di pagamento). - **Pochissimi documenti al mese e vuoi zero costi/servizi aggiuntivi** → SdI via PEC, sapendo che dovrai controllare manualmente gli esiti nella casella PEC. - **Il tuo negozio ha sede in Italia o San Marino** → resta su SdI (via POP o via PEC) anche per i clienti business esteri: PEPPOL non si attiva mai in questo caso, indipendentemente dal paese del cliente. Le fatture verso l'estero passano comunque per SdI, con il codice destinatario convenzionale per i destinatari non italiani. - **Il tuo negozio ha sede in un paese UE diverso da Italia/San Marino coperto da PEPPOL** (elenco in [api/peppol](../../api/peppol.md)) e vendi B2B → usa PEPPOL: è il canale equivalente a SdI per la fatturazione elettronica in questi paesi. - **Vendi in Polonia** → serve KSeF, indipendentemente dal canale scelto per l'Italia. - **Il tuo account ha paese Emirati Arabi Uniti, Arabia Saudita, Bahrein, Kuwait, Oman o Qatar** → Zoho nativo è l'unica opzione: nessun altro canale è disponibile per questi paesi. ## Da sapere - Su WordPress nessuno di questi canali richiede un piano a pagamento per l'attivazione: ogni piano, incluso Free, può inviare a consumo di crediti. Su Shopify, PEPPOL, KSeF, Zoho nativo e il webhook richiedono ancora il piano Basic o superiore. - Attivare SdI via POP e PEPPOL contemporaneamente non è supportato: se entrambi risultano attivi, l'ultimo attivato prevale e l'altro viene disattivato automaticamente. - Cambiare canale in futuro è possibile, ma va rifatta la configurazione del nuovo canale (credenziali, mappature) — non c'è una migrazione automatica dei dati tra un'integrazione e l'altra. ## Configurazione correlata Per i dettagli di attivazione di ciascun canale, vedi le guide dedicate in questa stessa sezione ("Integrazioni"). --- ## Source: https://docs.popapi.io/it/guides/getting-started/first-installation ## Obiettivo Installare il plugin POP su un sito WordPress/WooCommerce e completare la configurazione iniziale dell'account. ## Prerequisiti - Un sito WordPress con WooCommerce attivo. - Versioni minime supportate: vedi [minimum-requirements](minimum-requirements.md). - Un indirizzo email per creare (o collegare) l'account POP. ## Passi 1. Scarica/installa il plugin da `wp-admin > Plugin > Aggiungi nuovo`, cercando "POP – European e-invoicing compliance for e-commerce", oppure carica lo zip scaricato da WordPress.org. 2. Clicca **Attiva**. 3. Al primo caricamento di una pagina di `wp-admin` dopo l'attivazione, il plugin reindirizza automaticamente al wizard (`POP → Electronic Invoice - Settings`, tab **Wizard setup**). Il reindirizzamento avviene una sola volta e solo se l'account non è ancora collegato (nessuna `license_key` né account POP associato). 4. Se non vieni reindirizzato, apri manualmente `POP → Electronic Invoice - Settings` e vai sulla tab **Wizard setup** (visibile solo finché l'account non è collegato). 5. Inserisci l'email dell'account: se hai già un account POP lo collega, altrimenti ne crea uno nuovo. Riceverai un codice OTP via email per autenticarti. 6. Completa i dati aziendali richiesti dal wizard (paese, regime fiscale se in Italia, dati anagrafici). Una volta completato, la tab **Wizard setup** scompare dal menu. ## Verifica - La tab **Wizard setup** non è più visibile tra le tab delle impostazioni. - In `POP → Electronic Invoice - Settings`, tab **General**, la licenza risulta collegata. - L'admin bar di WordPress mostra la voce POP con lo stato dell'ambiente (Live/Sandbox). ## Errori comuni - **Il wizard non parte da solo dopo l'attivazione** — il reindirizzamento è "one-shot": se nel frattempo hai già aperto un'altra pagina admin, apri direttamente `admin.php?page=wc_el_inv-options-page&tab=wizard&wizard=init`. - **Non arriva l'OTP via email** — controlla spam/filtri anti-spam del provider email; l'indirizzo usato per il wizard deve essere raggiungibile. - **Compatibilità non garantita con temi/plugin non testati** — prima di installare in produzione, testa in un ambiente di staging speculare all'e-commerce reale: non è possibile garantire compatibilità universale con ogni combinazione di tema/plugin. ## Configurazione correlata Per requisiti tecnici minimi vedi [minimum-requirements](minimum-requirements.md); per scegliere il canale di invio (SdI via POP, PEPPOL, KSeF, add-on) dopo il wizard vedi [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/get-your-license-key ## Obiettivo Ottenere una `license_key` valida per autenticare le richieste all'API POP. ## Prerequisiti - Un indirizzo email valido. - Accesso alla casella email per ricevere l'OTP. ## Passi 1. Apri `https://popapi.io/otp-login/`. 2. Inserisci il tuo indirizzo email. 3. Ricevi via email una password monouso (OTP). 4. Inserisci l'OTP. 5. Completa il wizard di configurazione account. 6. Apri `https://popapi.io/`. 7. Vai su `Account > API`. 8. Copia la `license_key` generata di default. ## Verifica Testa la chiave con: ```bash curl --request GET \ --url 'https://popapi.io/wp-json/api/v2/account-profile?sdk=wordpress' \ --header 'X-API-Key: YOUR_LICENSE_KEY' ``` Una risposta con `"authenticated": true` conferma che la chiave è valida. ## Errori comuni - **`account-profile` risponde non autenticato** — l'OTP potrebbe essere scaduto o il wizard di configurazione non è stato completato: ripeti il login OTP. - **Serve più di una chiave** (es. ambienti separati) — da `Account > API` puoi generare altre `license_key` collegate allo stesso account. - **La chiave smette di funzionare** — verifica che non sia stata rigenerata/revocata da `Account > API`; ogni `license_key` va trattata come credenziale segreta. ## Configurazione correlata Vedi [api/overview](../../api/overview.md) per base URL, header di autenticazione e primi passi con l'API. --- ## Source: https://docs.popapi.io/it/guides/getting-started/minimum-requirements ## Obiettivo Verificare che il tuo ambiente WordPress soddisfi i requisiti minimi prima di installare POP. ## Requisiti dichiarati dal plugin | Componente | Minimo richiesto | Versione testata | | --- | --- | --- | | PHP | 7.4 | — | | WordPress | 4.6 | 7.0 | | WooCommerce | 4.0 | 9.x | Questi valori sono quelli dichiarati nel pacchetto del plugin (header e `readme.txt`). L'HPOS (High-Performance Order Storage) di WooCommerce è supportato a partire da WooCommerce 9.x. Per usare in modo affidabile tutte le funzionalità correnti (wizard di configurazione, tab Integrazioni, generazione XML/PDF via API cloud) ti consigliamo comunque un ambiente aggiornato — WordPress 6.x e WooCommerce 9.x o superiori — coerente con quanto già richiesto dal tuo hosting per motivi di sicurezza. ## Come vedere le versioni installate - **WordPress**: `wp-admin > Info su WordPress` (o in fondo a qualsiasi schermata di `wp-admin`). - **WooCommerce**: `WooCommerce > Stato` (tab "Stato"), sezione "WordPress environment". - **PHP**: nella stessa schermata `WooCommerce > Stato`, sezione "Server environment". ## Verifica Se le versioni installate sono pari o superiori ai minimi in tabella, puoi procedere con [first-installation](first-installation.md). ## Errori comuni - **Il plugin non appare tra quelli attivabili / errore fatale all'attivazione** — verifica la versione PHP: ambienti molto datati (PHP < 7.4) possono avere un comportamento diverso in alcune aree del plugin che dipendono da funzionalità di autoloading più recenti. - **Alcune impostazioni non compaiono (tab Integrazioni, wizard)** — assicurati che WooCommerce sia attivo e aggiornato: il plugin registra i suoi hook rispetto a WooCommerce all'`init`. - **Prima di aggiornare WordPress/WooCommerce a una major** — testa in un ambiente di staging: vedi [update-plugin](../configuration/update-plugin.md) per la procedura di aggiornamento del solo plugin POP. ## Configurazione correlata Per il primo avvio dopo l'installazione vedi [first-installation](first-installation.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/onboard-via-ai-assistant ## Obiettivo Creare un nuovo account POP e attivare SdI (Italia/San Marino) o PEPPOL (resto UE) interamente in chat con un assistente AI collegato al [server MCP remoto](../integrations/mcp-remote.md) — senza aprire popapi.io né compilare form. ## Prerequisiti - Un client MCP collegato a `https://mcp.popapi.io/mcp` (vedi [mcp-remote](../integrations/mcp-remote.md)) — per questo flusso **non serve ancora una `license_key`**, quindi puoi collegarti anche senza account. - Un indirizzo email valido, raggiungibile. ## Il flusso (5 passi) L'assistente userà, in ordine, questi 5 strumenti: 1. **`pop_onboarding_request_otp`** — chiedi all'assistente di avviare la registrazione con la tua email. Se l'account non esiste, viene creato automaticamente. Il codice OTP arriva anche via email, ma l'assistente lo riceve già nella risposta. 2. **`pop_onboarding_verify_otp`** — dai all'assistente il codice OTP (scade in 10 minuti): in cambio ottieni un `onboarding_token` temporaneo (valido 30 minuti), che l'assistente userà per te nei passi successivi. 3. **`pop_onboarding_get_status`** *(opzionale)* — per controllare a che punto sei prima di procedere. 4. **`pop_onboarding_get_account_setup`** — l'assistente recupera i campi ancora da compilare (paese, ragione sociale, partita IVA, regime fiscale, ecc.) e i valori ammessi (es. elenco regimi fiscali per il tuo paese). 5. **`pop_onboarding_save_account_setup`** — fornisci i dati mancanti (in linguaggio naturale, li traduce l'assistente); a questo punto puoi anche chiedere di attivare SdI o PEPPOL nella stessa richiesta. ## Attivare SdI o PEPPOL nello stesso flusso - **SdI** (solo account IT/SM) — chiedi di attivarlo: l'assistente imposta `active_sdipop_integration = 1` e `active_peppol_integration = 0`. - **PEPPOL** (altri paesi UE) — chiedi di registrare la legal entity PEPPOL: servono indirizzo, città, CAP e lo schema/identificativo PEPPOL: l'assistente li recupera dai lookup del passo 4 se non li sai a memoria. - SdI e PEPPOL sono **mutuamente esclusivi**: non puoi attivarli entrambi sullo stesso account. ## Dopo l'attivazione Una volta completato il wizard, recupera la tua `license_key` da `Account > API` su popapi.io (vedi [get-your-license-key](get-your-license-key.md)) per iniziare a generare fatture — quella è la chiave che userai per autenticare le chiamate "normali" (creazione fatture), diversa dall'`onboarding_token` usato solo durante questo flusso. ## Da sapere - Nessuno dei 5 strumenti di onboarding richiede l'header `Authorization: Bearer` — usano solo `onboarding_token` (o niente, nel primo passo). - Se hai un account amministratore, non ricevi un OTP: usa la tua password admin come "OTP" al passo 2. - Una volta che `wizard_completed` è vero, richiamare di nuovo il salvataggio non sovrascrive nulla: torna solo lo stato attuale. - I campi PEPPOL, una volta registrata la legal entity, restano bloccati permanentemente (non modificabili in autonomia). ## Errori comuni - **OTP scaduto** — hai aspettato più di 10 minuti tra richiesta e verifica: ripeti dal passo 1. - **`onboarding_token` scaduto** — è passata più di mezz'ora dal passo 2: non esiste un refresh, si riparte dalla richiesta OTP. - **Partita IVA già in uso** — errore 422 durante il salvataggio: quella partita IVA è già associata a un altro account sull'ambiente scelto (live/sandbox). - **Campo bloccato non modificabile** — alcuni campi restano fissi dopo il primo salvataggio (es. paese, o tutti i campi PEPPOL dopo la registrazione): va aperto un ticket di supporto per cambiarli. ## Configurazione correlata Per il dettaglio tecnico del protocollo sottostante (stesso flusso, chiamate REST dirette) vedi [api/onboarding](../../api/onboarding.md). Per collegare l'assistente vedi [mcp-remote](../integrations/mcp-remote.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/shopify-faq ## Obiettivo Orientarsi rapidamente su cosa fa (e non fa) POP for Shopify prima di approfondire le singole guide di configurazione. ## Prima di iniziare **POP calcola le imposte del checkout?** No. Shopify resta l'unico responsabile del calcolo e applicazione delle imposte. POP usa i dati fiscali presenti in Shopify per generare e inviare documenti (PDF/XML, SdI/PEPPOL/KSeF). **Dove configuro IVA, OSS, mercati e regole fiscali?** Sempre in Shopify Admin (Markets, Tax regions). Per il B2B, verifica i dati fiscali su Company/Company Location dove applicabile. ## Dati fiscali cliente **Da dove prende i dati fiscali POP?** Da metafield ordine/cliente `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), con fallback ai customAttributes dell'ordine. Dettagli e priorità in [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **I metafield vengono creati automaticamente?** Sì, dopo il completamento di wizard e licenza POP prova a creare le definizioni mancanti in modo idempotente. Se qualcosa manca, la Home mostra una sezione di recovery con un pulsante di ricreazione manuale. ## Shopify Plus vs non-Plus **Qual è la differenza nella raccolta dati fiscali in checkout?** Su Shopify Plus è disponibile la Checkout UI Extension nativa POP. Sugli store non-Plus i campi si aggiungono su carrello/cart drawer tramite uno script da incollare nel tema — vedi [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **POP supporta scenari B2B e B2C?** Sì, entrambi; la correttezza fiscale del documento dipende comunque dalla qualità dei dati raccolti in Shopify. ## Italia, SdI e PEPPOL **I campi Codice Fiscale/PEC nativi di Shopify si possono rimuovere dal checkout?** No, Shopify li applica nativamente per l'Italia e non possono essere rimossi né modificati da POP. Sono comunque opzionali; per disattivarli serve una richiesta al supporto Shopify. **Posso inviare a SdI con store in valuta diversa da EUR?** No. I flussi SdI richiedono che la valuta principale dello store Shopify sia EUR. **PEPPOL è disponibile per clienti privati?** No. L'invio automatico a PEPPOL salta sempre i clienti privati (B2C); resta disponibile il download del PDF come documento di cortesia. Dettagli in [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **POP valida la Partita IVA?** Sì, tramite il servizio ufficiale VIES. La decisione fiscale finale su applicazione IVA resta comunque alla configurazione Shopify. ## Piani e limiti **Quanti documenti posso generare al mese?** Dipende dal piano attivo: Free 20/mese, Basic 40/mese, Growth 100/mese, Pro 400/mese, Enterprise 2000/mese. Superato il limite, la generazione mostra un avviso con link per fare l'upgrade. ## Troubleshooting rapido **Non vedo tutti i campi fiscali sull'ordine/cliente:** 1. Verifica che wizard e licenza POP siano completati. 2. Verifica che i metafield `pop_*` risultino creati (altrimenti usa il pulsante di ricreazione in Home). 3. Verifica la configurazione checkout/tema. 4. Verifica Markets/Tax in Shopify Admin. **Le imposte in fattura non corrispondono alle attese:** 1. Verifica le regole fiscali Shopify. 2. Verifica tipo cliente e dati fiscali salvati. 3. Verifica un'eventuale validazione VAT fallita. 4. Verifica il canale di invio (SdI/PEPPOL/KSeF) e i vincoli specifici di quel canale. ## Configurazione correlata Per approfondire, parti da [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) e [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/what-the-plugin-does ## Obiettivo Capire, prima di installarlo, cosa fa concretamente il plugin POP quando lo attivi su un negozio WooCommerce. ## Cosa configura POP Una volta attivo, POP si integra con WooCommerce e aggiunge automaticamente: 1. **Campi di fatturazione al checkout e in "Il mio account"** — tipo cliente (Privato / Azienda / Libero professionista), numero di P.IVA, codice fiscale, e un campo per PEC oppure codice destinatario SDI a 7 caratteri. Ognuno di questi campi è obbligatorio o opzionale a seconda del paese del cliente e del tipo cliente selezionato, e viene validato con un controllo di formato. 2. **Generazione automatica del documento XML** per ogni ordine che entra in stato "in lavorazione" o "completato" — vedi [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). 3. **Un pannello impostazioni dedicato** — `POP → Electronic Invoice - Settings` in `wp-admin`, con tab separate per dati aziendali, checkout, numerazione, documenti, opzioni avanzate e integrazioni. ## Cosa NON include di base - **Firma digitale e invio allo SDI** non sono automatici con la sola installazione: richiedono di scegliere un canale di trasmissione (SdI via POP, PEPPOL, KSeF, oppure un add-on come Fatture in Cloud, Aruba o SdI via PEC) — vedi [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). - **La compatibilità con checkout personalizzati** non è garantita: se il flusso ordine/checkout viene alterato da un altro plugin o da codice custom, POP potrebbe non riuscire a leggere correttamente i campi di fatturazione. ## Verifica Dopo l'attivazione, apri `POP → Electronic Invoice - Settings`: se vedi le tab General, Checkout, Numeration, Documents, Advanced, Invoices e Integrations, il plugin è installato e funzionante. ## Errori comuni - **I campi di fatturazione non compaiono al checkout** — verifica che WooCommerce sia attivo: senza WooCommerce, POP non aggiunge alcun campo. - **Un plugin di personalizzazione checkout nasconde i campi POP** — la compatibilità con logiche di checkout di terze parti non è garantita: disattiva temporaneamente l'altro plugin per isolare il problema. ## Configurazione correlata Per i passi di installazione e primo avvio vedi [first-installation](first-installation.md); per il contratto dei campi vedi [checkout-field-names](../configuration/checkout-field-names.md). --- ## Source: https://docs.popapi.io/it/guides/getting-started/xml-invoices-generated ## Obiettivo Capire cosa produce POP quando genera una fattura XML per un ordine, e cosa manca per poterla inviare allo SDI senza un canale di trasmissione attivo. ## Cosa genera il plugin Per ogni ordine completato, POP crea un file **XML FatturaPA** (formato `FPR12` di default, il formato standard per le fatture verso privati; il formato cambia se il documento è indirizzato a un destinatario business). Puoi scaricare i file singolarmente dalla tab **Invoices**, oppure selezionarne più di uno ed esportarli in blocco come archivio `.zip`. ## Cosa NON fa da solo - **Il file XML generato dal solo plugin non è firmato digitalmente.** La firma digitale, se richiesta dal canale di invio scelto, viene applicata dal canale stesso (es. SdI via POP), non dalla generazione XML di base. - **Il file non viene trasmesso automaticamente allo SDI** a meno di attivare uno dei canali di invio (SdI via POP, PEPPOL, KSeF, oppure un add-on come Fatture in Cloud, Aruba o SdI via PEC) — vedi [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md). Se non attivi nessun canale, resta comunque possibile scaricare l'XML e trasmetterlo tu stesso (es. via PEC firmandolo con uno strumento esterno, secondo le indicazioni dell'Agenzia delle Entrate). ## Verifica Dopo che un ordine passa in lavorazione o completato, in `POP → Electronic Invoice - Settings > Invoices` dovresti vedere il documento XML associato all'ordine, scaricabile. ## Errori comuni - **L'XML scaricato non viene accettato da un intermediario/software esterno perché "non firmato"** — atteso: la generazione XML di base non include la firma; serve firmarlo esternamente o attivare un canale di invio che gestisca la firma. - **Manca l'XML per un ordine** — controlla lo stato dell'ordine: la generazione avviene al passaggio a "in lavorazione" o "completato", vedi [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). - **Serve capire dove sono salvati fisicamente i file XML/PDF sul server** — vedi [generated-files-storage](../configuration/generated-files-storage.md). ## Configurazione correlata Per scegliere un canale che invii l'XML automaticamente allo SDI/PEPPOL/KSeF vedi [choosing-an-invoicing-integration](choosing-an-invoicing-integration.md); per il contratto del payload XML lato API vedi [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/aruba-connect ## Obiettivo Collegare WooCommerce al servizio di fatturazione elettronica Aruba e attivare l'invio automatico delle fatture dopo il completamento di un ordine. ## Prerequisiti - Addon **Aruba** installato e attivo. - Un **account di fatturazione Aruba Premium**, oppure un account base collegato a un account Premium tramite delega — è un requisito dell'account Aruba, non una verifica fatta dal plugin. - Solo **una** integrazione di invio fatture può essere attiva alla volta: se Fatture in Cloud o SDI via PEC sono già attivi, disattivali prima di collegare Aruba. ## Passi ### 1. Collega l'account Nella scheda **Aruba** del plugin, inserisci utente e password del tuo account di fatturazione Aruba nell'apposito pannello di login. Non serve altro: il plugin autentica direttamente con quelle credenziali. ### 2. Configura l'invio automatico 1. **Stato ordine che attiva l'invio** — per default "Completato", ma configurabile su un altro stato ordine WooCommerce. 2. **Abilita l'invio automatico delle fatture** — quando un ordine raggiunge lo stato configurato, viene schedulato un evento che parte dopo un ritardo impostabile in ore (default **12 ore**): la fattura viene inviata ad Aruba, che dopo i propri controlli la inoltra allo SDI. 3. In caso di fattura non valida l'invio si blocca e va completato manualmente dopo aver corretto gli errori. ### Affidabilità di WP-Cron Gli eventi di invio automatico sono gestiti da **WP-Cron**, che si attiva solo quando qualcuno apre una pagina del sito: su siti con poco traffico gli invii possono ritardare. Aggiungi un Cron di sistema che richiami periodicamente (es. ogni 30 minuti): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` dove `` è la root del dominio. ### Log diagnostico Per tracciare scheduling ed esecuzione degli invii, aggiungi in `wp-config.php`: ``` define("WP_FATT_ARUBA_LOG", true); ``` ## Verifica Con il log attivo, genera un ordine di prova e verifica nel file di log che l'invio sia stato schedulato ed eseguito; controlla poi che il documento compaia sul portale Aruba. ## Errori comuni - **Il login non funziona pur con credenziali corrette** — verifica che l'account sia effettivamente Premium o correttamente delegato: un account base non delegato non è abilitato all'invio via API. - **L'invio automatico non parte** — quasi sempre WP-Cron non si attiva per mancanza di traffico: aggiungi il Cron di sistema descritto sopra. - **La fattura resta bloccata dopo l'invio ad Aruba** — Aruba l'ha segnata come non valida in fase di controllo: correggi i dati e reinvia manualmente una volta risolti gli errori. ## Configurazione correlata Per il ciclo di consegna allo SDI e la logica delle email di notifica, vedi [aruba-invoice-flow](aruba-invoice-flow.md). Per il contratto dei dati fattura, vedi [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/aruba-invoice-flow ## Sintomo Dopo l'invio di una fattura ad Aruba non è chiaro cosa succede in background, o il cliente riceve (o non riceve) l'email con la fattura pro forma. ## Causa ### Il ciclo attivo lato Aruba Una volta inviata la fattura ad Aruba, il "ciclo attivo" segue questi passaggi (gestiti da Aruba, non dal plugin): 1. Il documento XML viene inviato via web service ai canali Aruba. 2. Aruba PEC controlla la conformità formale del formato. 3. Aruba PEC appone la firma elettronica (qualificata, facoltativa per B2B/B2C) e la trasmette allo SDI. 4. Lo SDI valida la fattura e la inoltra al destinatario (via codice destinatario o PEC), oppure a un soggetto terzo delegato dal destinatario. 5. Lo SDI restituisce ad Aruba una notifica di scarto, mancata consegna o consegna. 6. Il documento passa in conservazione digitale a norma (obbligatoria). Per il significato dettagliato dei singoli codici di notifica, fai riferimento alla documentazione Aruba. ### Quando parte l'email con la fattura pro forma Allo scadere del tempo impostato per il controllo delle notifiche, il plugin verifica lo stato ricevuto da Aruba e invia automaticamente al cliente l'email con la fattura pro forma **solo** se si verifica una di queste condizioni: - stato **RC (Consegnata)** — la fattura è stata consegnata dallo SDI; oppure - stato **MC (Non Consegnata)**, ma **solo per clienti "privati"**; oppure - stato **RC o MC** quando il destinatario ha una PEC/indirizzo email valido oppure il codice destinatario SDI è impostato a `0000000`. Fuori da questi casi (es. cliente business con codice destinatario specifico e stato diverso da RC/MC) l'email pro forma automatica non parte: non è un errore, è il comportamento previsto. ## Fix - Per inviare comunque la pro forma in un caso non coperto dalle condizioni sopra, usa il bottone manuale **"Pro Forma"** sull'ordine/fattura. - Se un ordine resta a lungo senza notifica RC/MC, verifica lo stato direttamente sul portale Aruba: il plugin si limita a interrogare le notifiche già disponibili, non forza una nuova trasmissione. ## Configurazione correlata Per collegare l'account e configurare l'invio automatico, vedi [aruba-connect](aruba-connect.md). Per capire un rifiuto SDI, vedi [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-auto-send ## Obiettivo Attivare l'invio automatico delle fatture a Fatture in Cloud dopo il completamento di un ordine, e verificare il flusso con un ordine di prova prima di affidarti all'automazione. ## Prerequisiti - [Connessione Fatture in Cloud](fatture-in-cloud-connect.md) già attiva. ## Passi ### Configurare l'invio automatico Nella scheda **Fatture in Cloud**: 1. **Stato ordine che attiva l'invio** — per default è "Completato", ma è configurabile su un altro stato ordine WooCommerce. 2. **Abilita l'invio automatico delle fatture** — quando un ordine raggiunge lo stato configurato, viene schedulato un evento che parte dopo un ritardo impostabile in ore (default **12 ore**). 3. Alla scadenza del ritardo: la fattura viene caricata su Fatture in Cloud, poi ne viene verificata la validità formale; solo se valida viene inoltrata allo SDI. In caso di fattura non valida l'invio si blocca e va completato manualmente dopo aver corretto gli errori. 4. **Disabilita l'invio automatico delle fatture allo SDI** — se attivo, ferma il processo dopo il caricamento/verifica su Fatture in Cloud e non esegue l'inoltro automatico allo SDI (utile se vuoi che sia sempre Fatture in Cloud, non il plugin, a decidere quando inviare allo SDI). 5. **Notifica email in caso di mancata creazione** — c'è un'opzione dedicata per ricevere un'email se la creazione automatica della fattura fallisce. ### Affidabilità di WP-Cron Gli eventi di invio automatico sono gestiti da **WP-Cron**, che si attiva solo quando qualcuno apre una pagina del sito. Su siti con poco traffico gli invii possono ritardare o non partire. Per renderli puntuali, aggiungi un vero Cron di sistema (via hosting, VPS o server dedicato) che richiami periodicamente (es. ogni 30 minuti): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` dove `` è la root del dominio. ### Log diagnostico Per tracciare lo scheduling e l'esecuzione degli invii (inclusi gli stati ordine attraversati e il motivo per cui un invio automatico viene saltato), aggiungi in `wp-config.php`: ``` define("WP_FATT_CLOUD_LOG", true); ``` ## Generare un XML di prova Prima di affidarti all'automazione, verifica il flusso con un ordine di prova: 1. Assicurati che l'addon sia connesso (vedi [fatture-in-cloud-connect](fatture-in-cloud-connect.md)). 2. **Disattiva temporaneamente** sia "Abilita l'invio automatico delle fatture" sia "Disabilita l'invio automatico delle fatture allo SDI", così nessun invio parte da solo. 3. Fai un acquisto di prova e porta l'ordine allo stato configurato come trigger (default "Completato"). Vai nella sezione **Fatture** del plugin: troverai l'XML generato, scaricabile per controllarne la struttura. 4. Controllato l'XML, usa il bottone **"Carica"** sulla fattura per inviarla manualmente a Fatture in Cloud: dopo l'invio la vedrai comparire tra i documenti del tuo account. ## Verifica - Con il log attivo, il file registra la creazione, verifica e invio (o il motivo dello skip) per ogni ordine. - Il documento compare su Fatture in Cloud con lo stato di validità/invio coerente con quanto visto nel plugin. ## Errori comuni - **L'invio automatico non parte mai** — quasi sempre è WP-Cron che non si attiva per mancanza di traffico: aggiungi il Cron di sistema descritto sopra. - **La fattura resta bloccata dopo il caricamento** — la verifica formale su Fatture in Cloud l'ha segnata come non valida: correggi i dati dell'ordine/fattura e reinvia manualmente. - **Vuoi testare senza rischiare un invio reale** — segui la procedura "Generare un XML di prova" sopra: disattivando entrambe le opzioni di invio automatico nessun documento parte da solo finché non lo carichi tu manualmente. ## Configurazione correlata Per il contratto dei dati fattura (payload, mapping campi), vedi [api/sdi](../../api/sdi.md). Per capire un rifiuto SDI dopo l'inoltro, vedi [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-connect ## Obiettivo Collegare il tuo account Fatture in Cloud al plugin POP, scegliere quali documenti generare (fatture o ordini) e, opzionalmente, taggare i documenti con un centro di ricavo. ## Prerequisiti - Addon **Fatture in Cloud** installato e attivo. - Un account Fatture in Cloud con almeno: un conto saldo (es. "Conto standard") e i metodi di pagamento che usi in WooCommerce (bonifico, contrassegno, contanti, carta) già creati — sono prerequisiti dell'account Fatture in Cloud, non impostazioni del plugin. - Solo **una** integrazione di invio fatture può essere attiva alla volta (Fatture in Cloud, Aruba, SDI via PEC, SDI via POP...): se un'altra è già attiva, disattivala prima di connettere Fatture in Cloud. ## Passi Puoi collegare l'account Fatture in Cloud in due modi equivalenti: dal plugin WordPress (permette anche di scegliere i permessi granulari, vedi sotto) oppure direttamente dal pannello account su `popapi.io` (**Il mio account > Integrazioni > Fatture in Cloud > Connect**) — utile se non stai integrando via WordPress (es. API diretta). Entrambi i percorsi mostrano lo stesso popup di autorizzazione OAuth (codice + link). ### 1. Scegli i permessi e collega l'account (plugin WordPress) Nella scheda **Fatture in Cloud** del plugin, prima di connettere seleziona i permessi da concedere: - **Fatture** oppure **Ordini** — sono due permessi mutuamente esclusivi: selezionandone uno l'altro viene deselezionato automaticamente. Se scegli **Ordini**, il plugin creerà su Fatture in Cloud un documento della lista ordini invece di una fattura vera e propria. - **Note di credito**, **Ricevute**, **Anagrafica clienti** — permessi opzionali aggiuntivi. - **Magazzino** — necessario solo se userai la sincronizzazione stock (vedi [fatture-in-cloud-warehouse-sync](fatture-in-cloud-warehouse-sync.md)). Fai clic su **Connetti**: si apre un popup con un codice e un link di autorizzazione. Non chiudere il popup — apri il link, autorizza l'app su Fatture in Cloud inserendo il codice mostrato, poi torna al plugin: vedrai il messaggio **"Token di accesso riuscito!"**. ### 2. Imposta il centro di ricavo (opzionale) Se gestisci più attività o rami d'azienda, valorizza il campo **Centro di ricavo** (es. `e-commerce`): il valore viene aggiunto a ogni fattura/ordine creato su Fatture in Cloud per identificare la provenienza della vendita. Se lasci il campo vuoto, non viene inviato alcun dato di centro di ricavo. ## Verifica - Nella scheda Fatture in Cloud del plugin lo stato della connessione risulta attivo (token salvato). - Genera un ordine di prova (vedi [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md#generare-un-xml-di-prova)) e controlla che il documento compaia su Fatture in Cloud nel formato scelto (fattura o ordine). ## Errori comuni - **Il popup di autorizzazione si chiude senza completare la connessione** — non chiudere né ricaricare la pagina finché non compare "Token di accesso riuscito!": il codice mostrato scade se la procedura non viene completata in tempo. - **Vengono create fatture invece di ordini (o viceversa)** — i due permessi sono mutuamente esclusivi lato Fatture in Cloud: per cambiarli devi rifare la connessione scegliendo il permesso corretto, non basta un'impostazione separata dopo la connessione. - **Il centro di ricavo non compare sul documento** — verifica di aver salvato il campo nella scheda impostazioni: se è vuoto il dato semplicemente non viene inviato. ## Configurazione correlata Per il contratto dei dati fattura (payload, mapping campi), vedi [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-corrispettivi ## Obiettivo Generare un **corrispettivo** su Fatture in Cloud a partire da un ordine con documento di tipo **ricevuta**, usando l'add-on dedicato **POP to Fatture in Cloud (Corrispettivi)**. ## Prerequisiti - Add-on **POP to Fatture in Cloud** già collegato e funzionante (vedi [fatture-in-cloud-connect](fatture-in-cloud-connect.md)) — l'add-on Corrispettivi si aggiunge a quello base, non lo sostituisce e non funziona senza di esso. - Ordini configurati per generare documento di tipo **ricevuta** (non fattura). ## Passi 1. Installa e attiva l'add-on **POP to Fatture in Cloud (Corrispettivi)**. 2. Verifica che l'add-on base Fatture in Cloud sia già connesso e configurato correttamente. 3. Da questo momento, gli ordini con documento di tipo ricevuta generano un corrispettivo su Fatture in Cloud invece di una ricevuta POP standalone. ## Limite importante Fatture in Cloud, per sua natura, **non gestisce l'emissione di corrispettivi elettronici** (l'invio telematico all'Agenzia delle Entrate): il corrispettivo creato da questo add-on è un documento interno a Fatture in Cloud, utile per la contabilità, ma non sostituisce un obbligo di trasmissione telematica dei corrispettivi se la tua attività vi è soggetta. Verifica con il tuo commercialista se questo limite è rilevante per la tua situazione. ## Errori comuni - **Il corrispettivo non viene creato** — controlla prima che l'add-on base Fatture in Cloud sia connesso: senza quella connessione attiva, l'add-on Corrispettivi non ha nulla a cui appoggiarsi. - **Ti aspettavi un invio telematico automatico** — non è previsto: vedi il limite sopra. ## Configurazione correlata Per la connessione base e la mappatura dei metodi di pagamento, vedi [fatture-in-cloud-connect](fatture-in-cloud-connect.md) e [fatture-in-cloud-payment-methods](fatture-in-cloud-payment-methods.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-payment-methods ## Obiettivo Fare in modo che l'add-on POP per Fatture in Cloud generi documenti con il metodo di pagamento corretto, mappando i gateway attivi su WooCommerce ai metodi configurati su Fatture in Cloud. ## Prerequisiti - Add-on **POP to Fatture in Cloud** installato e attivo. - Un account Fatture in Cloud. ## Passi 1. **Collega l'account** — nella tab **Fatture in Cloud** di POP, clicca su **Connect**: si apre un popup con un codice e un link per autorizzare la connessione OAuth. Non chiudere il popup finché non vedi la conferma "Access Token successful!". 2. **Seleziona l'azienda** — dal menu a tendina **"Set the company to link"**, scegli l'azienda Fatture in Cloud da collegare (se il tuo account ne gestisce più di una). 3. **Crea un conto di saldo su Fatture in Cloud** — su Fatture in Cloud, vai in `Impostazioni > Conti di saldo` e crea un conto (es. "Conto standard"), se non esiste già. 4. **Crea i metodi di pagamento base su Fatture in Cloud** — in `Impostazioni > Metodi di pagamento`, crea almeno le voci base: Bonifico, Assegno, Contanti, Carta di pagamento (puoi consolidare Stripe/PayPal/altri gateway con carta sotto un'unica voce "Carta di pagamento", oppure crearne una per gateway). 5. **Configura i metodi di pagamento su WooCommerce** — assicurati che `WooCommerce > Impostazioni > Pagamenti` elenchi tutti i gateway realmente usati sul tuo store. 6. **Mappa i pagamenti nella tab Fatture in Cloud di POP** — imposta il conto di saldo globale, poi associa ogni gateway WooCommerce al metodo di pagamento Fatture in Cloud corrispondente. ## Verifica Genera un documento di prova dall'add-on per un ordine con un gateway specifico: il documento su Fatture in Cloud deve riportare il metodo di pagamento mappato, non un valore generico o vuoto. ## Errori comuni - **"Payment account missing"** — non hai selezionato/creato il conto di saldo globale prima di mappare i metodi: torna al passo 3. - **Il documento generato ha il metodo di pagamento sbagliato** — controlla la mappatura gateway → metodo: ogni gateway WooCommerce deve puntare esplicitamente al metodo Fatture in Cloud corretto, non c'è un fallback automatico intelligente. - **Non riesci a completare la connessione OAuth** — non chiudere il popup prima del messaggio di conferma; se il codice scade, ripeti il passo 1. ## Configurazione correlata Per capire se Fatture in Cloud è il canale più adatto rispetto a SdI via POP, Aruba o PEPPOL, vedi [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-pdf-email ## Obiettivo Scegliere se allegare alle email dell'ordine il PDF fattura generato da Fatture in Cloud, oppure usare il PDF generato di default da POP. ## Prerequisiti - [Connessione Fatture in Cloud](fatture-in-cloud-connect.md) già attiva. ## Passi 1. Nella scheda **Fatture in Cloud** del plugin, individua l'opzione **"Usa il PDF di Fatture in Cloud"**. 2. **Attivata** — il PDF allegato sia all'email manuale "Fattura" (azione disponibile sull'ordine) sia all'email automatica di fattura inviata dopo la consegna allo SDI (se l'invio SDI è attivo) è quello generato da Fatture in Cloud, recuperato dal documento già caricato sul loro sistema. 3. **Disattivata** — viene usato il PDF generato internamente da POP, senza dipendere da Fatture in Cloud. ## Comportamento quando il documento non esiste ancora Con l'opzione **attivata**, se un ordine passa allo stato "completato" ma la fattura non è ancora stata caricata su Fatture in Cloud (es. invio automatico non ancora eseguito, vedi [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md)), l'email cliente **non viene inviata affatto** — non ripiega sul PDF di POP, resta semplicemente in attesa che il documento Fatture in Cloud esista. Una volta che il documento è presente, l'invio riprende regolarmente con il PDF corretto allegato. ## Verifica Invia manualmente l'email "Fattura" da un ordine con documento già caricato su Fatture in Cloud e controlla l'allegato: con l'opzione attiva deve avere l'impaginazione di Fatture in Cloud, non quella standard di POP. ## Errori comuni - **L'email cliente non parte per niente** — con l'opzione attiva questo è atteso finché il documento non è stato caricato su Fatture in Cloud: verifica lo stato dell'invio automatico o carica manualmente la fattura (vedi [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md)) prima di aspettarti l'email. - **L'allegato resta quello di POP anche con l'opzione attivata** — il PDF di Fatture in Cloud esiste solo dopo che il documento è stato caricato sul loro sistema: se manca l'URL del PDF nei metadati dell'ordine, il plugin non ha nulla da recuperare. ## Configurazione correlata Per l'invio automatico e la generazione del documento, vedi [fatture-in-cloud-auto-send](fatture-in-cloud-auto-send.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/fatture-in-cloud-warehouse-sync ## Obiettivo Collegare i prodotti WooCommerce a quelli di Fatture in Cloud e mantenere sincronizzato lo stock tra i due sistemi. ## Prerequisiti - Addon **Fatture in Cloud (Gestione Magazzino)** — funziona solo insieme all'[integrazione Fatture in Cloud](fatture-in-cloud-connect.md) di base. - Durante la connessione a Fatture in Cloud devi aver concesso anche il permesso **Magazzino** (scope di scrittura sullo stock): senza questo permesso il pulsante di scaricamento prodotti non compare. ## Passi ### 1. Scarica/aggiorna i prodotti Nella scheda dell'addon, usa il bottone **"Scarica/Aggiorna prodotti"** per importare l'elenco prodotti da Fatture in Cloud (viene mostrata anche la data dell'ultimo aggiornamento). ### 2. Associa i prodotti Puoi collegare ogni prodotto WooCommerce a un prodotto Fatture in Cloud in due modi equivalenti: - dal selettore **"Associa il prodotto"** nella scheda prodotto WooCommerce (semplice o variazione); - inserendo nel campo **COD** (SKU) del prodotto WooCommerce lo stesso codice del prodotto su Fatture in Cloud — l'abbinamento avviene automaticamente per corrispondenza di codice, senza bisogno del selettore. ## Cosa sincronizza - Ogni volta che aggiorni lo stock di un prodotto WooCommerce (semplice o variazione), lo stock del prodotto collegato su Fatture in Cloud viene aggiornato di conseguenza. - Quando un prodotto rientra in stock dopo un rimborso, la sincronizzazione riparte. - Quando viene caricata una fattura, per ogni riga prodotto presente nel documento lo stock su Fatture in Cloud viene allineato a quello WooCommerce. ## Verifica - Dopo aver aggiornato lo stock di un prodotto collegato, controlla la quantità sulla relativa scheda prodotto in Fatture in Cloud: deve riflettere il nuovo valore. ## Errori comuni - **Il bottone "Scarica/Aggiorna prodotti" non compare** — l'account Fatture in Cloud connesso non ha il permesso di scrittura sul magazzino: rifai la connessione includendo lo scope Magazzino. - **Il prodotto non si sincronizza** — non è associato a nessun prodotto Fatture in Cloud: verifica il selettore "Associa il prodotto" oppure che il campo COD combaci esattamente con il codice su Fatture in Cloud. - **Lo stock non si aggiorna sulle variazioni** — l'associazione va fatta per singola variazione (SKU o selettore), non basta averla fatta sul prodotto padre. ## Configurazione correlata Per la configurazione base della connessione, vedi [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/france-peppol ## Obiettivo Capire cosa serve per fatturare elettronicamente in Francia con POP e cosa aspettarsi dall'attivazione. ## Cosa serve - Nessun piano minimo: l'attivazione e l'invio sono disponibili su ogni piano, incluso Free, a consumo di crediti. - Paese account impostato su Francia. - Una partita IVA francese valida, oppure (se non ne hai una) il tuo numero **SIREN** (9 cifre) o **SIRET** (14 cifre). ## Come funziona POP invia le tue fatture al corridoio ufficiale francese (**gov-fr**), gestito tramite il nostro partner di compliance: non è lo stesso circuito PEPPOL generico usato per altri paesi europei, ma per te non cambia nulla nel modo in cui generi le fatture. Non devi cercare o inserire manualmente il tuo SIREN nella maggior parte dei casi: POP lo ricava automaticamente dalla tua partita IVA francese (le ultime 9 cifre). POP verifica anche che la partita IVA inserita sia corretta rispetto al SIREN che contiene, così eventuali errori di battitura vengono segnalati subito invece di causare problemi in un secondo momento. Dopo l'attivazione dovrai completare una verifica d'identità (KYC) su una pagina gestita direttamente dal nostro partner di compliance, non dal pannello POP: un passaggio diverso da quello usato per KSeF (Polonia), dove invece la firma avviene interamente nel pannello account. ## Passi 1. Nel wizard di configurazione guidata (o nel pannello account, per un account già esistente con paese Francia), conferma il tuo numero **SIREN**: nella maggior parte dei casi è già precompilato, derivato automaticamente dalla tua partita IVA. 2. Salva: POP registra automaticamente la tua Legal Entity francese. 3. Completa la verifica d'identità (KYC) sulla pagina esterna del nostro partner di compliance. ## Stato attuale Il corridoio Francia è **in beta**: copre la generazione e l'invio delle fatture (e-invoicing). Il secondo obbligo francese, l'**e-reporting** (per operazioni fuori dal perimetro B2B interno), non è ancora coperto. ## Errori comuni - **"France Legal Entity is missing."**: l'attivazione non è ancora completa, verifica che l'account abbia una partita IVA francese valida o un SIREN registrato. - **"France integration is not active."**: la registrazione esiste ma l'integrazione non è ancora attiva sull'account. - **La partita IVA viene rifiutata**: le cifre di controllo non corrispondono al SIREN contenuto, verifica di aver inserito il numero corretto. ## Configurazione correlata Per i dettagli tecnici del contratto API, vedi [api/peppol](../../api/peppol.md). Per scegliere tra i canali di fatturazione disponibili, vedi [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/ksef ## Obiettivo Collegare il tuo account POP al sistema KSeF (Polonia) per inviare fatture elettroniche FA(3). ## Prerequisiti - Su WordPress: nessun piano minimo, l'attivazione e l'invio sono disponibili su ogni piano (incluso Free), a consumo di crediti. Su Shopify serve invece il piano **Basic o superiore**. - **NIP** (partita IVA polacca) impostato nei dati dell'account. - **Ambiente live**: accesso a `podpis.gov.pl` con Profil Zaufany, oppure un certificato PKI KSeF (`PKCS#12` o `PEM`). - **Ambiente sandbox**: nessun prerequisito, la firma viene simulata automaticamente. Live e sandbox sono registrazioni **separate**: attivare il sandbox non attiva automaticamente il live, e viceversa. ## Passi (pannello account) 1. **Registra la legal entity**: indirizzo, città, CAP, email di notifica. NIP e ragione sociale vengono letti automaticamente dalle impostazioni account, non vanno reinseriti. 2. **Autorizza l'accesso**: - **Sandbox**: clicca "Avvia autorizzazione" (finestra di 10 minuti), poi "Attiva". - **Live con Profil Zaufany**: scarica il file di firma, firmalo su `podpis.gov.pl`, carica l'XML firmato, poi "Attiva". - **Live con certificato PKI**: carica nome certificato, passphrase e file del certificato. 3. **Connessione attiva**: da questo momento puoi inviare fatture KSeF tramite l'API POP. Se accedi per la prima volta con un account polacco (`PL`), l'attivazione può avvenire anche dal wizard di configurazione guidata, con gli stessi due passi (registrazione + autorizzazione). ## Costo in crediti Ogni documento KSeF consuma **1 credito**, solo per la consegna: la generazione locale dell'XML non consuma mai un credito. ## Disconnessione - **Disconnetti**: sospende l'invio mantenendo la registrazione (puoi riattivare in seguito). - **Elimina connessione**: rimuove anche i dati locali della registrazione. ## Errori comuni - **"KSeF Legal Entity is missing"**: la legal entity non è stata registrata (Passo 1) prima di generare/inviare un documento, completa la registrazione nel pannello account. - **Onboarding KSeF non completato**: mancano NIP o dati account, verifica le impostazioni prima di procedere con l'autorizzazione. - **Sandbox attivo ma nessun invio reale avviene**: atteso, la sandbox non consegna realmente a KSeF, serve passare all'ambiente live per l'invio effettivo. ## Configurazione correlata Per i dettagli del contratto API (payload, mapping campi FA(3)), vedi [api/ksef](../../api/ksef.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/mcp ## Obiettivo Generare, inviare e verificare fatture SdI, PEPPOL, KSeF, ZUGFeRD e PDF, oltre a sincronizzare documenti verso Zoho, direttamente da un assistente AI (es. Claude Desktop) tramite il server MCP ufficiale (`@getpopapi/pop-mcp`), senza chiamare manualmente l'API REST. Questa guida copre l'installazione **locale** (Node.js, stdio). Se vuoi collegare il tuo assistente senza installare nulla, esiste anche un server MCP **remoto** già online — vedi [mcp-remote](mcp-remote.md). ## Prerequisiti - Node.js >= 18. - Una `license_key` POP valida (vedi [get-your-license-key](../getting-started/get-your-license-key.md)) — se non hai ancora un account, puoi ottenerla anche via flusso headless (vedi [api/onboarding](../../api/onboarding.md)), senza passare dal login via browser. - Per l'invio SdI/PEPPOL: integrazione attiva sull'account POP. Nessun piano minimo: l'invio è disponibile su ogni piano, incluso Free, a consumo di crediti. ## Installazione ```bash npm install -g @getpopapi/pop-mcp ``` In alternativa, da sorgente: clona il repository, `npm install`, `npm run build`, poi punta il client al file `dist/cli.js` generato. ## Configurazione La `license_key` va passata come variabile d'ambiente, mai come parametro nelle chiamate: ```bash export POP_API_KEY=la_tua_license_key ``` Opzionale, per usare l'ambiente sandbox: `export POP_ENVIRONMENT=staging`. ## Collegare Claude Desktop Aggiungi al file di configurazione (`~/Library/Application Support/Claude/claude_desktop_config.json` su macOS, equivalenti su Windows/Linux): ```json { "mcpServers": { "pop": { "command": "pop-mcp", "env": { "POP_API_KEY": "la_tua_license_key" } } } } ``` ## Strumenti disponibili (11) - **Creazione** — `pop_create_sdi_invoice` (XML FatturaPA, invio opzionale via SdI), `pop_create_peppol_invoice` (UBL 2.1, invio opzionale via PEPPOL), `pop_create_ksef_invoice` (FA(3) XML polacco, invio opzionale via KSeF), `pop_create_zugferd_invoice` (bundle PDF/XML/PDF ibrido), `pop_create_pdf_invoice` (PDF con invio email opzionale, fino a 3 destinatari). - **Sincronizzazione Zoho** — `pop_sync_zoho_document`: sincronizza fattura o nota di credito verso Zoho Books/Invoice tramite il connector nativo dell'account; per default verifica prima che il connector Zoho sia attivo e connesso (`GET /integration/zoho/status`), fallendo con un errore chiaro se non lo è, invece di lasciar fallire la sincronizzazione lato Zoho. - **Stato e recupero** — `pop_get_invoice_status` (notifiche SdI), `pop_get_peppol_document`, `pop_get_sdi_document`. - **Validazione e conservazione** — `pop_verify_sdi_document`, `pop_preserve_document` (conservazione sostitutiva). Nessuno di questi richiede più un piano minimo. Ogni strumento richiama le stesse route REST già documentate in [api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md) e [api/zoho](../../api/zoho.md) — il server MCP non introduce un contratto API diverso, traduce solo le richieste dell'assistente in chiamate HTTP verso POP. ## Verifica Chiedi all'assistente qualcosa come *"Crea una fattura FatturaPA da 1000€ + IVA 22% per Rossi SRL (P.IVA IT12345678901)"*: se la configurazione è corretta, il tool restituisce l'XML generato (o un errore leggibile, con causa e campo coinvolto). ## Errori comuni - **`unauthorized_user`** — `POP_API_KEY` mancante o non valida: verificala da `Account > API` su popapi.io. - **`integration_inactive`** — SdI o PEPPOL non è attivo sull'account: completa l'attivazione prima di usare `submit_to_sdi`/`submit_to_peppol`. - **`pop_api_email_limit`** — più di 3 destinatari email su `pop_create_pdf_invoice`: riduci a un massimo di 3. - **`pop_preserve_document` chiamato nel momento sbagliato** — va usato solo dopo che `pop_get_invoice_status` restituisce stato `RC` (Ricevuta di Consegna) o `MC` (Mancata Consegna), non per gli altri stati. - **"Zoho integration is not active for this account"** — restituito da `pop_sync_zoho_document` prima ancora di chiamare Zoho, se il connector nativo non risulta attivo/connesso: completa l'attivazione dal pannello account POP (vedi [guides/integrations/zoho](zoho.md)). ## Configurazione correlata Per il contratto dati completo (struttura `data`, campi obbligatori per tipo documento), vedi [api/overview](../../api/overview.md) e le pagine specifiche per canale ([api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md), [api/zoho](../../api/zoho.md)). --- ## Source: https://docs.popapi.io/it/guides/integrations/mcp-remote ## Obiettivo Collegare un assistente AI (Claude, o qualunque client che parla MCP) al server MCP remoto ufficiale di POP (`https://mcp.popapi.io/mcp`), senza installare Node.js né configurare nulla in locale — a differenza della [versione locale](mcp.md), qui basta un URL. ## Prerequisiti - Una `license_key` POP valida (vedi [get-your-license-key](../getting-started/get-your-license-key.md)) — oppure, se non hai ancora un account, puoi crearne uno **conversando con l'assistente stesso**: vedi [onboard-via-ai-assistant](../getting-started/onboard-via-ai-assistant.md). - Un client che supporta MCP via HTTP: Claude (connector remoto), OpenAI Responses API, n8n, MCP Inspector, o un'integrazione custom. ## Come funziona - Endpoint: `https://mcp.popapi.io/mcp` — trasporto Streamable HTTP. - Il server è **stateless e multi-tenant**: non c'è una `license_key` configurata lato server come nella versione locale. Ogni singola richiesta deve portare la tua chiave come header: ``` Authorization: Bearer la_tua_license_key ``` - Se l'header manca o è malformato, la richiesta fallisce con `401` (`unauthorized_user`) **prima** di chiamare l'API POP. Se invece la chiave è presente ma non valida, la richiesta arriva a POP e restituisce l'errore che POP stesso genera (es. `unauthorized_user`, `insufficient_level`). ## Collegare Claude Aggiungi un nuovo connector remoto puntato a `https://mcp.popapi.io/mcp`, con header `Authorization: Bearer la_tua_license_key` — la procedura esatta dipende dalla versione di Claude che usi (desktop o web): cerca "connector" o "MCP remoto" nelle impostazioni. ## Provare con MCP Inspector ```bash npx @modelcontextprotocol/inspector ``` Configuralo per puntare a `https://mcp.popapi.io/mcp`, con lo stesso header `Authorization: Bearer`. ## Provare con curl ```bash curl -X POST https://mcp.popapi.io/mcp \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -H "Authorization: Bearer la_tua_license_key" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Strumenti disponibili (16) Gli stessi 11 strumenti della [versione locale](mcp.md) (creazione/invio SdI, PEPPOL, KSeF, ZUGFeRD, PDF, sincronizzazione Zoho, stato, verifica, conservazione), più **5 strumenti di onboarding** (`pop_onboarding_request_otp`, `pop_onboarding_verify_otp`, `pop_onboarding_get_status`, `pop_onboarding_get_account_setup`, `pop_onboarding_save_account_setup`) che **non richiedono l'header Bearer**: usano un proprio `onboarding_token` temporaneo, pensato apposta per creare un account da zero. Vedi [onboard-via-ai-assistant](../getting-started/onboard-via-ai-assistant.md) per il flusso completo. ## Da sapere - Il server gira come funzione serverless: è stateless, ogni richiesta è indipendente — non aspettarti che ricordi conversazioni precedenti al di fuori di quello che il client MCP stesso gestisce. - `https://mcp.popapi.io/health` è un endpoint di stato pensato per il monitoraggio, non per l'uso conversazionale. ## Errori comuni - **`401 unauthorized_user` immediato** — header `Authorization` assente o non nel formato `Bearer `: il server lo rifiuta prima ancora di contattare POP. - **Chiave presente ma richiesta rifiutata da POP** — la chiave è formalmente valida ma POP la rifiuta (piano insufficiente, integrazione non attiva): l'errore restituito è quello di POP, non del server MCP. - **Il client non trova il tool giusto** — verifica di aver connesso il client all'URL `/mcp` (non alla home page `https://mcp.popapi.io/`, che è solo la landing page informativa). ## Configurazione correlata Per l'installazione locale (stdio, via npm) vedi [mcp](mcp.md). Per il contratto dati completo delle fatture, vedi [api/overview](../../api/overview.md), [api/sdi](../../api/sdi.md), [api/peppol](../../api/peppol.md), [api/ksef](../../api/ksef.md), [api/zugferd](../../api/zugferd.md), [api/pdf](../../api/pdf.md) e [api/zoho](../../api/zoho.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/n8n ## Obiettivo Generare fatture SdI, PEPPOL, KSeF o ZUGFeRD, verificarne lo stato e validare partite IVA UE dentro un workflow n8n, senza chiamare manualmente l'API REST. ## Prerequisiti - Un'istanza n8n (cloud o self-hosted). - Una `license_key` POP valida (vedi [get-your-license-key](../getting-started/get-your-license-key.md)). ## Cosa offre il nodo POP Il nodo ufficiale (`n8n-nodes-pop`) espone due risorse: - **Invoice** — Create SdI Invoice (XML), Create Peppol Invoice (UBL), Create KSeF Invoice (FA(3) XML), Create ZUGFeRD Invoice, Get Invoice Status, Get Peppol Document, Verify SdI Document, **Sync Document to Zoho** (sincronizza una fattura o nota di credito su Zoho Books/Invoice tramite il connettore nativo POP — richiede che Zoho sia già collegato sull'account POP, nessun piano minimo; verifica opzionale dello stato del connettore prima dell'invio). - **VAT Validation** — Validate VAT Number, tramite il servizio VIES della UE (non l'API POP). Create KSeF Invoice condivide lo stesso form d'invio degli altri operatori di creazione fattura, più l'opzione **Submit via KSeF Provider** (Yes/No) per inviare subito il documento al provider KSeF invece di generare solo l'XML localmente — equivalente a impostare `integration.use = ksef-via-pop` sulla richiesta REST sottostante (vedi [api/ksef](../../api/ksef.md)). Create ZUGFeRD Invoice genera solo il pacchetto ZUGFeRD/Factur-X (nessuna opzione di invio: l'invio è sempre gestito da POP internamente, vedi [api/zugferd](../../api/zugferd.md)). Non copre PDF: per quel dominio usa l'API REST direttamente (vedi [api/pdf](../../api/pdf.md)). Per Zoho esistono due percorsi diversi, non equivalenti: **Sync Document to Zoho** qui sopra (usa il connettore Zoho già collegato sull'account POP, nessuna configurazione OAuth separata da fare in n8n) oppure il pacchetto dedicato [n8n-zoho](n8n-zoho.md) (self-hosted, credenziali Zoho OAuth configurate direttamente in n8n, instradamento tramite webhook firmato — installabile solo via npm, non è approvato/listato sul registro ufficiale dei Community Nodes di n8n). Scegli in base a dove vuoi che viva la connessione OAuth con Zoho. ## Passi 1. Installa il nodo ufficiale: . 2. Crea una credenziale **POP API** con la tua `license_key` (campo unico, inviato come header `X-API-Key`); n8n la verifica chiamando `GET /account-profile`. 3. Aggiungi il nodo POP, scegli risorsa e operazione (es. *Invoice → Create SdI Invoice*). 4. Scegli la modalità di input: **Passthrough** (usa il JSON in arrivo così com'è), **Form Fields** (compila i campi nel nodo), **JSON**, o **Raw**. 5. Se vuoi che POP invii subito il documento (non solo generarlo), attiva **Send Invoice**: aggiunge automaticamente l'integrazione `sdi-via-pop` o `peppol-via-pop` alla richiesta. ## Verifica Esegui il workflow una volta e controlla l'output del nodo: in caso di successo restituisce XML/JSON a seconda dell'operazione; in caso di errore, un `NodeApiError` con URL, status HTTP e corpo della risposta — utile per capire subito quale campo ha fallito la validazione. ## Errori comuni - **Nodo non autenticato** — la `license_key` nella credenziale non è valida o è stata rigenerata: aggiornala da `Account > API`. - **Campi mancanti nel payload mappato** — stessa validazione dell'API REST sottostante: controlla la guida della route specifica (es. [api/sdi](../../api/sdi.md)) per i campi richiesti. - **Sconto riga non applicato** — se abiliti "Discount" su una riga d'ordine, il campo "Discount Percent" è obbligatorio: senza di esso l'operazione fallisce in validazione. - **Validazione VIES lenta o fallita** — il nodo *Validate VAT* ritenta automaticamente fino a 5 volte sui guasti temporanei del servizio VIES (`MS_UNAVAILABLE`, `TIMEOUT`, ecc.); un fallimento persistente dopo i retry indica che il servizio VIES è irraggiungibile, non un problema di configurazione POP. - **Il workflow si interrompe su un singolo errore** — se vuoi che n8n continui con gli item successivi invece di fermare il workflow, abilita "Continue On Fail" sul nodo: l'errore viene allegato all'item in output invece di interrompere l'esecuzione. ## Configurazione correlata Per il percorso Zoho alternativo (self-hosted, OAuth configurato in n8n, solo installazione manuale via npm), vedi [n8n-zoho](n8n-zoho.md) (o [api/connectors](../../api/connectors.md) per il meccanismo di instradamento sottostante). Per i dettagli del connettore nativo usato da **Sync Document to Zoho**, vedi [zoho](zoho.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/n8n-zoho ## Obiettivo Creare automaticamente fatture (`TD01`) e note di credito (`TD04`) su **Zoho Invoice** o **Zoho Books** a partire dai documenti generati da POP, usando il pacchetto npm ufficiale [`n8n-nodes-pop-zoho`](https://www.npmjs.com/package/@getpopapi/n8n-nodes-pop-zoho) su una tua istanza n8n self-hosted. Questo è un pacchetto **diverso e distinto** da [`n8n-nodes-pop`](n8n.md) (che gestisce SdI/PEPPOL/VIES e, tramite l'operazione **Sync Document to Zoho**, anche una sincronizzazione Zoho nativa più semplice — vedi [n8n](n8n.md)) — installali entrambi solo se ti servono entrambe le funzionalità, o preferisci questo percorso se vuoi che la connessione OAuth con Zoho viva direttamente in n8n. **Nota sull'installazione**: il pacchetto è pubblicato su npm ma non è approvato/listato sul registro ufficiale dei Community Nodes di n8n — il pulsante **Settings → Community Nodes → Install** di n8n non lo troverà. Va installato manualmente (vedi sotto), e per questo **non è utilizzabile su n8n Cloud**, solo su un'istanza self-hosted. ## Prerequisiti - Un'istanza **n8n self-hosted** (v2+), Node.js 18+. Non disponibile su n8n Cloud (vedi nota sopra). - Un account **Zoho Invoice** o **Zoho Books**, con un'app OAuth2 creata sullo Zoho API Console della tua regione e le aliquote IVA configurate in Zoho (una voce per ogni percentuale usata nei payload POP). - Un account POP con il connector n8n abilitato e un webhook già registrato nel pannello **Webhooks**. ## Passi 1. Installazione manuale (l'installer "Community Nodes" di n8n non trova questo pacchetto): ```bash git clone https://github.com/getpopapi/n8n-nodes-pop-zoho.git cd n8n-nodes-pop-zoho npm install npm run build ln -s $(pwd)/dist/nodes/PopZohoInvoice/PopZohoInvoice.node.js ~/.n8n/custom/PopZohoInvoice.node.js ln -s $(pwd)/dist/credentials/ZohoInvoiceOAuth2Api.credentials.js ~/.n8n/custom/ZohoInvoiceOAuth2Api.credentials.js ln -s $(pwd)/dist/nodes/PopZohoInvoice/pop-zoho-invoice.svg ~/.n8n/custom/pop-zoho-invoice.svg n8n start ``` 2. Su [Zoho API Console](https://api-console.zoho.com), crea una **Server-based Application** con redirect URI `https:///rest/oauth2-credential/callback`. 3. In n8n, crea una credenziale **Zoho OAuth2 (Invoice / Books)**: prodotto, regione, Organization ID (da Zoho → Impostazioni → Profilo organizzazione), Client ID/Secret dall'app appena creata. Clicca **Connect** per completare l'autorizzazione. 4. Crea il workflow: **Webhook node** (Authentication: `None`, Respond: `Using 'Respond to Webhook' Node`, path `webhook/zoho`) → nodo **POP → Zoho** → **Respond to Webhook**. 5. Copia l'URL di produzione del Webhook node e registralo nel pannello **Webhooks** di POP, impostando il campo **Connector** su **"n8n Connector — Zoho"**. 6. Nel nodo POP → Zoho, imposta la **License Key** (sempre la chiave **di default** dell'account, da `popapi.io → Account → API → API Key (default)` — mai una chiave specifica per Shopify/WooCommerce) e clicca il pulsante di refresh per recuperare la **chiave pubblica RSA**. ## Verifica Invia una richiesta con `environment: "sandbox"` (o attiva **Dry Run** sul nodo): la risposta include `dry_run: true` e il corpo `zoho_body` che verrebbe inviato a Zoho, senza creare nulla realmente e senza consumare quota. ## Da sapere - Il campo **Invoice Status** del nodo controlla lo stato della fattura creata su Zoho: se impostato su **Sent**, il nodo esegue automaticamente anche la transizione di stato richiesta da Zoho dopo la creazione, invece di lasciare la fattura in `draft`. ## Errori comuni - **`auth_error`** — la License Key nel nodo non è quella di default: POP firma sempre con la chiave di default indipendentemente dalla piattaforma che ha generato il documento. - **`tax_not_found`** — una delle aliquote usate nei tuoi payload POP non è configurata in Zoho → Impostazioni → Tasse: aggiungila. - **`contact_ambiguous`** — più contatti Zoho corrispondono allo stesso VAT/email/nome: risolvi il duplicato in Zoho prima di riprovare. - **`unsupported_doc_type`** — solo `TD01` (fattura) e `TD04` (nota di credito) sono supportati in v1. ## Configurazione correlata Per il meccanismo di instradamento generico usato da questo nodo (route `/connector/zoho`, firma HMAC+RSA, codici errore lato POP), vedi [api/connectors](../../api/connectors.md). Per scegliere tra questo percorso e gli altri canali disponibili, vedi [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/paid-member-subscriptions ## Obiettivo Generare fatture elettroniche per gli abbonamenti venduti tramite **Paid Member Subscriptions** (di Cozmoslabs), usando POP come motore di fatturazione al posto (o in aggiunta) di WooCommerce. Non confonderla con [Paid Memberships Pro](paid-memberships-pro.md): sono due plugin di membership diversi, con nomi simili ma integrazioni POP separate. ## Prerequisiti - Plugin **Paid Member Subscriptions** (Cozmoslabs) installato e attivo sul sito. - Il modulo **"Tax & EU VAT"** di Paid Member Subscriptions attivo: senza di esso, POP non può mostrare i campi di fatturazione fiscale sui form di abbonamento né sulle pagine account — è un prerequisito specifico di questa integrazione, non richiesto per PMPro. - POP installato e il tuo canale di invio (SDI via POP, Fatture in Cloud, Aruba, SDI via PEC...) già configurato: l'integrazione non sostituisce il canale di invio, si aggiunge come fonte degli ordini da fatturare. ## Passi 1. Installa e attiva **POP** sul sito WordPress. 2. In Paid Member Subscriptions, verifica che il modulo **Tax & EU VAT** sia attivo — se non lo è, POP mostra un avviso esplicito sui form e sulle pagine di pagamento invece dei campi fiscali. 3. Vai su **POP > Integrazioni** e attiva la card **Paid Member Subscriptions**. Come per PMPro, non è mutuamente esclusiva con gli altri canali di invio: puoi tenerla attiva insieme a un normale negozio WooCommerce. 4. Una volta attiva, POP aggiunge ai form di abbonamento e alle pagine account gli stessi campi di fatturazione usati in WooCommerce (tipo cliente, codice SDI/PEC, codice fiscale/partita IVA), e userà quei dati per generare la fattura di ogni pagamento registrato. ## Verifica Dopo un pagamento di test su un piano di abbonamento, controlla che POP abbia generato il documento con i dati di fatturazione inseriti e con l'IVA correttamente calcolata. ## Errori comuni - **I campi di fatturazione non compaiono sul form di abbonamento** — la causa più comune è il modulo **Tax & EU VAT** non attivo in Paid Member Subscriptions: attivalo prima di controllare altro. - **Impossibile modificare i campi fiscali dal dettaglio pagamento in admin** — stessa causa: senza quel modulo attivo, POP non può renderizzare i campi neanche lato amministratore. - **I campi di fatturazione non compaiono affatto** — verifica che l'integrazione sia attivata sia lato POP (`POP > Integrazioni > Paid Member Subscriptions`) sia che il plugin Cozmoslabs sia effettivamente attivo: entrambe le condizioni sono necessarie. ## Configurazione correlata Per attivare un canale di invio (obbligatorio perché POP possa trasmettere la fattura allo SDI o al provider scelto), vedi [sdi-via-pop](sdi-via-pop.md) o [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/paid-memberships-pro ## Obiettivo Generare fatture elettroniche per gli abbonamenti venduti tramite **Paid Memberships Pro (PMPro)**, usando POP come motore di fatturazione al posto (o in aggiunta) di WooCommerce. Non confonderla con [Paid Member Subscriptions](paid-member-subscriptions.md) di Cozmoslabs: sono due plugin di membership diversi, con nomi simili ma integrazioni POP separate. ## Prerequisiti - Plugin **Paid Memberships Pro** installato e attivo sul sito. - POP installato e il tuo canale di invio (SDI via POP, Fatture in Cloud, Aruba, SDI via PEC...) già configurato: l'integrazione PMPro non sostituisce il canale di invio, si aggiunge come fonte degli ordini da fatturare. ## Passi 1. Installa e attiva **POP** sul sito WordPress. 2. Vai su **POP > Integrazioni** e attiva la card **Paid Memberships Pro**. A differenza dei canali di invio (Fatture in Cloud/Aruba/SDI), questa integrazione **non** è mutuamente esclusiva con gli altri: puoi tenerla attiva insieme a un normale negozio WooCommerce con il suo canale di invio. 3. Una volta attiva, POP aggiunge automaticamente al checkout di PMPro gli stessi campi di fatturazione usati in WooCommerce (tipo cliente privato/azienda/libero professionista, codice SDI/PEC, codice fiscale/partita IVA), e userà quei dati per generare la fattura di ogni pagamento registrato da PMPro. ## Calcolo delle tasse L'addon calcola in automatico l'IVA sugli abbonamenti PMPro usando le aliquote configurate in POP per il paese di fatturazione: **non è necessario** attivare alcuna opzione aggiuntiva perché POP generi l'imposta sul documento — è un comportamento sempre attivo dell'addon, non un interruttore da azionare. Se in **PMPro > Impostazioni > Avanzate** hai anche l'opzione nativa di PMPro per il calcolo delle tasse al checkout, questa riguarda cosa vede il cliente in fase di pagamento (l'importo mostrato a checkout), non se POP calcola l'IVA sulla fattura: sono due cose distinte, e la seconda non dipende dalla prima. ## Verifica Dopo un pagamento di test su un livello di membership PMPro, controlla che POP abbia generato il documento con i dati di fatturazione inseriti al checkout e con l'IVA correttamente calcolata. ## Errori comuni - **I campi di fatturazione non compaiono al checkout PMPro** — verifica che l'integrazione sia attivata sia lato POP (`POP > Integrazioni > Paid Memberships Pro`) sia che PMPro sia effettivamente attivo: entrambe le condizioni sono necessarie. - **L'IVA non compare in fattura** — non è legata al toggle nativo di PMPro in Impostazioni > Avanzate: verifica invece che il paese di fatturazione del cliente abbia un'aliquota configurata in POP. ## Configurazione correlata Per attivare un canale di invio (obbligatorio perché POP possa trasmettere la fattura allo SDI o al provider scelto), vedi [sdi-via-pop](sdi-via-pop.md) o [fatture-in-cloud-connect](fatture-in-cloud-connect.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/peppol ## Obiettivo Attivare l'invio di fatture elettroniche tramite la rete PEPPOL direttamente dal tuo store WordPress o Shopify. Per la Francia il corridoio è distinto (gov-fr, non PEPPOL generico): vedi [france-peppol](france-peppol.md). ## Prerequisiti - Su WordPress: nessun piano minimo, l'attivazione e l'invio sono disponibili su ogni piano (incluso Free), a consumo di crediti. Su Shopify serve invece il piano **Basic o superiore**. - Indirizzo (via, città, CAP) della legal entity completo — PEPPOL richiede questi campi per la registrazione dell'endpoint. - Per la Germania: va scelto esplicitamente il "corridoio documentale" (`zugferd` o `peppol`) — senza questa scelta l'attivazione non si completa. ## Passi Puoi attivare PEPPOL in tre modi equivalenti: 1. **Pannello account** — su `popapi.io`, vai su **Il mio account > Integrazioni**, apri la scheda PEPPOL e attiva **"Attiva PEPPOL"**. 2. **Dal plugin/app, account già esistente** — su WordPress: scheda **Generali**, aggiorna le informazioni di licenza, poi vai su **Integrazioni** e clicca sulla card PEPPOL per attivarla. 3. **Wizard di configurazione al primo accesso** — se stai configurando l'account per la prima volta e il tuo paese usa il corridoio PEPPOL, l'attivazione avviene automaticamente al completamento del wizard. ## Invio automatico - **WordPress** — scheda **Avanzate > Invio automatico delle fatture**: abilita l'invio via WP-Cron in background. - **Shopify** — l'invio automatico su ordine pagato è disponibile sui piani a pagamento; è disabilitato di default per i clienti privati (PEPPOL è un corridoio B2B). ## Invio manuale Usa il bottone **"Invia Fattura"** nella tabella fatture per inviare un singolo documento alla rete PEPPOL. ## Errori comuni - **"Questo campo è richiesto quando PEPPOL è attivo"** — manca indirizzo, città o CAP della legal entity: completali nel pannello account prima di riprovare. - **Attivazione Germania bloccata** — per gli account `DE` serve scegliere il corridoio documentale (`zugferd` o `peppol`) prima che l'attivazione vada a buon fine. - **L'invio automatico non parte per un cliente privato** — atteso: PEPPOL è pensato per destinatari business, l'invio automatico a clienti privati è disabilitato per design. ## Configurazione correlata Per i dettagli del contratto API (payload, mapping campi UBL), vedi [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/sdi-via-pec ## Obiettivo Inviare fatture elettroniche valide (B2B e B2C) al Sistema di Interscambio tramite una casella PEC, usando l'addon **SDI via PEC**. ## Prerequisiti - Addon **SDI via PEC** installato e attivo. - Una casella PEC con accesso SMTP (host, porta/sicurezza, utente, password). - Solo **una** integrazione di invio fatture può essere attiva alla volta: disattiva Fatture in Cloud o Aruba prima di attivare questa. ## Passi ### 1. Configura la casella PEC (SMTP) Nella scheda **SDI via PEC** del plugin, inserisci i parametri della tua casella PEC: host SMTP, tipo di sicurezza della connessione, utente e password. Il plugin traccia anche una data di scadenza della password, utile come promemoria per rinnovarla prima che smetta di funzionare. Se il tuo provider PEC richiede l'autenticazione a due fattori per l'accesso SMTP (es. Aruba PEC), dovrai generare una password applicativa dedicata dal pannello del provider (per Aruba PEC: **gestione account > Password per programmi di posta**) e usare quella al posto della password normale — è un requisito del provider PEC, non un'impostazione del plugin. ### 2. Verifica/personalizza l'indirizzo destinatario SDI Il campo **destinatario PEC del Sistema di Interscambio** ha come default `sdi20@pec.fatturapa.it`; puoi sovrascriverlo solo se il tuo caso richiede un indirizzo diverso. ### 3. Configura l'invio automatico 1. **Stato ordine che attiva l'invio** — default "Completato", configurabile su un altro stato ordine WooCommerce. 2. **Abilita l'invio automatico** — alla scadenza di un ritardo impostabile in ore (default **12 ore**) dal raggiungimento dello stato configurato, la fattura viene inviata via PEC allo SDI. ### Affidabilità di WP-Cron Gli eventi automatici dipendono da **WP-Cron**, che si attiva solo con traffico sul sito. Se il tuo sito riceve poche visite, aggiungi un Cron di sistema (es. ogni 30 minuti): ``` cd /public_html; wp cron event run --due-now >/dev/null 2>&1 ``` ### Log diagnostico Per tracciare scheduling ed esecuzione degli invii, aggiungi in `wp-config.php`: ``` define("WP_FATT_SDI_LOG", true); ``` ## Invio manuale Usa il bottone **"Invia"** sulla fattura per trasmetterla subito via PEC; il plugin la contrassegna come inviata al termine dell'operazione. ## Verifica Controlla la casella PEC configurata: deve mostrare il messaggio inviato al destinatario SDI, e la fattura nel plugin deve risultare marcata come inviata. ## Errori comuni - **La connessione SMTP fallisce con "credenziali non valide"** — se hai attivato l'autenticazione a due fattori sulla casella PEC, la password normale non basta: genera una password applicativa dedicata. - **L'invio automatico non parte** — verifica prima WP-Cron/il Cron di sistema; è la causa più frequente. - **La password SMTP è scaduta** — il plugin traccia la data di scadenza inserita: se il provider l'ha cambiata, aggiornala nella configurazione SMTP. ## Configurazione correlata Per l'alternativa nativa senza casella PEC, vedi [sdi-via-pop](sdi-via-pop.md). Per capire un rifiuto SDI, vedi [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/sdi-via-pop ## Obiettivo Attivare **SDI via POP**, il canale nativo che invia fatture elettroniche al Sistema di Interscambio direttamente dal sito WordPress tramite il plugin POP, senza passare da Fatture in Cloud, Aruba o una casella PEC. ## Prerequisiti - Nessun piano minimo: l'attivazione è disponibile su ogni piano, incluso Free. L'invio consuma i crediti disponibili sul tuo account. - Solo **un** canale di invio fatture può essere attivo alla volta: se Fatture in Cloud, Aruba o SDI via PEC sono già attivi, disattivali prima di attivare SDI via POP. ## Passi Puoi attivare SDI via POP in due modi equivalenti. ### Dal pannello account (popapi.io) Dopo la creazione dell'account, vai su **Il mio account > Integrazioni**, apri la scheda **SDI via POP** e attiva **"Attiva SDI via POP"**; puoi anche abilitare opzionalmente firma digitale e conservazione sostitutiva. ### Dal plugin WordPress Se hai già completato la configurazione guidata dell'account: 1. Vai su **POP > Generali** e aggiorna le informazioni di licenza per sincronizzare la connessione. 2. Vai su **POP > Integrazioni** e attiva SDI via POP facendo clic sulla relativa card. Se invece stai configurando l'account per la prima volta, puoi attivarlo direttamente dalla sezione dati aziendali del wizard di configurazione guidata: l'attivazione avviene automaticamente al completamento. ## Invio automatico e manuale - **Invio manuale** — bottone **"Invia Fattura"** nella tabella fatture; usa poi il bottone **"Notifiche"** per controllare manualmente l'esito. - **Invio automatico** — scheda **POP > Avanzate > Invio automatico delle fatture**: abilita l'invio via WP-Cron in background invece che sincrono al cambio stato ordine. ## Verifica Dopo l'invio, controlla l'esito tramite il bottone **"Notifiche"** sulla fattura: deve riportare lo stato ricevuto dallo SDI (consegnata, scartata, ecc.). ## Errori comuni - **Non riesco ad attivare SDI via POP mentre un altro canale è attivo** — i canali di invio sono mutuamente esclusivi: disattiva prima Fatture in Cloud, Aruba o SDI via PEC dalla stessa schermata Integrazioni. - **L'invio ritorna un errore generico** — le cause più comuni segnalate dal sistema sono: canale non corrispondente a quello attivo, integrazione non configurata, azione non valida, o un documento con lo stesso identificativo già esistente. Verifica che SDI via POP sia effettivamente il canale attivo e riprova. ## Configurazione correlata Per il contratto dei dati (payload, mapping campi), vedi [api/sdi](../../api/sdi.md). Per capire un rifiuto SDI, vedi [sdi-invoice-rejected](../troubleshooting/sdi-invoice-rejected.md). Per l'alternativa via casella PEC, vedi [sdi-via-pec](sdi-via-pec.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/webhook ## Obiettivo Inviare automaticamente ogni documento generato da POP (XML o PDF) a uno strumento esterno: Zapier, Make (Integromat), un CRM, Google Drive, o un endpoint personalizzato. ## Prerequisiti - Su WordPress: nessun piano minimo, la consegna via webhook è disponibile su ogni piano (incluso Free), a consumo di crediti. Su Shopify serve invece il piano **Basic o superiore**. - Un endpoint HTTP in ascolto (URL del webhook di destinazione). ## Passi 1. Su `popapi.io`, vai su **Il mio account > Integrazioni > POP to Webhook > Connect**. 2. Configura: - un nome identificativo - l'URL di destinazione del webhook - il formato dati: **JSON** o **XML** - l'interruttore di attivazione 3. Su **WordPress**: nel plugin POP vai su **Avanzate > Webhook**, inserisci l'ID webhook creato al passo precedente, abilitalo, e — se vuoi l'invio in background invece che sincrono — attiva anche l'invio automatico via CRON. 4. Su **Shopify**: inserisci l'ID webhook nelle impostazioni dell'app; comparirà un'icona nella lista fatture per inviare i dati. ## Formati - **JSON** — pensato per piattaforme no-code (Zapier, Make): i dati vengono appiattiti automaticamente in una struttura semplice da mappare. - **XML** — adatto ad archiviazione o sistemi che richiedono lo standard FatturaPA; può essere inviato anche come allegato. Puoi configurare più webhook con URL e formati diversi contemporaneamente. ## Errori comuni - **URL webhook non valido** — verifica che l'URL sia raggiungibile pubblicamente e risponda con successo (non basta che sia sintatticamente corretto). - **Formato dati non supportato** — usa solo `JSON` o `XML`; altri formati vengono rifiutati. - **Il webhook non riceve nulla in sandbox** — è un limite atteso: la consegna via webhook non è disponibile in ambiente sandbox (vedi [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Configurazione correlata Per il caso specifico di inoltro verso n8n con un connector dedicato (es. Zoho), vedi [api/connectors](../../api/connectors.md) e [n8n](n8n.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/wordpress-invoice-abilities ## Obiettivo Permettere a un assistente AI collegato al tuo sito WordPress (o a uno script da riga di comando) di cercare le fatture e note di credito **già generate** da POP su WooCommerce, Paid Memberships Pro o Paid Member Subscriptions, e recuperarne XML, PDF o dati strutturati — senza dare accesso diretto al database o ai file. Questo è un meccanismo diverso dal server MCP ospitato di POP (vedi [mcp](mcp.md) e [mcp-remote](mcp-remote.md)): quello parla con l'API Cloud POP e crea nuovi documenti per qualsiasi piattaforma; questo lavora **localmente sul tuo sito WordPress**, sugli ordini che il tuo negozio ha già fatturato, e non genera nulla di nuovo — serve solo documenti già in cache. ## Prerequisiti - pop-wordpress 6.9.11 o superiore. - Per il percorso **WP-CLI**: nessun'altra dipendenza, solo accesso SSH/shell al sito. - Per il percorso **assistente AI**: il sito deve avere un'Abilities API registrata (funzione `wp_register_ability()` disponibile, tipicamente tramite il plugin "Abilities API") e un server MCP che esponga le abilities del sito (tipicamente il plugin "MCP Adapter") — pop-wordpress registra le proprie abilities solo se questi sono presenti, altrimenti non fa nulla. ## Cosa espone Quattro abilities, categoria `pop`: - `pop/search-invoices` — cerca fatture/note di credito per provider, cliente, indirizzo, stato, tipo documento o intervallo di date; restituisce gli id documento da usare con le altre tre. - `pop/get-invoice-data` — dati strutturati del documento (numero fattura, stato, totale, valuta, date, canale fiscale attivo, formati disponibili in cache). - `pop/get-invoice-xml` — XML in cache (fattura/nota di credito). - `pop/get-invoice-pdf` — metadati e URL del PDF in cache. ## Passi ### Percorso assistente AI (Abilities/MCP) 1. Installa e attiva i plugin **Abilities API** e **MCP Adapter** sul sito WordPress, oltre a pop-wordpress. 2. Collega il tuo assistente AI al server MCP del sito (indirizzo e autenticazione dipendono dal plugin MCP Adapter installato). 3. Chiedi all'assistente qualcosa come *"Cerca le fatture del cliente Rossi di luglio"*: l'assistente usa `pop/search-invoices`, poi `pop/get-invoice-data`/`xml`/`pdf` sul documento trovato. Per default, ogni ability richiede la capability WordPress `manage_options` (filtrabile con `wc_el_inv-abilities-capability`), perché raggiungibile via HTTP. ### Percorso WP-CLI ```bash wp popapi invoice search --customer="Rossi" --date_from=2026-07-01 wp popapi invoice get --provider=woocommerce wp popapi invoice xml --raw wp popapi invoice pdf ``` - `search` accetta `--provider`, `--customer`, `--address`, `--status`, `--document_type`, `--date_from`, `--date_to`, `--limit` (default 10, max 50), `--offset`. - `get`/`xml`/`pdf` richiedono `` come argomento posizionale, più `--provider` (obbligatorio se sul sito sono attivi più provider), `--document_type`, `--parent_id` (per le note di credito). - Tutti e quattro accettano `--format=table|csv|json|yaml|ids|count` e `--fields=`. - `xml --raw` stampa solo il contenuto XML, senza metadati. I comandi WP-CLI **non** applicano il gate `manage_options`: l'accesso shell/WP-CLI al sito è già una barriera di fiducia più forte di una capability WordPress, quindi non serve `--user`. ## Verifica `wp popapi invoice search --format=count` deve restituire un numero coerente con gli ordini fatturati sul sito. Su un documento esistente, `wp popapi invoice get --provider=` deve restituire i dati strutturati senza errori. ## Errori comuni - **`pop_ability_forbidden`** (403, solo percorso AI) — l'utente autenticato non ha la capability richiesta: verifica il ruolo o il filtro `wc_el_inv-abilities-capability`. - **`pop_ability_invalid_provider`** — il sito ha più provider attivi (es. WooCommerce e PMPro insieme) e non hai specificato `--provider`/`provider`: il messaggio elenca i provider attivi tra cui scegliere. - **`pop_ability_document_not_found`** — id documento inesistente per il provider/tipo indicato. - **`pop_ability_xml_not_found` / `pop_ability_pdf_not_found`** — il documento non ha XML/PDF in cache: queste abilities servono solo documenti già generati, non ne creano di nuovi al volo. - **Nessuna ability registrata (silenzio, nessun errore)** — mancano i plugin Abilities API/MCP Adapter: il percorso WP-CLI resta comunque disponibile indipendentemente da questi plugin. ## Configurazione correlata Per generare o inviare nuovi documenti da un assistente AI (non solo recuperare quelli esistenti), vedi [mcp](mcp.md) o [mcp-remote](mcp-remote.md), che lavorano a livello di API Cloud POP e non richiedono plugin aggiuntivi su WordPress. --- ## Source: https://docs.popapi.io/it/guides/integrations/zoho ## Obiettivo Sincronizzare fatture e note di credito generate da POP con **Zoho Invoice** o **Zoho Books**, senza dover gestire tu stesso un webhook o un workflow n8n. ## Prerequisiti - Un account Zoho Invoice o Zoho Books attivo. - Su WordPress: nessun piano minimo, la sincronizzazione è disponibile su ogni piano (incluso Free), a consumo di crediti. Su Shopify serve invece il piano **Basic o superiore**. ## Attivazione (due passaggi) 1. **Account POP** — vai su `popapi.io > Il mio account > Integrazioni API` e completa l'autorizzazione OAuth verso Zoho. Da qui in poi Zoho è uno dei canali di invio disponibili: attivarlo come canale principale disattiva automaticamente ogni altro canale già attivo (SdI via POP, PEPPOL, KSeF, Fatture in Cloud, Aruba, SdI via PEC — sono tutti mutuamente esclusivi). 2. **Lato plugin/app** — l'autorizzazione sull'account POP non basta da sola: va abilitata anche localmente. ### WordPress Nella tab **Integrazioni**, trova la card **"Zoho (via POP)"** e clicca **Activate**. Se l'account POP non ha ancora completato l'autorizzazione, la card mostra il messaggio *"Activate and connect Zoho in your POP account first."* — torna al passaggio 1. ### Shopify Vai su **Impostazioni > Invoice Channel** e seleziona l'opzione **"Zoho via POP"** tra i canali disponibili (selezione a radio button). Se l'opzione risulta disabilitata con l'etichetta "(unavailable)", compare un banner che spiega il motivo (es. account POP non pronto, o il connector attivo lato POP non è Zoho). ## Invio manuale e automatico **WordPress:** - Manuale — pulsanti **"Create Zoho Invoice"** / **"Create Zoho Credit Note"** sull'ordine; dopo l'invio diventano **"Zoho invoice created"** / **"Zoho credit note created"**. - Automatico — usa la stessa impostazione di invio automatico già presente per gli altri canali (stato ordine che attiva l'invio, con eventuale ritardo in ore). **Shopify:** - Manuale — pulsanti **"Send invoice to Zoho"** / **"Send credit note to Zoho"** nella pagina Ordini. - Stato mostrato in tabella: **"Zoho: sent"** oppure **"Zoho: pending"**. ## Note di credito: serve prima la fattura Zoho Una nota di credito non può essere inviata a Zoho se l'ordine collegato non ha già una fattura sincronizzata su Zoho con successo: - **WordPress** — il pulsante resta bloccato con il messaggio: *"Zoho credit notes require a Zoho parent invoice reference on the original order. Create the Zoho invoice first."* - **Shopify** — stesso blocco, messaggio: *"Send the parent invoice through Zoho before generating or sending the credit note."* Fix: invia prima la fattura originale a Zoho, poi la nota di credito. ## Sandbox - **WordPress** — un invio in sandbox non crea nulla su Zoho: restituisce una conferma di prova, *"Zoho sandbox dry run succeeded. No document was created in Zoho."* — non è un errore, è il comportamento atteso. - **Shopify** — l'invio automatico in coda viene bloccato con: *"Zoho auto-send is disabled while POP sandbox mode is active. Switch the environment back to live to process queued invoices."* ## Verifica Dopo l'attivazione, controlla nel plugin/app che lo stato Zoho risulti connesso e che il prodotto collegato (Zoho Invoice o Zoho Books) sia indicato correttamente, non "not available". ## Errori comuni - **Il prodotto risulta "not available"** — l'autorizzazione OAuth non è stata completata o è scaduta: ripeti il passaggio 1 dal pannello account. - **Ho attivato Zoho e un altro canale si è disattivato da solo** — comportamento atteso: i canali principali sono mutuamente esclusivi. - **Il pulsante di invio nota di credito resta bloccato** — vedi la sezione sopra: manca la fattura Zoho collegata all'ordine originale. - **"The previous Zoho send may have timed out..."** (WordPress) — l'invio precedente potrebbe non aver ricevuto risposta in tempo: se il documento risulta creato su Zoho, conferma e salva manualmente l'ID restituito; altrimenti annulla e riprova. - **La sincronizzazione fallisce per un contatto mancante** — verifica l'opzione di auto-creazione contatti; se disattivata, il contatto deve già esistere su Zoho prima della sincronizzazione. ## Configurazione correlata Per scegliere tra questo canale e gli altri disponibili, vedi [choosing-an-invoicing-integration](../getting-started/choosing-an-invoicing-integration.md). Per i dettagli endpoint, vedi [api/zoho](../../api/zoho.md). --- ## Source: https://docs.popapi.io/it/guides/integrations/zugferd ## Obiettivo Scegliere quale corridoio documentale usare per un account tedesco (`DE`): **ZUGFeRD/Factur-X** oppure **PEPPOL**. La scelta è obbligatoria per gli account `DE` e determina quale formato POP genera. ## Prerequisiti - Account POP con paese impostato su `DE`. ## Passi 1. La scelta si fa **solo dal pannello account POP** (wizard di onboarding o `account-setup`): non esiste un controllo dedicato né nel plugin WordPress né nell'app Shopify: entrambi mostrano solo lo stato attivo (badge), in sola lettura. 2. Se non scegli esplicitamente, per un account `DE` senza legal entity PEPPOL registrata il valore predefinito è **`zugferd`**. 3. Per passare a `peppol`, registra una legal entity PEPPOL (vedi [integrations/peppol](peppol.md)): da quel momento il corridoio viene forzato automaticamente su `peppol` e **non può più tornare a `zugferd`**, la scelta si blocca appena esiste una legal entity PEPPOL (live o sandbox). ## Verifica Nel plugin WordPress, la sezione **ZUGFeRD** nelle impostazioni mostra lo stato corrente e il consumo crediti; nell'app Shopify compare un badge "ZUGFeRD attivo" quando il corridoio è `zugferd`. In entrambi i casi il valore mostrato riflette quello impostato nel pannello account, non è modificabile da lì. ## Usare ZUGFeRD una volta attivo (WordPress) Quando il corridoio dell'account è `zugferd`, il plugin WordPress sostituisce i pulsanti separati XML/PDF con un'esperienza dedicata, sia nella lista ordini che nel dettaglio ordine: - **Pulsante ZUGFeRD**: scarica il PDF ibrido (quello con l'XML incorporato), pensato per l'uso quotidiano. - **Download ZIP**: scarica in un unico archivio tutti e tre i file (PDF ibrido, PDF standard, XML EN16931). Viene servito dalla cache locale e **non consuma crediti aggiuntivi** rispetto alla generazione iniziale. - **Email ordine completato**: il PDF ibrido viene allegato automaticamente all'email di ordine completato. Se reinvii quell'email dal dettaglio ordine, i file già generati in cache non vengono cancellati, puoi reinviarla quante volte serve senza rigenerare il bundle. ## Da sapere - Ogni bundle ZUGFeRD generato consuma **1 credito** (la generazione stessa è l'unica azione fatturata, a differenza di XML/UBL/KSeF dove la generazione è gratuita e solo l'invio consuma un credito); scaricare di nuovo lo stesso bundle dalla cache (incluso lo ZIP) non consuma crediti ulteriori. - Su Shopify, la generazione automatica all'ordine pagato **non include** i documenti ZUGFeRD: quando il corridoio è `zugferd`, l'invio automatico viene saltato esplicitamente, perché il bundle è composto da 3 file (PDF visuale, XML EN16931, PDF ibrido) e richiede un'azione manuale per scegliere cosa generare. - Vedi [api/zugferd](../../api/zugferd.md) per il contratto API del bundle generato. ## Errori comuni - **"Germany requires a document corridor selection"**: un account `DE` non ha ancora scelto il corridoio, vai al wizard/pannello account e seleziona `zugferd` o `peppol`. - **"Invalid Germany document corridor. Allowed values: zugferd, peppol"**: è stato inviato un valore diverso dai due ammessi, usa esattamente `zugferd` o `peppol`. - **Non riesco a tornare a ZUGFeRD dopo aver attivato PEPPOL**: comportamento atteso, una volta registrata una legal entity PEPPOL, il corridoio resta bloccato su `peppol`. --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/admin-error-email-notifications ## Sintomo L'indirizzo email amministratore del sito WordPress (`admin_email`) riceve automaticamente un'email quando qualcosa va storto nella generazione o trasmissione di una fattura, senza che nessuno l'abbia richiesto esplicitamente. ## Causa Non è un add-on opzionale da attivare: è un comportamento **integrato nel plugin POP**, sempre attivo, pensato per far notare subito eventuali problemi senza dover controllare i log manualmente. Le email vengono inviate all'indirizzo admin del sito (`get_bloginfo('admin_email')`) in questi casi: - **Setup account non completato** — se il wizard non è stato completato (manca il collegamento all'account POP) e il sito prova comunque a generare un documento, arriva un'email "Complete Your Account Setup" con i passi per completare la configurazione. - **Errore dell'API POP** — qualsiasi risposta di errore dalle chiamate di generazione/invio documento genera un'email con oggetto e contesto tecnico dell'errore. - **Overquota** — se l'account ha esaurito i crediti disponibili, arriva un'email dedicata "POP API overquota block". - **Rifiuto da parte dello SDI** — se arriva una notifica di scarto (tipo `NS`) per una fattura inviata allo SDI, arriva un'email con oggetto "POP - SDI Reject Notification" e i dettagli dell'ordine. ## Fix Non c'è nulla da "attivare": queste notifiche sono automatiche. Se le ricevi, agisci sulla causa indicata nel corpo dell'email: 1. **Setup account non completato** → vai su `POP → Electronic Invoice - Settings`, tab **General**, e completa/collega l'account (o rilancia il wizard). 2. **Errore API generico o overquota** → controlla il messaggio tecnico incluso nell'email: indica lo status code e il contesto della chiamata fallita; verifica piano e crediti residui dell'account. 3. **Scarto SDI** → apri la fattura indicata e verifica i dettagli dello scarto prima di correggere e reinviare. Se **non vuoi ricevere queste email** su quell'indirizzo, l'unica leva è cambiare l'`admin_email` del sito WordPress (impostazione generale di WordPress, non un'opzione di POP): non esiste un toggle dedicato in POP per disattivarle singolarmente. ## Configurazione correlata Per la checklist quando una fattura SDI viene rifiutata vedi [sdi-invoice-rejected](sdi-invoice-rejected.md). --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/credit-note-generation ## Sintomo Un rimborso genera un XML nota di credito che non corrisponde a quanto rimborsato, oppure il documento viene rifiutato/non generato correttamente. ## Causa Le cause più comuni: - **La nota di credito è stata generata prima che la fattura originale fosse effettivamente inviata** — una nota di credito ha senso solo se collegata a una fattura già emessa/inviata: deve riportare riferimento (numero e data) della fattura collegata. - **Il rimborso è stato registrato solo per importo, senza stornare le quantità** — se indichi solo l'importo rimborsato senza annullare le quantità dei prodotti coinvolti, il documento non riflette correttamente cosa è stato reso/annullato. ## Fix 1. Verifica che la fattura originale sia stata effettivamente inviata prima di procedere col rimborso: se non lo è, valuta prima di correggere/inviare la fattura originale. 2. Quando registri il rimborso su WooCommerce, **storna le quantità** dei prodotti interessati (non limitarti a inserire un importo di rimborso libero): è quello che permette al documento di riportare correttamente le righe annullate. 3. Dopo il rimborso, POP genera automaticamente l'XML della nota di credito collegata all'ordine (vedi [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md) per il trigger esatto). Scaricalo dalla tab **Invoices**. 4. Se usi un canale/add-on di trasmissione verso un gestionale esterno, l'invio della nota di credito al gestionale potrebbe richiedere un caricamento manuale, distinto dalla sola generazione del documento: verifica il comportamento specifico del canale attivo. ## Configurazione correlata Per i requisiti esatti del payload nota di credito (`connected_invoice_data.id`/`date`) lato API, vedi [api/sdi](../../api/sdi.md); per capire quando l'ordine genera effettivamente l'XML vedi [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/delete-an-invoice ## Sintomo Non si trova un pulsante "elimina fattura" nella tab **Invoices** o nella lista documenti di POP. ## Causa Le fatture generate da POP sono **collegate strutturalmente all'ordine** che le ha originate: non esistono come entità indipendenti nel database. Se l'ordine non esiste (o viene cancellato), non esiste più nemmeno la fattura associata. Questo vale sia usando solo il plugin POP, sia con un canale/add-on di trasmissione attivo (Fatture in Cloud, Aruba, ecc.) per la parte di generazione documento lato WordPress. ## Fix Per "eliminare" una fattura, elimina l'ordine WooCommerce collegato: 1. Vai su `WooCommerce > Ordini`. 2. Individua l'ordine corrispondente al numero fattura da rimuovere. 3. Spostalo nel cestino o eliminalo definitivamente, secondo la procedura standard di WooCommerce. **Prima di farlo, considera le implicazioni fiscali**: se la fattura era già stata inviata/trasmessa (es. allo SDI, o caricata su un gestionale esterno collegato), eliminare l'ordine locale **non annulla** la trasmissione già avvenuta. Per un documento già trasmesso, la via corretta è la nota di credito, non la cancellazione — vedi [credit-note-generation](credit-note-generation.md). ## Configurazione correlata Per capire quando viene assegnato il numero fattura (e quindi da quale ordine "nasce") vedi [invoice-numbering-and-order-status](../configuration/invoice-numbering-and-order-status.md). --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/quota-and-overquota ## Sintomo Una richiesta di generazione documento fallisce con un errore relativo alla quota, oppure il plugin WordPress mostra un avviso che la quota inclusa nel piano è esaurita. ## Causa Ogni piano POP include un numero di operazioni mensili ("crediti") a consumo. La generazione locale di un documento (XML, PDF, UBL, FA(3)) non consuma mai un credito: a consumarlo è solo l'operazione successiva, quando prevista, cioè l'invio a un canale (SdI, PEPPOL, KSeF, Zoho, Fatture in Cloud, Aruba, SdI via PEC), la consegna via webhook, l'invio email del PDF o la conservazione sostitutiva. Quando la quota inclusa è esaurita: - se il tuo piano **non** prevede overquota (uso extra oltre l'incluso), le nuove richieste vengono rifiutate finché non rinnova il ciclo o fai upgrade; - se il tuo piano **prevede** overquota ed è abilitata sul tuo account, l'uso extra continua ma può essere fatturato automaticamente, fino a un tetto mensile configurato sul tuo account. ## Verifica lo stato del tuo account `GET /wp-json/api/v2/overquota-policy` (autenticata con la tua `license_key`) restituisce lo stato completo: quota inclusa (`included_quota`), quota già usata (`used_quota`), se l'overquota è abilitata (`overquota_enabled`/`effective_overquota_enabled`), la tariffa per richiesta extra configurata sul tuo account (`rate_eur`) e il tetto mensile (`monthly_cap_eur`), oltre a un messaggio di stato leggibile (`status_message`) con l'azione suggerita (`suggested_action`). ## Fix - **Quota esaurita, overquota non abilitata**: attendi il rinnovo del ciclo mensile oppure fai upgrade del piano da `popapi.io > Account`. - **Overquota abilitata ma hai raggiunto il tetto mensile configurato**: le richieste extra vengono bloccate finché non rinnova il ciclo o il tetto viene alzato, contatta il supporto per rivedere il tetto mensile del tuo account. - **Nessun metodo di pagamento valido collegato**: l'overquota a pagamento richiede un metodo di pagamento Stripe valido salvato sull'account, aggiungilo dal pannello account prima che l'uso extra possa proseguire. - **Hai un saldo overquota da regolarizzare**: se un ordine overquota di un ciclo precedente è rimasto non pagato per più di 30 giorni, il nuovo uso extra a pagamento viene bloccato finché non lo salde, controlla `settlement_pending` nella risposta di `overquota-policy` o lo stato pagamenti dal pannello account. - **Non sai se l'overquota è abilitata sul tuo account**: non è un'opzione self-service dal plugin, contatta il supporto per attivarla o modificarne i limiti. ## Configurazione correlata Vedi [api/overview](../../api/overview.md) per l'autenticazione delle chiamate API. --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/sdi-invoice-rejected ## Sintomo La chiamata a `create-xml` (o l'invio SdI collegato) restituisce un errore JSON invece dell'XML/esito atteso, oppure il documento viene respinto prima dell'invio. ## Cause - **Regime fiscale non allineato** — se sia il payload che l'account hanno `tax_regime` impostato, i due valori devono coincidere. Se non coincidono, la generazione fallisce. - **Nota di credito su piano free** — i piani free non possono creare note di credito (`type: credit_note`). - **Nota di credito senza riferimento alla fattura collegata** — le note di credito richiedono `connected_invoice_data.id` e `connected_invoice_data.date` valorizzati. - **Manca l'instradamento del destinatario** — serve `transmitter_data.sdi_code` oppure `transmitter_data.recipient_pec`; senza uno dei due l'invio non può essere instradato. - **Payload incompleto** — campi obbligatori mancanti nel payload condiviso (es. dati fornitore/cliente, totale documento, almeno una riga in `order_items`). ## Fix 1. Controlla il `tax_regime` configurato sull'account (pannello POP) e allinealo a quello inviato nel payload, oppure ometti il campo nel payload se non necessario. 2. Se stai generando una nota di credito, verifica piano attivo e presenza di `connected_invoice_data.id`/`date`. 3. Verifica che il payload contenga `sdi_code` o `recipient_pec` per il destinatario. 4. Rileggi la risposta JSON di errore: il messaggio indica quale validazione ha fallito — non serve indovinare, il body della risposta è la fonte primaria. 5. Riprova prima in sandbox (vedi [use-sandbox-environment](../configuration/use-sandbox-environment.md)) per isolare il problema senza toccare dati di produzione. ## Configurazione correlata Per i nomi canonici dei campi payload e i codici errore documentati, vedi [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/sepa-direct-debit-payments ## Sintomo Un cliente paga un abbonamento/membership tramite **SEPA Direct Debit (SDD)** (addebito diretto SEPA su IBAN): l'ordine risulta subito "in elaborazione" e l'accesso viene attivato, ma il pagamento non compare come "completato" per un certo numero di giorni. ## Causa Non è un errore: è il funzionamento standard del mandato **SDD**. A differenza di carta o bonifico, un addebito SDD richiede un periodo di attesa (tipicamente attorno a **14 giorni**) prima che i fondi vengano effettivamente prelevati dal conto del cliente, perché il mandato deve essere confermato dalla banca. Durante questo periodo: - l'ordine risulta in stato "in elaborazione" lato piattaforma di pagamento; - l'accesso/membership viene comunque attivato subito, per non far attendere il cliente; - il cliente riceve una prima email di conferma attivazione, e una seconda al termine del periodo di verifica quando il pagamento risulta effettivamente completato. Questo comportamento dipende dal gateway di pagamento (es. Stripe SDD) e dalle regole SEPA, non da una configurazione del plugin di fatturazione POP: SDD non è un metodo di pagamento gestito o configurato da POP. ## Fix Non serve alcuna azione per far "completare prima" il pagamento: è un vincolo del circuito SEPA, non qualcosa che si possa accelerare lato sito. Se un cliente segnala il ritardo: 1. Conferma che ha ricevuto (o riceverà) l'email di conferma mandato dalla banca/gateway. 2. Rassicuralo che l'accesso è già attivo nel frattempo. 3. Se dopo 14 giorni circa il pagamento non risulta ancora completato, verifica lo stato del mandato direttamente nel pannello del gateway di pagamento (non in POP, che non gestisce questo flusso). ## Configurazione correlata Questo comportamento riguarda il gateway di pagamento/l'abbonamento, non le impostazioni di fatturazione elettronica del plugin POP: non esiste una pagina di configurazione POP per SDD. --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/shopify-billing-address-override ## Sintomo Un ordine Shopify ha un indirizzo di fatturazione errato (via, città, CAP, nome...) e serve correggerlo prima di generare/inviare il documento fiscale, ma Shopify non permette di modificare l'indirizzo di fatturazione di un ordine già creato. ## Causa Shopify non espone un'interfaccia per modificare l'indirizzo di fatturazione dopo la creazione dell'ordine. POP risolve questo limite con un set di metafield ordine dedicati che, se valorizzati, sovrascrivono il dato corrispondente in fase di generazione documento. ## Fix 1. In Shopify Admin vai su **Settings > Custom data > Orders** e crea le definizioni dei seguenti metafield (namespace `app`, tipo "Single line text"): - `pop_billing_first_name` - `pop_billing_last_name` - `pop_billing_company` - `pop_billing_address1` - `pop_billing_address2` - `pop_billing_city` - `pop_billing_province` - `pop_billing_zip` - `pop_billing_country` 2. Apri l'ordine interessato e valorizza **solo** i campi che richiedono correzione: non serve compilarli tutti, anche un solo campo è sufficiente. 3. Salva: POP fa un merge campo per campo — i metafield impostati sovrascrivono il dato originale dell'ordine, gli altri campi restano quelli originali (indirizzo di fatturazione, o in mancanza indirizzo cliente/spedizione). 4. Rigenera il documento: userà subito l'indirizzo corretto. ## Configurazione correlata Questo meccanismo corregge l'indirizzo del **cliente** su un singolo ordine. Per sostituire in modo permanente l'indirizzo del **venditore/emittente** su tutti i documenti, vedi [shopify-seller-fiscal-data](../configuration/shopify-seller-fiscal-data.md). Per la gestione generale dei dati fiscali cliente (P.IVA, Codice Fiscale, tipo cliente), vedi [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). --- ## Source: https://docs.popapi.io/it/guides/troubleshooting/shopify-order-edit-invoice-mismatch ## Sintomo Hai modificato un ordine su Shopify (prodotto sostituito, quantità o importo cambiati) prima che la fattura fosse inviata a un canale ufficiale, ma il PDF/XML scaricato mostra ancora i dati vecchi. Oppure: vedi un bottone "Note di credito" su un ordine dove non è mai stato incassato alcun rimborso reale. ## Causa Shopify non notifica sempre POP in tempo reale quando modifichi un ordine. Per questo, quando richiedi di nuovo il documento (scaricandolo, o al pagamento se l'invio è automatico), POP verifica se l'ordine è stato modificato dopo l'ultima generazione: se sì, non serve il file salvato ma ne genera uno nuovo con i dati aggiornati, riusando lo stesso numero e progressivo già assegnati (nessuna nuova identità documento). Questo controllo si applica solo se la fattura non è ancora stata inviata a un canale ufficiale (SdI, PEPPOL, KSeF, Zoho) o via email: da quel momento il documento è protetto e ogni correzione richiede una nota di credito, per non riscrivere un documento fiscale già emesso. Una modifica che riduce solo le quantità (senza incasso reale) crea in Shopify un record di rimborso "tecnico" identico nell'aspetto a un rimborso vero: POP li distingue e non genera più una nota di credito spuria per questi casi. ## Fix 1. Dopo aver modificato l'ordine, **riapri/riscarica il documento** dalla pagina Orders (o attendi il trigger automatico, es. al pagamento): questo è il momento in cui POP verifica l'allineamento e rigenera se necessario. La modifica dell'ordine da sola non aggiorna il file esistente. 2. Verifica che il documento non sia già stato inviato a un canale ufficiale: se lo è, la fattura resta quella emessa e la correzione va fatta con una nota di credito dalla pagina Orders (bottone dedicato, generato da un rimborso Shopify reale). 3. Nota: rigenerare un documento perché l'ordine è cambiato consuma un credito piano, come una nuova generazione. ## Configurazione correlata Per i requisiti del payload nota di credito (`connected_invoice_data.id`/`date`) lato API, vedi [api/sdi](../../api/sdi.md). --- ## Source: https://docs.popapi.io/nl/guides/getting-started/choosing-an-invoicing-integration ## Doel Begrijpen welk verzendkanaal u voor uw winkel moet activeren, uit de kanalen die in POP beschikbaar zijn. **De kanalen sluiten elkaar wederzijds uit**: u kunt er telkens maar één actief hebben (het activeren van één kanaal deactiveert automatisch de andere). ## Beschikbare kanalen | Kanaal | Voor wie | Externe afhankelijkheden | Opmerkingen | | --- | --- | --- | --- | | **SdI via POP** | Voor wie de eenvoudigste flow voor Italië wil: geen externe dienst te configureren | Geen | Directe verzending naar de SdI, meldingen worden binnen POP afgehandeld, automatische controle van fiscaal nummer/btw-nummer van de ontvanger. | | **SdI via PEC** | Lage volumes, voor wie al een PEC-postbus (gecertificeerde e-mail) heeft en geen extra externe accounts wil | PEC-postbus | De XML wordt via PEC-e-mail verzonden; resultaatmeldingen moeten handmatig in de PEC-postbus worden gecontroleerd — ze worden niet automatisch door POP afgehandeld. | | **Fatture in Cloud** | Voor wie al Fatture in Cloud gebruikt voor boekhouding/facturering | Actief Fatture in Cloud-abonnement | Verloopt via de officiële Fatture in Cloud-API; vereist het mappen van [betaalmethoden](../integrations/fatture-in-cloud-payment-methods.md) en een saldorekening vóór de eerste indiening. | | **Aruba Business** | Voor wie Aruba al gebruikt als aanbieder van elektronische facturering | API-activering bij Aruba | Minder configuratieflexibiliteit dan de andere opties. | | **PEPPOL** | B2B-verkoop in het buitenland (PEPPOL-netwerk) | Geen | Geen alternatief voor de SdI voor Italië: het is de corridor voor intra-EU elektronische facturering. Dekt 28 landen (volledige lijst in [api/peppol](../../api/peppol.md)) — **Spanje is uitgesloten** (Facturae-corridor, nog niet ondersteund), evenals Noord-Ierland en Liechtenstein. | | **KSeF** | Verkoop naar Polen | Pools NIP (fiscaal nummer) | Zie [KSeF-activering](../integrations/ksef.md) — vereist een aparte, dedicated registratie los van SdI/PEPPOL. | | **Zoho (native)** | Voor wie Zoho Invoice/Zoho Books gebruikt en de synchronisatie rechtstreeks door POP wil laten beheren | OAuth-autorisatie naar Zoho | Zie [Zoho-activering](../integrations/zoho.md). Vereist geen eigen n8n-instantie. Voor accounts geregistreerd in de Verenigde Arabische Emiraten, Saoedi-Arabië, Bahrein, Koeweit, Oman of Qatar is dit het **enige** beschikbare kanaal: deze landen hebben geen ondersteund officieel netwerk voor elektronische facturering (geen SdI/PEPPOL/KSeF). | Als u de synchronisatielogica liever zelf beheert op uw eigen self-hosted n8n-instantie (meer controle/maatwerk), bestaat daarvoor ook een dedicated package — zie [synchroniseren naar Zoho via n8n](../integrations/n8n-zoho.md). ## Hoe kiest u - **U verkoopt alleen in Italië en gebruikt nog geen extern boekhoudsysteem** → SdI via POP: dit is het pad met de minste configuratiestappen, en meldingen blijven binnen POP. - **U gebruikt al Fatture in Cloud of Aruba voor de boekhouding** → koppel die integratie in plaats van gegevens elders te dupliceren, maar reserveer tijd om de vereiste mapping te voltooien (rekeningen, betaalmethoden). - **Zeer weinig documenten per maand en u wilt nul extra kosten/diensten** → SdI via PEC, wetende dat u de resultaten handmatig in de PEC-postbus moet controleren. - **Uw winkel is gevestigd in Italië of San Marino** → blijf bij SdI (via POP of via PEC), ook voor buitenlandse zakelijke klanten: PEPPOL wordt in dit geval nooit geactiveerd, ongeacht het land van de klant. Facturen aan buitenlandse klanten lopen nog steeds via SdI, met de conventionele ontvangercode voor niet-Italiaanse ontvangers. - **Uw winkel is gevestigd in een ander EU-land dan Italië/San Marino dat door PEPPOL wordt gedekt** (volledige lijst in [api/peppol](../../api/peppol.md)) en u verkoopt B2B → gebruik PEPPOL: dit is het equivalent van SdI voor elektronische facturering in die landen. - **U verkoopt in Polen** → u heeft KSeF nodig, ongeacht het voor Italië gekozen kanaal. - **Uw account is geregistreerd in de Verenigde Arabische Emiraten, Saoedi-Arabië, Bahrein, Koeweit, Oman of Qatar** → native Zoho is de enige optie: voor deze landen is geen ander kanaal beschikbaar. ## Goed om te weten - Het gelijktijdig activeren van SdI via POP en PEPPOL wordt niet ondersteund: zijn beide uiteindelijk actief, dan krijgt het laatst geactiveerde voorrang en wordt het andere automatisch gedeactiveerd. - U kunt later van kanaal wisselen, maar de configuratie van het nieuwe kanaal (inloggegevens, mappings) moet opnieuw worden gedaan — er is geen automatische gegevensmigratie tussen de ene integratie en de andere. ## Gerelateerde configuratie Voor activeringsdetails van elk kanaal, zie de bijbehorende handleidingen in dit deel ("Integraties"). --- ## Source: https://docs.popapi.io/nl/guides/getting-started/shopify-faq ## Doel Snel begrijpen wat POP voor Shopify wel en niet doet, voordat u in de afzonderlijke configuratiehandleidingen duikt. ## Voordat u begint **Berekent POP de belastingen bij het afrekenen?** Nee. Shopify blijft als enige verantwoordelijk voor het berekenen en toepassen van belastingen. POP gebruikt de belastinggegevens die in Shopify aanwezig zijn om documenten (PDF/XML, SdI/PEPPOL/KSeF) te genereren en te verzenden. **Waar configureer ik btw, OSS, markten en belastingregels?** Altijd in Shopify Admin (Markets, Tax regions). Controleer voor B2B waar van toepassing de belastinggegevens onder Company/Company Location. ## Belastinggegevens van de klant **Waar haalt POP de belastinggegevens van de klant vandaan?** Uit de bestel-/klant-metafields `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), met een terugval op de customAttributes van de bestelling. Details en prioriteit in [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **Worden de metafields automatisch aangemaakt?** Ja, zodra de wizard en de POP-licentie zijn voltooid, wordt geprobeerd de ontbrekende definities idempotent aan te maken. Als er iets ontbreekt, toont de startpagina een herstelsectie met een knop "Ontbrekende metafields aanmaken". ## Shopify Plus versus niet-Plus **Wat is het verschil in het verzamelen van belastinggegevens bij het afrekenen?** Op Shopify Plus is de native POP Checkout UI Extension beschikbaar. Bij niet-Plus-winkels worden de velden toegevoegd aan de winkelwagen/winkelwagenlade via een script dat in het thema is geplakt — zie [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **Ondersteunt POP zowel B2B- als B2C-scenario's?** Ja, beide; de fiscale juistheid van het document blijft afhankelijk van de kwaliteit van de in Shopify verzamelde gegevens. ## Italië, SdI en PEPPOL **Kunnen de native Shopify-velden Tax Code/PEC uit het afrekenproces worden verwijderd?** Nee, Shopify past deze native toe voor Italië en ze kunnen niet door POP worden verwijderd of gewijzigd. Ze blijven optioneel; ze uitschakelen vereist een verzoek aan de Shopify-support. **Kan ik naar de SdI verzenden met een winkel waarvan de valuta niet EUR is?** Nee. SdI-stromen vereisen dat de hoofdvaluta van de Shopify-winkel EUR is. **Is PEPPOL beschikbaar voor particuliere klanten?** Nee. Automatische verzending naar PEPPOL slaat particuliere klanten (B2C) altijd over; het downloaden van de PDF als beleefdheidsdocument blijft beschikbaar. Details in [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **Valideert POP het btw-nummer?** Ja, via de officiële VIES-dienst. De uiteindelijke fiscale beslissing over de toepassing van btw blijft bij de Shopify-configuratie liggen. ## Abonnementen en limieten **Hoeveel documenten kan ik per maand genereren?** Dat hangt af van het actieve abonnement: Free 20/maand, Basic 40/maand, Growth 100/maand, Pro 400/maand, Enterprise 2000/maand. Bij overschrijding van de limiet toont het genereren een waarschuwing met een link om te upgraden. ## Snelle probleemoplossing **Ik zie niet alle fiscale velden bij de bestelling/klant:** 1. Controleer of de wizard en de POP-licentie zijn voltooid. 2. Controleer of de `pop_*`-metafields zijn aangemaakt (gebruik anders de knop voor opnieuw aanmaken op de startpagina). 3. Controleer de checkout-/themaconfiguratie. 4. Controleer Markets/Tax in Shopify Admin. **De belastingen op de factuur komen niet overeen met de verwachtingen:** 1. Controleer de Shopify-belastingregels. 2. Controleer het klanttype en de opgeslagen fiscale gegevens. 3. Controleer op een mislukte btw-validatie. 4. Controleer het verzendkanaal (SdI/PEPPOL/KSeF) en de specifieke beperkingen daarvan. ## Gerelateerde configuratie Begin voor meer diepgang met [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) en [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/nl/guides/integrations/peppol ## Doel Het verzenden van elektronische facturen via het PEPPOL-netwerk rechtstreeks vanuit uw WordPress- of Shopify-winkel activeren. ## Vereisten - Op WordPress: geen minimumabonnement, activering en verzending zijn beschikbaar op elk abonnement (ook Free), op basis van credits. Op Shopify is nog steeds het **Basic-abonnement of hoger** vereist. - Een volledig adres (straat, plaats, postcode) voor de rechtspersoon — PEPPOL vereist deze velden om het endpoint te registreren. - Voor Duitsland: u moet expliciet de "documentcorridor" kiezen (`zugferd` of `peppol`) — zonder deze keuze kan de activering niet worden voltooid. ## Stappen U kunt PEPPOL op drie gelijkwaardige manieren activeren: 1. **Accountpaneel** — ga op `popapi.io` naar **Mijn account > Integraties**, open het PEPPOL-tabblad en schakel **"PEPPOL activeren"** in. 2. **Vanuit de plugin/app, met een bestaand account** — in WordPress: het tabblad **Algemeen**, ververs de licentiegegevens en ga vervolgens naar **Integraties** en klik op de PEPPOL-kaart om te activeren. 3. **Geleide installatiewizard bij eerste toegang** — als u het account voor het eerst instelt en uw land gebruikmaakt van de PEPPOL-corridor, gebeurt de activering automatisch zodra de wizard is voltooid. ## Automatisch verzenden - **WordPress** — het tabblad **Geavanceerd > Automatische factuurverzending**: schakel verzending via WP-Cron op de achtergrond in. - **Shopify** — automatisch verzenden bij betaalde bestellingen is beschikbaar op betaalde abonnementen; het staat standaard uit voor particuliere klanten (PEPPOL is een B2B-corridor). ## Handmatig verzenden Gebruik de knop **"Factuur verzenden"** in de facturentabel om één document naar het PEPPOL-netwerk te verzenden. ## Veelvoorkomende fouten - **"This field is required when PEPPOL is enabled."** — het adres, de plaats of de postcode van de rechtspersoon ontbreekt: vul deze aan in het accountpaneel voordat u het opnieuw probeert. - **Activering geblokkeerd voor Duitsland** — voor `DE`-accounts moet u de documentcorridor (`zugferd` of `peppol`) kiezen voordat de activering slaagt. - **Automatisch verzenden start niet bij een particuliere klant** — verwacht gedrag: PEPPOL is bedoeld voor zakelijke ontvangers, automatisch verzenden naar particuliere klanten staat standaard uit. ## Gerelateerde configuratie Voor de details van het API-contract (payload, UBL-veldmapping), zie [api/peppol](../../api/peppol.md). --- ## Source: https://docs.popapi.io/nl/guides/integrations/webhook ## Doel Elk door POP gegenereerd document (XML of PDF) automatisch verzenden naar een externe tool: Zapier, Make (Integromat), een CRM, Google Drive of een aangepast endpoint. ## Vereisten - POP **Basic-abonnement of hoger** — webhook-aflevering is niet beschikbaar in het gratis abonnement. - Een luisterend HTTP-endpoint (de doel-webhook-URL). ## Stappen 1. Ga op `popapi.io` naar **Mijn account > Integraties > POP to Webhook > Verbinden**. 2. Configureer: - een herkenbare naam - de doel-webhook-URL - het gegevensformaat: **JSON** of **XML** - de activeringsschakelaar 3. Op **WordPress**: ga in de POP-plugin naar **Geavanceerd > Webhook**, voer de in de vorige stap aangemaakte webhook-ID in, schakel deze in en schakel — als u verzending op de achtergrond wilt in plaats van synchroon — ook automatische verzending via CRON in. 4. Op **Shopify**: voer de webhook-ID in bij de app-instellingen; er verschijnt dan een icoon in de factureringslijst om de gegevens te verzenden. ## Formaten - **JSON** — ontworpen voor no-code-platforms (Zapier, Make): de gegevens worden automatisch platgeslagen tot een structuur die eenvoudig te mappen is. - **XML** — geschikt voor archivering of systemen die de FatturaPA-standaard vereisen; kan ook als bijlage worden verzonden. U kunt meerdere webhooks met verschillende URL's en formaten tegelijk configureren. ## Veelvoorkomende fouten - **Ongeldige webhook-URL** — controleer of de URL publiekelijk bereikbaar is en succesvol reageert (syntactisch correct zijn is niet voldoende). - **Niet-ondersteund gegevensformaat** — gebruik alleen `JSON` of `XML`; andere formaten worden geweigerd. - **De webhook ontvangt niets in de sandbox** — verwachte beperking: webhook-aflevering is niet beschikbaar in de sandbox-omgeving (zie [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Gerelateerde configuratie Voor het specifieke geval van doorsturen naar n8n met een dedicated connector (bijv. Zoho), zie [api/connectors](../../api/connectors.md) en [n8n](n8n.md). --- ## Source: https://docs.popapi.io/pl/guides/getting-started/choosing-an-invoicing-integration ## Cel Zrozumienie, który kanał transmisji aktywować dla Twojego sklepu, spośród dostępnych w POP. **Kanały wzajemnie się wykluczają**: w danym momencie może być aktywny tylko jeden (aktywacja jednego automatycznie dezaktywuje pozostałe). ## Dostępne kanały | Kanał | Dla kogo | Zależności zewnętrzne | Uwagi | | --- | --- | --- | --- | | **SdI via POP** | Dla tych, którzy chcą najprostszego przepływu dla Włoch: brak zewnętrznej usługi do konfiguracji | Brak | Bezpośrednia transmisja do SdI, powiadomienia obsługiwane w POP, automatyczna weryfikacja kodu podatkowego/numeru VAT odbiorcy. | | **SdI via PEC** | Niskie wolumeny, dla tych, którzy mają już skrzynkę PEC (certyfikowaną pocztę) i nie chcą dodatkowych kont zewnętrznych | Skrzynka PEC | Plik XML jest wysyłany e-mailem PEC; powiadomienia o wyniku trzeba sprawdzać ręcznie w skrzynce PEC — nie są obsługiwane automatycznie przez POP. | | **Fatture in Cloud** | Dla tych, którzy już korzystają z Fatture in Cloud do księgowości/fakturowania | Aktywna subskrypcja Fatture in Cloud | Odbywa się przez oficjalne API Fatture in Cloud; wymaga zmapowania [metod płatności](../integrations/fatture-in-cloud-payment-methods.md) i konta bilansowego przed pierwszym wysłaniem. | | **Aruba Business** | Dla tych, którzy już korzystają z Aruby jako dostawcy fakturowania elektronicznego | Aktywacja API w Arubie | Mniejsza elastyczność konfiguracji niż pozostałe opcje. | | **PEPPOL** | Sprzedaż B2B za granicę (sieć PEPPOL) | Brak | Nie jest alternatywą dla SdI dla Włoch: to korytarz dla wewnątrzunijnego fakturowania elektronicznego. Obejmuje 28 krajów (pełna lista w [api/peppol](../../api/peppol.md)) — **Hiszpania jest wyłączona** (korytarz Facturae, jeszcze nieobsługiwany), podobnie jak Irlandia Północna i Liechtenstein. | | **KSeF** | Sprzedaż do Polski | Polski NIP | Zobacz [aktywację KSeF](../integrations/ksef.md) — wymaga dedykowanej rejestracji, oddzielnej od SdI/PEPPOL. | | **Zoho (natywny)** | Dla tych, którzy używają Zoho Invoice/Zoho Books i chcą synchronizacji zarządzanej bezpośrednio przez POP | Autoryzacja OAuth do Zoho | Zobacz [aktywację Zoho](../integrations/zoho.md). Nie wymaga własnej instancji n8n. Dla kont zarejestrowanych w Zjednoczonych Emiratach Arabskich, Arabii Saudyjskiej, Bahrajnie, Kuwejcie, Omanie lub Katarze jest to **jedyny** dostępny kanał: kraje te nie mają obsługiwanej oficjalnej sieci fakturowania elektronicznego (brak SdI/PEPPOL/KSeF). | Jeśli wolisz samodzielnie zarządzać logiką synchronizacji we własnej instancji n8n hostowanej lokalnie (więcej kontroli/personalizacji), istnieje też dedykowany pakiet — zobacz [synchronizację z Zoho przez n8n](../integrations/n8n-zoho.md). ## Jak wybrać - **Sprzedajesz wyłącznie we Włoszech i nie korzystasz jeszcze z zewnętrznego systemu księgowego** → SdI via POP: to ścieżka z najmniejszą liczbą kroków konfiguracyjnych, a powiadomienia pozostają w POP. - **Korzystasz już z Fatture in Cloud lub Aruby do księgowości** → połącz tę integrację zamiast duplikować dane w innym miejscu, ale zaplanuj czas na uzupełnienie wymaganego mapowania (konta, metody płatności). - **Bardzo mało dokumentów miesięcznie i chcesz zero dodatkowych kosztów/usług** → SdI via PEC, wiedząc, że wyniki trzeba będzie sprawdzać ręcznie w skrzynce PEC. - **Twój sklep ma siedzibę we Włoszech lub San Marino** → pozostań przy SdI (przez POP lub przez PEC), również dla zagranicznych klientów biznesowych: PEPPOL nigdy nie jest w tym przypadku aktywowany, niezależnie od kraju klienta. Faktury dla zagranicznych klientów nadal przechodzą przez SdI, z konwencjonalnym kodem odbiorcy dla odbiorców spoza Włoch. - **Twój sklep ma siedzibę w kraju UE innym niż Włochy/San Marino, objętym siecią PEPPOL** (pełna lista w [api/peppol](../../api/peppol.md)) i sprzedajesz B2B → użyj PEPPOL: to kanał równoważny SdI dla fakturowania elektronicznego w tych krajach. - **Sprzedajesz do Polski** → potrzebujesz KSeF, niezależnie od kanału wybranego dla Włoch. - **Twoje konto jest zarejestrowane w Zjednoczonych Emiratach Arabskich, Arabii Saudyjskiej, Bahrajnie, Kuwejcie, Omanie lub Katarze** → natywny Zoho jest jedyną opcją: dla tych krajów nie ma dostępnego innego kanału. ## Warto wiedzieć - Jednoczesna aktywacja SdI via POP i PEPPOL nie jest obsługiwana: jeśli oba okażą się aktywne, pierwszeństwo ma ostatnio aktywowany, a drugi zostaje automatycznie dezaktywowany. - Kanał można zmienić później, ale konfigurację nowego kanału (dane uwierzytelniające, mapowania) trzeba wykonać od nowa — nie ma automatycznej migracji danych między jedną integracją a drugą. ## Powiązana konfiguracja Szczegóły aktywacji każdego kanału znajdziesz w dedykowanych przewodnikach w tej samej sekcji („Integracje"). --- ## Source: https://docs.popapi.io/pl/guides/getting-started/shopify-faq ## Cel Szybkie zorientowanie się, co POP dla Shopify robi (a czego nie robi), zanim przejdziesz do poszczególnych przewodników konfiguracyjnych. ## Zanim zaczniesz **Czy POP oblicza podatki przy kasie?** Nie. Wyłączną odpowiedzialność za obliczanie i naliczanie podatków ponosi Shopify. POP wykorzystuje dane podatkowe obecne w Shopify do generowania i wysyłania dokumentów (PDF/XML, SdI/PEPPOL/KSeF). **Gdzie konfiguruję VAT, OSS, rynki i reguły podatkowe?** Zawsze w Shopify Admin (Markets, Tax regions). W przypadku B2B sprawdź dane podatkowe w Company/Company Location, jeśli dotyczy. ## Dane podatkowe klienta **Skąd POP pobiera dane podatkowe klienta?** Z metapól zamówienia/klienta `app.pop_*` (`pop_customer_type`, `pop_vat`, `pop_tax_code`, `pop_pec`), z zapasowym źródłem w postaci customAttributes zamówienia. Szczegóły i priorytet w [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md). **Czy metapola są tworzone automatycznie?** Tak, po ukończeniu kreatora i licencji POP system próbuje w sposób idempotentny utworzyć brakujące definicje. Jeśli czegoś brakuje, strona główna wyświetla sekcję odzyskiwania z przyciskiem „Utwórz brakujące metapola". ## Shopify Plus a wersja bez Plus **Jaka jest różnica w zbieraniu danych podatkowych przy kasie?** W Shopify Plus dostępne jest natywne rozszerzenie POP Checkout UI Extension. W sklepach bez Plus pola są dodawane do koszyka/panelu koszyka za pomocą skryptu wklejonego w motywie — zobacz [shopify-non-plus-billing-fields](../configuration/shopify-non-plus-billing-fields.md). **Czy POP obsługuje zarówno scenariusze B2B, jak i B2C?** Tak, oba; poprawność podatkowa dokumentu nadal zależy od jakości danych zebranych w Shopify. ## Włochy, SdI i PEPPOL **Czy natywne pola Shopify Tax Code/PEC można usunąć z kasy?** Nie, Shopify stosuje je natywnie dla Włoch i nie mogą one zostać usunięte ani zmodyfikowane przez POP. Pozostają opcjonalne; ich wyłączenie wymaga zgłoszenia do wsparcia Shopify. **Czy mogę wysyłać do SdI ze sklepem, którego walutą nie jest EUR?** Nie. Procesy SdI wymagają, aby główną walutą sklepu Shopify było EUR. **Czy PEPPOL jest dostępny dla klientów prywatnych?** Nie. Automatyczna wysyłka do PEPPOL zawsze pomija klientów prywatnych (B2C); pobranie PDF jako dokumentu grzecznościowego pozostaje dostępne. Szczegóły w [shopify-reverse-charge](../configuration/shopify-reverse-charge.md). **Czy POP weryfikuje numer VAT?** Tak, za pośrednictwem oficjalnej usługi VIES. Ostateczna decyzja podatkowa dotycząca naliczenia VAT nadal zależy od konfiguracji Shopify. ## Plany i limity **Ile dokumentów mogę wygenerować miesięcznie?** Zależy to od aktywnego planu: Free 20/miesiąc, Basic 40/miesiąc, Growth 100/miesiąc, Pro 400/miesiąc, Enterprise 2000/miesiąc. Po przekroczeniu limitu generowanie wyświetla ostrzeżenie z linkiem do uaktualnienia planu. ## Szybkie rozwiązywanie problemów **Nie widzę wszystkich pól podatkowych przy zamówieniu/kliencie:** 1. Sprawdź, czy kreator i licencja POP zostały ukończone. 2. Sprawdź, czy metapola `pop_*` zostały utworzone (jeśli nie, użyj przycisku ponownego tworzenia na stronie głównej). 3. Sprawdź konfigurację kasy/motywu. 4. Sprawdź Markets/Tax w Shopify Admin. **Podatki na fakturze nie odpowiadają oczekiwaniom:** 1. Sprawdź reguły podatkowe Shopify. 2. Sprawdź typ klienta i zapisane dane podatkowe. 3. Sprawdź, czy nie doszło do błędu walidacji VAT. 4. Sprawdź kanał transmisji (SdI/PEPPOL/KSeF) i jego specyficzne ograniczenia. ## Powiązana konfiguracja Aby dowiedzieć się więcej, zacznij od [shopify-fiscal-data-management](../configuration/shopify-fiscal-data-management.md) oraz [shopify-checkout-vat-tax-code-fields](../configuration/shopify-checkout-vat-tax-code-fields.md). --- ## Source: https://docs.popapi.io/pl/guides/integrations/ksef ## Cel Połączenie konta POP z systemem KSeF (Polska) w celu wysyłania elektronicznych faktur FA(3). ## Wymagania wstępne - Konto POP z planem **Basic lub wyższym**. - **NIP** ustawiony w danych konta. - **Środowisko produkcyjne**: dostęp do `podpis.gov.pl` z Profilem Zaufanym lub certyfikat PKI KSeF (`PKCS#12` lub `PEM`). - **Środowisko testowe (sandbox)**: brak wymagań wstępnych — podpis jest symulowany automatycznie. Środowisko produkcyjne i testowe to **osobne** rejestracje: aktywacja środowiska testowego nie aktywuje automatycznie produkcyjnego i odwrotnie. ## Kroki (panel konta) 1. **Zarejestruj podmiot prawny** — adres, miasto, kod pocztowy, e-mail do powiadomień. NIP i zarejestrowana nazwa firmy są odczytywane automatycznie z ustawień konta, nie trzeba ich wpisywać ponownie. 2. **Autoryzuj dostęp**: - **Sandbox** — kliknij „Rozpocznij autoryzację" (okno 10-minutowe), następnie „Aktywuj". - **Produkcja z Profilem Zaufanym** — pobierz plik podpisu, podpisz go na `podpis.gov.pl`, prześlij podpisany plik XML, następnie kliknij „Aktywuj". - **Produkcja z certyfikatem PKI** — prześlij nazwę certyfikatu, hasło i plik certyfikatu. 3. **Aktywne połączenie** — od tego momentu możesz wysyłać faktury KSeF za pośrednictwem API POP. Jeśli uzyskujesz dostęp po raz pierwszy przy użyciu polskiego konta (`PL`), aktywacja może również nastąpić z poziomu kreatora konfiguracji, z tymi samymi dwoma krokami (rejestracja + autoryzacja). ## Koszt w kredytach Każdy dokument KSeF zużywa **2 kredyty**: 1 za generowanie XML i 1 za dostarczenie. ## Odłączanie - **Odłącz** — wstrzymuje wysyłkę, zachowując rejestrację (można ją później ponownie aktywować). - **Usuń połączenie** — usuwa również lokalne dane rejestracji. ## Typowe błędy - **„KSeF Legal Entity is missing."** — podmiot prawny nie został zarejestrowany (krok 1) przed wygenerowaniem/wysłaniem dokumentu: dokończ rejestrację w panelu konta. - **Onboarding KSeF nieukończony** — brakuje NIP-u lub danych konta: sprawdź ustawienia przed kontynuowaniem autoryzacji. - **Sandbox aktywny, ale nie następuje żadna rzeczywista wysyłka** — oczekiwane zachowanie: środowisko testowe nie dostarcza faktycznie do KSeF, do rzeczywistej wysyłki trzeba przełączyć się na środowisko produkcyjne. ## Powiązana konfiguracja Szczegóły kontraktu API (payload, mapowanie pól FA(3)) znajdziesz w [api/ksef](../../api/ksef.md). --- ## Source: https://docs.popapi.io/pl/guides/integrations/webhook ## Cel Automatyczne wysyłanie każdego dokumentu wygenerowanego przez POP (XML lub PDF) do zewnętrznego narzędzia: Zapier, Make (Integromat), CRM, Google Drive lub niestandardowego endpointu. ## Wymagania wstępne - Plan POP **Basic lub wyższy** — dostarczanie przez webhook nie jest dostępne w planie darmowym. - Nasłuchujący endpoint HTTP (docelowy adres URL webhooka). ## Kroki 1. Na `popapi.io` przejdź do **Moje konto > Integracje > POP to Webhook > Połącz**. 2. Skonfiguruj: - nazwę identyfikującą - docelowy adres URL webhooka - format danych: **JSON** lub **XML** - przełącznik aktywacji 3. W **WordPressie**: we wtyczce POP przejdź do **Zaawansowane > Webhook**, wpisz identyfikator webhooka utworzony w poprzednim kroku, włącz go i — jeśli chcesz wysyłkę w tle zamiast synchronicznej — włącz również automatyczną wysyłkę przez CRON. 4. W **Shopify**: wpisz identyfikator webhooka w ustawieniach aplikacji; na liście faktur pojawi się ikona umożliwiająca wysłanie danych. ## Formaty - **JSON** — zaprojektowany dla platform no-code (Zapier, Make): dane są automatycznie spłaszczane do struktury łatwej do zmapowania. - **XML** — odpowiedni do archiwizacji lub systemów wymagających standardu FatturaPA; można go też wysłać jako załącznik. Możesz jednocześnie skonfigurować wiele webhooków z różnymi adresami URL i formatami. ## Typowe błędy - **Nieprawidłowy adres URL webhooka** — sprawdź, czy adres URL jest publicznie dostępny i odpowiada poprawnie (samo poprawnej składni nie wystarczy). - **Nieobsługiwany format danych** — używaj wyłącznie `JSON` lub `XML`; inne formaty są odrzucane. - **Webhook nic nie odbiera w środowisku testowym** — oczekiwane ograniczenie: dostarczanie przez webhook nie jest dostępne w środowisku sandbox (zobacz [use-sandbox-environment](../configuration/use-sandbox-environment.md)). ## Powiązana konfiguracja W przypadku przekazywania do n8n za pomocą dedykowanego konektora (np. Zoho), zobacz [api/connectors](../../api/connectors.md) oraz [n8n](n8n.md). --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-09) ### POP API The email onboarding flow is lighter, one step at a time instead of a checklist, and accounts that generate documents without finishing activation now get a reminder a few days later. Fixed a block that stopped Free-plan accounts from generating ZUGFeRD and Facturae credit notes, and PEPPOL delivery to Belgian recipients now automatically picks the right identifier for the recipient. ### POP for WordPress Several important security fixes protect invoices, downloads and account settings from unauthorized actions, and a bug that completely blocked document generation for shops outside Italy and Spain is fixed. Bulk XML/CSV download works again on every plan, including Free, and German shops can choose between PEPPOL and ZUGFeRD/Factur-X without connecting a POP account first. The same codebase also gives birth to **POP for Belgium**, the first channel-vertical plugin dedicated entirely to PEPPOL, submitted to WordPress.org today. ### POP for Shopify Duplicate-send protection now covers every channel (SdI, PEPPOL, KSeF, Zoho), not just SdI: an accidental double-click or a slow retry can no longer create a second submission. Zoho sync is available again on every eligible plan, and numbering stays consistent even when a failed generation attempt is retried. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-08) ### POP API From this month you can generate invoices, credit notes and PDFs without a POP account at all, up to 1000 free generations a month; an account is only needed to actually send a document through a channel. Every sending channel, including Zoho, is now available on every plan starting from Free, and French merchants can register directly with the public gov-fr platform in beta instead of going through generic PEPPOL. ### POP for WordPress The same "generate without an account" approach lands in the plugin too, with a new guided wizard replacing the external popup and every channel available from the Free plan. Also fixed an Aruba connection-status issue that could show as "connected" before login had actually completed. ### POP for Shopify Invoice and credit note status shown in external reporting tools like Report Pundit now updates correctly for PEPPOL, KSeF and Zoho, not just SdI. Manually editing a document's number before it's sent is also now correctly reflected in the reporting fields. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-07) ### POP API Native Zoho integration debuts, with a choice between creating invoices as Draft or Sent and control over whether missing customers are created automatically. PEPPOL support expands to 23 more European countries, and a dedicated channel opens for Gulf markets, such as the UAE, that have no official e-invoicing network. ### POP for WordPress Invoice documents become queryable by AI agents and automation tools through WordPress Abilities and WP-CLI, and Zoho can now become the store's exclusive invoicing channel right from the Integrations page. Also fixed a bulk XML download bug that produced incomplete invoices. ### POP for Shopify The app becomes fully available in Polish, with local fiscal terminology instead of a literal translation. In the same release, merchants can connect Zoho Books as their invoice channel and have invoices and credit notes sent automatically when an order is paid. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-06) ### POP API German ZUGFeRD/Factur-X e-invoicing support arrives: a single call returns the PDF, the EN16931 XML, and the hybrid PDF ready for Germany's mandatory e-invoicing shift. KSeF onboarding for Poland can now be completed straight from the wizard, and POP starts sending automatic emails at the key moments of the account journey, in the user's own language. ### POP for WordPress German shops can now generate and deliver ZUGFeRD invoices directly from WooCommerce, automatically attached to the completed-order email. Polish shops can send KSeF invoices from the order screen, with automatic sending on status change. ### POP for Shopify A complete ZUGFeRD bundle is downloadable in one click from the Orders page for German shops, and Polish invoices can now be sent to KSeF automatically on payment, with status tracked in real time. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-05) ### POP API Polish e-invoicing support via KSeF debuts, together with a dedicated route to test API credentials before going live. A new sandbox environment also arrives for testing SDI, PEPPOL, KSeF and PDF generation without spending credits, with semantic KSeF tax variants, VAT-number-based EU customer validation, and clearer validation error messages. ### POP for WordPress Paid Memberships Pro refunds become more robust: invoices and credit notes are now separate documents with the correct SdI/PEPPOL actions, alongside provider-aware admin search and assets that stay up to date without reloading the plugin. For Poland, KSeF shops now generate and store XML on the dedicated route, with simpler handling of reverse charge and extra-EU exports. The SdI/PEPPOL panel also splits Live and Sandbox status into two separate sections, and Fatture in Cloud invoices now pick up updated VAT rates automatically. ### POP for Shopify Invoice calculation precision improves for multi-quantity orders, reducing PEPPOL and SdI rejections. A sandbox mode arrives for generating test documents without sending them for real, with a live/sandbox switch always visible on the Orders page, plus KSeF XML download for Polish invoices and credit notes. SdI and PEPPOL sending also becomes more reliable during brief connection hiccups with POP, and a new Settings panel lets you check status and company details without leaving the app. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-04) ### POP API Full OSS sales support lands for the European Union, with foreign VAT on invoices now handled automatically, and the overquota system becomes more hands-off with automatic payments and email notifications. Also fixed an overquota billing edge case on Paid Memberships Pro sites offering the same plan both monthly and yearly, where an extra charge could occasionally be attributed to the wrong plan variant. --- ## Source: https://docs.popapi.io/en/release-notes/ (release-notes/2026-03) ### POP API Overquota handling improves, and PDF invoice support expands to Belgium, the Netherlands, Germany and France, with every generated PDF invoice now delivered automatically by email. A handful of VAT calculation and rounding edge cases are also fixed. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-09) ### POP API Il flusso di onboarding via email è più leggero, con un passo alla volta invece di una checklist, e chi genera documenti senza completare l'attivazione riceve un promemoria qualche giorno dopo. Corretto un blocco che impediva ai piani Free di generare note di credito ZUGFeRD e Facturae, e il recapito PEPPOL verso il Belgio sceglie ora automaticamente l'identificativo giusto del destinatario. ### POP per WordPress Diverse correzioni di sicurezza importanti proteggono fatture, download e impostazioni account da azioni non autorizzate, ed è stato risolto un bug che bloccava del tutto la generazione documenti per i negozi fuori da Italia e Spagna. Il download massivo XML/CSV torna a funzionare su tutti i piani, incluso Free, e i negozi tedeschi possono scegliere tra PEPPOL e ZUGFeRD/Factur-X senza collegare prima un account POP. Dallo stesso codice nasce anche **POP per il Belgio**, il primo plugin verticale dedicato interamente al canale PEPPOL, sottoposto oggi a WordPress.org. ### POP per Shopify La protezione contro invii duplicati è estesa a tutti i canali (SdI, PEPPOL, KSeF, Zoho), non solo a SdI: un doppio clic o un tentativo lento non può più creare una seconda trasmissione. La sincronizzazione con Zoho è di nuovo disponibile su tutti i piani idonei, e la numerazione resta coerente anche quando un tentativo di generazione fallisce e viene ripetuto. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-08) ### POP API Da questo mese si possono generare fatture, note di credito e PDF anche senza un account POP, fino a 1000 generazioni gratuite al mese: l'account serve solo per inviare davvero un documento tramite un canale. Tutti i canali di invio, incluso Zoho, sono ora disponibili su ogni piano a partire da Free, e i commercianti francesi possono registrarsi direttamente sulla piattaforma pubblica gov-fr in beta invece di passare dal PEPPOL generico. ### POP per WordPress La stessa filosofia "genera senza account" arriva anche nel plugin, con un nuovo wizard guidato che sostituisce il popup esterno e ogni canale disponibile fin dal piano Free. Risolto anche un problema sullo stato di connessione Aruba, che poteva risultare "connesso" prima che il login fosse davvero completato. ### POP per Shopify Lo stato di fatture e note di credito mostrato negli strumenti di reporting esterni come Report Pundit si aggiorna ora correttamente per PEPPOL, KSeF e Zoho, non solo per SdI. Anche una modifica manuale al numero di un documento prima dell'invio si riflette correttamente nei campi di reporting. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-07) ### POP API Debutta l'integrazione nativa con Zoho, con la scelta se creare le fatture come bozza o già inviate e il controllo su chi crea automaticamente i clienti mancanti. Il supporto PEPPOL si allarga a 23 nuovi paesi europei e si apre un canale dedicato ai mercati del Golfo, come gli Emirati, privi di una rete di fatturazione elettronica ufficiale. ### POP per WordPress I documenti fattura diventano consultabili anche da agenti AI e strumenti di automazione tramite WordPress Abilities e WP-CLI, e Zoho può diventare il canale di fatturazione esclusivo del negozio direttamente dalla pagina Integrazioni. Risolto anche un bug sul download bulk XML che produceva fatture incomplete. ### POP per Shopify L'app diventa disponibile integralmente in polacco, con terminologia fiscale locale invece di una traduzione letterale. Nella stessa release, i merchant possono collegare Zoho Books come canale di fatturazione e ricevere fatture e note di credito inviate automaticamente al pagamento dell'ordine. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-06) ### POP API Arriva il supporto per la fatturazione elettronica tedesca ZUGFeRD/Factur-X: un'unica chiamata restituisce PDF, XML EN16931 e il PDF ibrido pronto per l'obbligo tedesco. L'onboarding KSeF per la Polonia si completa direttamente dal wizard, e POP inizia a inviare email automatiche nei momenti chiave del percorso account, nella lingua dell'utente. ### POP per WordPress I negozi tedeschi generano e consegnano fatture ZUGFeRD direttamente da WooCommerce, allegate automaticamente all'email dell'ordine completato. I negozi polacchi inviano fatture KSeF dalla pagina ordini, con invio automatico al cambio di stato. ### POP per Shopify Bundle ZUGFeRD completo scaricabile in un click dalla pagina Ordini per i negozi tedeschi, e le fatture polacche possono ora essere inviate a KSeF automaticamente al pagamento, con stato tracciato in tempo reale. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-05) ### POP API Debutta il supporto per la fatturazione elettronica polacca via KSeF, insieme a una rotta dedicata per testare le credenziali API prima di andare live. Arriva anche un nuovo ambiente sandbox per testare SDI, PEPPOL, KSeF e la generazione PDF senza consumare crediti, con varianti fiscali semantiche per KSeF, validazione del cliente UE basata sulla partita IVA e messaggi di errore più chiari. ### POP per WordPress I rimborsi Paid Memberships Pro diventano più solidi: fattura e nota di credito sono ora documenti separati con le azioni SdI/PEPPOL corrette, oltre a una ricerca admin più consapevole del provider e asset sempre aggiornati senza dover ricaricare il plugin. Per la Polonia, i negozi KSeF generano e archiviano ora gli XML sulla rotta dedicata, con gestione più semplice di reverse charge ed export extra-UE. Il pannello SdI/PEPPOL separa inoltre gli stati Live e Sandbox in due sezioni distinte, e le fatture Fatture in Cloud recuperano automaticamente le aliquote IVA aggiornate. ### POP per Shopify Migliora la precisione di calcolo delle fatture con più quantità, riducendo gli scarti PEPPOL e SdI. Arriva una modalità sandbox per generare documenti di prova senza inviarli davvero, con un interruttore live/sandbox sempre visibile nella pagina Ordini, oltre al download delle fatture e note di credito polacche in XML KSeF. Invio SdI e PEPPOL più affidabile anche durante brevi interruzioni di connessione con POP, e un nuovo pannello nelle impostazioni per verificare stato e dati aziendali senza uscire dall'app. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-04) ### POP API Arriva il supporto completo alla vendita OSS nell'Unione Europea, con gestione automatica dell'IVA estera in fattura, e il sistema di overquota diventa più autonomo grazie a pagamenti e notifiche email automatici. Corretto anche un caso limite di fatturazione overquota sui siti Paid Memberships Pro che offrono lo stesso piano in versione mensile e annuale, dove l'addebito extra poteva finire attribuito alla variante di piano sbagliata. --- ## Source: https://docs.popapi.io/it/release-notes/ (release-notes/2026-03) ### POP API Migliora la gestione dell'overquota e il supporto PDF si estende a Belgio, Paesi Bassi, Germania e Francia, con invio automatico via email di ogni fattura PDF generata. Vengono inoltre corretti alcuni casi di calcolo e arrotondamento IVA.