Configurare le capability SMP, la Peppol Directory e la businessCard tramite l'API PSB.
La PSB è un Peppol Access Point certificato e un SMP (Service Metadata Publisher). Tramite l'API si configurano i tipi di documento che un'organizzazione può ricevere, si pubblicano i dati aziendali nella Peppol Directory e si gestisce la registrazione SMP. Questo articolo tratta il contesto tecnico e gli endpoint API utilizzati a tale scopo.
Peppol funziona con un modello a 4 angoli: il mittente (C1) invia tramite il proprio Access Point (C2) un documento all'Access Point del destinatario (C3), che lo inoltra al destinatario (C4). Il routing avviene tramite due componenti centrali:
C1 Mittente
C2 Access Point mittente
SML / SMP
C3 Access Point destinatario
C4 Destinatario
SML/SMP lookup
Quando si invia una fattura tramite la PSB, questa esegue automaticamente un lookup SML/SMP per trovare l'Access Point corretto del destinatario. Come integratore non è necessario farlo autonomamente.
L'infrastruttura Peppol viene attivamente sviluppata. Per gli integratori che utilizzano l'API PSB questo non ha conseguenze: la PSB gestisce automaticamente i lookup SML/SMP. Di seguito gli sviluppi attuali a titolo informativo.
Insourcing SML. OpenPeppol assume la gestione dell'SML dalla Commissione Europea (DG DIGIT). La finestra di migrazione è stata aperta il 19 marzo 2026. Si applicano due scadenze separate: il termine per le registrazioni SMP è il 31 maggio 2026, il periodo di migrazione per l'AP Lookup (risoluzione DNS) è stato esteso fino al 31 agosto 2026. OpenPeppol sta discutendo con la Commissione Europea se anche il termine per le registrazioni SMP possa essere esteso. Per gli integratori API non cambia nulla negli endpoint o nei lookup: la PSB gestisce la migrazione internamente.
Migrazione da CNAME a NAPTR. La migrazione dei record DNS CNAME ai record NAPTR per i lookup SML è stata completata a marzo 2026. NAPTR è obbligatorio dal 1 febbraio 2026. I vecchi record CNAME sono stati rimossi dalla rete di test SMK (4 marzo 2026) e dalla rete di produzione SML (11 marzo 2026). Si tratta di una modifica DNS interna nell'infrastruttura Peppol. La PSB utilizza già NAPTR e non sono necessari adattamenti all'integrazione.
Migrazione PKI G3. OpenPeppol sta preparando la transizione dai certificati PKI Generation 2 (G2) a Generation 3 (G3). I certificati G3 vengono utilizzati per la comunicazione reciproca tra gli Access Point. Il Peppol Testbed supporta sia i certificati G2 che G3 da marzo 2026, in modo che i Service Provider possano testare in anticipo. Non è stata ancora pubblicata una data di transizione obbligatoria. Per gli integratori API non cambia nulla: la PSB gestisce il rinnovo dei certificati internamente.
Peppol supporta tipi di documento logistici oltre alle fatture tramite la specifica Peppol Logistics. La versione 1.2 è obbligatoria dal 16 marzo 2026. La versione 1.3 è obbligatoria dal 24 agosto 2026.
Documenti logistici supportati:
Novità nella release 1.3:
La release 1.3 risolve le RFC da LLC-27 a LLC-35, inclusi allineamento ItemInstance, aggiornamenti non di fatturazione e codici di sottotrattamento per rifiuti.
Alla registrazione di una party nell'SMP eConnect, tramite le capability si determinano i tipi di documento che quella party può ricevere. Ogni capability ha tre possibili stati:
onoffinheritedIl valore consigliato per le nuove registrazioni è inherited, a meno che una party non debba specificamente deviare dallo standard.
invoicesselfbillinginvoice_bisv2reviewsinvoiceResponseordersorderOnlyorderAdvancedorderResponseorderResponseAdvancedLe capability vengono configurate tramite l'endpoint Peppol config:
PUT /api/v1/peppol/config/party/{partyId}
Nel body della richiesta si specifica lo stato desiderato per ogni capability. Un esempio:
{
"capabilities": {
"invoices": "on",
"selfbilling": "inherited",
"invoiceResponse": "on",
"orderOnly": "on",
"orderAdvanced": "off"
}
}
La Peppol Directory è il registro pubblico di tutti i partecipanti Peppol. Pubblicando una businessCard, una party diventa reperibile nella directory. La businessCard contiene:
La businessCard viene pubblicata tramite l'endpoint Enrollment o tramite la configurazione SMP. Dopo la pubblicazione l'organizzazione è reperibile su directory.peppol.eu.
L'API PSB non deduce alcun campo da un registro delle imprese collegato. Indipendentemente dallo schema di identificatore (KvK 0106, IVA 9944, OIN 0190, GLN 0088 o un altro), sia names sia un address con codice paese devono essere esplicitamente presenti nel payload. Un esempio di businessCard configurata correttamente:
"businessCard": {
"names": {
"value": "eVerbinding, eConnect",
"state": "on",
"description": "Business names."
},
"address": {
"value": "Pelmolenlaan 16A, 3447 GW, Woerden, NL",
"state": "on",
"description": "Geographic information."
},
"emailAddress": {
"value": "techsupport@econnect.eu",
"state": "on",
"description": "Technical contact"
},
"state": "on"
}
Il codice paese (nell'esempio sopra, NL alla fine del campo address) deve essere esplicitamente incluso.
Both name(s) and country code are required when adding a business cardQuesto messaggio di errore è diagnosticamente inequivocabile: il payload inviato non contiene names, oppure il campo address non contiene un codice paese. La soluzione consiste sempre nell'aggiungere esplicitamente questi campi nel payload della businessCard, e non nel modificare un altro livello (party, identificatore, capability SMP). Il messaggio compare in pratica con relativa frequenza nell'integrazione GLN (0088), perché i partner di integrazione GLN utilizzano meno spesso un template che invia questi campi per impostazione predefinita. La PSB non mostra un comportamento diverso per GLN rispetto agli altri schemi.
La verifica preliminare che un destinatario sia raggiungibile su Peppol avviene per tipo di documento e tramite un endpoint di lookup avanzato:
POST /api/v1/{partyId}/salesInvoice/queryRecipientParty["0106:..."] oppure { "partyIds": [...], "metaAttributes": {...} }; parametri opzionali ?preferredDocumentTypeId, ?includeOptionsPOST /api/v1/{partyId}/purchaseOrder/queryRecipientParty?documentFamily=OrderGET /api/v1/peppol/deliveryOption?partyIds=...&documentFamily=...&isCredit=...partyId, documentTypeId, processId, protocol (As2/As4), url, certificateLa risposta mostra i canali disponibili, l'Access Point selezionato e i tipi di documento supportati. Utilizzi questi endpoint per validare preventivamente se un invio avrà successo. Sono disponibili in modo illimitato in tutti i piani (rilevamento/discovery proattivo dei percorsi).
Nota: in caso di mancata corrispondenza SML/SMP sull'endpoint
deliveryOption, la chiamata non fallisce immediatamente. Non è presente alcuna gestione fail-fast in produzione: la chiamata continua e restituisce un timeout dopo circa 30 secondi. Tenere conto di ciò nella gestione degli errori della propria integrazione.
Nella rete Peppol, un participantId nella SML punta a una sola SMP. Tramite un record Redirect nella SMP, combinazioni specifiche di tipo di documento e identificatore di processo possono essere reindirizzate a una SMP secondaria. Peppol supporta un solo livello di reindirizzamento: la destinazione di un redirect non può a sua volta contenere un redirect.
Fonti alternative per i lookup SMP: peppolautoriteit.nl/discover (NPa), peppol.helger.com e directory.peppol.eu (non completo).
Ogni party nell'SMP viene identificata tramite un identificativo con uno schemeID. Gli schemi più utilizzati:
01060106:1234567801900190:0000000123456789000099449944:NL123456789B010208BE:EN0208:01234567899925BE:VAT9925:BE0835689642 (anche BE1xxxxxxxxx è valido dal 2025)00880088:1234567890123L'API PSB accetta sia lo schemeID numerico sia il codice letterale: 9925:BE0835689642 è equivalente a BE:VAT:BE0835689642. Con strumenti di ricerca esterni (come l'SMP lookup), devono essere utilizzati gli schemeID numerici ufficiali.
Una party può avere più identificativi, ma ogni fattura può contenere un solo EndpointID.
In Belgio vengono utilizzati due tipi di identificativi per Peppol. Il numero d'impresa (KBO, schemeID 0208) è il numero di identificazione principale ed è obbligatorio per la ricezione Peppol. La registrazione sulla partita IVA (schemeID 9925) è facoltativa, per cui la ricerca di un'organizzazione belga tramite numero d'impresa ha più successo rispetto alla partita IVA.
Il numero d'impresa si ricava dalla partita IVA rimuovendo il prefisso del codice paese (BE). Ad esempio: la partita IVA BE0835689642 corrisponde al numero d'impresa 0835689642.
Durante l'invio di un documento, la PSB estrae l'identificativo Peppol dall'elemento EndpointID nel XML. Questo elemento determina a quale destinatario il documento viene instradato. Se l'EndpointID è assente o compilato in modo errato, il documento non è valido e riceve lo stato InvoiceSentError.
Un XML errato non viene automaticamente riprovato. La correzione spetta al sistema di origine (il pacchetto software che genera la fattura), non alla PSB. Verifichi preventivamente tramite queryRecipientParty se il destinatario è raggiungibile sulla rete Peppol.
Regola di validazione NLCIUS che richiede che lo schemeID del CompanyID abbia il valore 0190 (OIN) quando il destinatario è una parte pubblica. Sulla piattaforma, l'ID organizzazione e "Invia tramite" devono usare lo stesso tipo di identificativo. Una discrepanza produce un errore di validazione sul documento.
Quando un fornitore segnala che una fattura è stata consegnata a eConnect come Access Point, ma il destinatario indica di non aver ricevuto nulla, la diagnosi lato destinatario avviene tramite il returnedMessageId.
Il returnedMessageId è un ID creato da eConnect nel momento in cui l'Access Point accetta o rifiuta un documento a livello AS4. Ha in genere la forma GUID@econnect.eu. Con questo ID il supporto può cercare la fattura nel sistema e seguire il percorso di elaborazione.
Cause più frequenti per cui un documento è considerato "consegnato" dall'AP mittente ma non raggiunge il destinatario:
Percorso di supporto: con il returnedMessageId il supporto può recuperare quasi tutti i documenti tramite la Management API. Se la ricerca non riesce, il supporto coinvolge TechSupport.
Con on si abilita esplicitamente un tipo di documento per una party specifica, con off lo si disabilita esplicitamente. Il valore inherited significa che la party adotta la configurazione predefinita dell'organizzazione. Per le nuove registrazioni inherited è il valore consigliato, salvo che una party debba discostarsi in modo specifico.
No. La PSB esegue automaticamente i lookup SML/SMP all'invio dei documenti. Come integratore non è necessaria un'interazione diretta con SML o SMP. Anche le modifiche all'infrastruttura (migrazione da CNAME a NAPTR o insourcing della SML) non cambiano l'integrazione.
Una businessCard non è obbligatoria, ma consigliata. Senza businessCard la party resta raggiungibile via Peppol (la registrazione SMP è attiva), ma non è reperibile nella Peppol Directory su directory.peppol.eu. Pubblichi una businessCard per aumentare la visibilità dell'organizzazione.
L'API PSB non ricava valori da un registro delle imprese collegato. Indipendentemente dallo schema dell'identificativo (Camera di Commercio, IVA, OIN, GLN), a ogni pubblicazione di businessCard vanno inviati esplicitamente sia names sia un address con codice paese. Il messaggio indica sempre un campo names mancante o un address senza codice paese. La correzione è completare quei campi nel payload della businessCard; modifiche a livello di party, identificativo o capability SMP non risolvono l'errore.
Desidera automatizzare l'intero processo di registrazione? Consulti l'articolo sulla Enrollment API, con cui configurare registrazione, capability e hook in un'unica chiamata API.
Consulti gli endpoint SMP