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:
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 release 1.3 è in member review fino al 15 aprile 2026, con pubblicazione prevista il 18 maggio 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.
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.
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