Registrare organizzazioni su Peppol tramite l'Enrollment API: servizi, diritti e hook in un'unica chiamata.
L'Enrollment API è una soluzione completa per la registrazione di una nuova party sulla rete Peppol. In un'unica chiamata API si configura il servizio Peppol, si collegano gli utenti con i diritti appropriati e si impostano opzionalmente gli hook. Questo articolo descrive l'endpoint, le tre sezioni dell'enrollment e la rimozione di una registrazione.
L'Enrollment API richiede il ruolo ApManager. Un ApUser non può eseguire un enrollment. Verificare che le proprie credenziali API abbiano il ruolo corretto prima di iniziare.
PUT /api/v1-beta/{partyId}/enroll
Il {partyId} è l'identificativo Peppol della party da registrare, nel formato schemeID:identifier (ad es. 0106:12345678).
Il body della richiesta contiene tre sezioni: Services, Party authorizations e Hooks.
Nella sezione Services si attiva il servizio Peppol per la party. Si configurano le capability SMP (quali tipi di documento la party può ricevere) e opzionalmente una businessCard per la pubblicazione nella Peppol Directory.
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on",
"orderOnly": "inherited"
},
"businessCard": {
"names": "Bedrijfsnaam B.V.",
"geoInfo": "Utrecht, NL",
"email": "info@bedrijf.nl"
}
}
}
}
La businessCard è opzionale ma consigliata. Senza businessCard la party non è reperibile nella Peppol Directory, anche se la registrazione SMP è attiva.
Qui si collegano uno o più utenti alla party e si definiscono i loro diritti. Ogni party registrata deve essere collegata ad almeno un ApUser.
{
"partyAuthorizations": [
{
"userId": "gebruiker@bedrijf.nl",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": true,
"canManageHook": true
}
}
]
}
canSendDocumentcanReceiveDocumentcanRemoveDocumentcanManageHookOpzionalmente si possono registrare direttamente degli hook per la nuova party. Questo è utile se al momento della registrazione si sa già quali notifiche sono necessarie, ad esempio un webhook per le fatture ricevute.
{
"hooks": [
{
"action": "https://api.bedrijf.nl/webhooks/invoices",
"topics": ["InvoiceReceived"]
},
{
"action": "mailto:facturatie@bedrijf.nl",
"topics": ["InvoiceReceived"]
}
]
}
Una richiesta di enrollment completa che combina tutte e tre le sezioni:
{
"services": {
"peppol": {
"capabilities": {
"invoices": "on",
"invoiceResponse": "on"
},
"businessCard": {
"names": "Voorbeeld B.V.",
"geoInfo": "Amsterdam, NL"
}
}
},
"partyAuthorizations": [
{
"userId": "api-user@voorbeeld.nl",
"permissions": {
"canSendDocument": true,
"canReceiveDocument": true,
"canRemoveDocument": false,
"canManageHook": true
}
}
],
"hooks": [
{
"action": "https://api.voorbeeld.nl/leren/peppol/incoming",
"topics": ["InvoiceReceived"]
}
]
}
Per deregistrare completamente una party (inclusi tutti i servizi, i permessi e gli hook), utilizzare:
DELETE /api/v1-beta/{partyId}/enroll
Dopo la rimozione la party non è più raggiungibile sulla rete Peppol e tutti gli hook e le autorizzazioni collegati vengono rimossi.
L'Enrollment API è un endpoint beta (v1-beta). La funzionalità è stabile, ma l'endpoint potrebbe cambiare in versioni future. Per domande sullo stato beta è possibile contattare TechSupport.
Tenere anche presente che la registrazione SMP dopo l'enrollment potrebbe richiedere alcuni minuti prima della sincronizzazione sull'intera rete Peppol. Questo è inerente al protocollo SML/SMP.
Desidera migrare registrazioni esistenti da un altro provider? Legga l'articolo sulla migrazione verso eConnect.
Provi nell'API