Scegliere il corridoio documentale per la Germania (ZUGFeRD o PEPPOL)

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): 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 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.