Invio e ricezione di fatture con Peppol

Peppol è la rete europea per lo scambio di fatture elettroniche strutturate tra aziende e enti pubblici. Ciascuna fattura viaggia dal punto di accesso del mittente a quello del destinatario. Nordlet genera fatture e note di credito in formato Peppol BIS Billing 3.0 e provvede a inviarle e riceverle tramite l'account del punto di accesso della tua azienda.

Peppol stabilisce le regole con cui i punti di accesso si scambiano i documenti, ma non definisce le modalità di comunicazione tra il tuo software e il tuo punto di accesso: ogni fornitore adotta una propria API. Nordlet è compatibile con i seguenti fornitori:

Fornitore	Invio	Stato di consegna	Ricezione
Recommand	sì	tramite webhook e su richiesta	sì
Storecove	sì	solo tramite webhook	sì
e-invoice.be	sì	tramite webhook e su richiesta	sì

In assenza di un punto di accesso, Nordlet compila comunque il file Peppol di ogni fattura emessa e nota di credito affinché tu possa scaricarlo e trasmetterlo con altre modalità; in questo caso, non effettua alcuna operazione di invio o ricezione.

Requisiti

• Un account presso uno dei fornitori sopra indicati, con la tua azienda registrata su Peppol tramite lo stesso. Ciascun fornitore applica tariffe proprie per il servizio; consulta il rispettivo listino prezzi.
• In Nordlet, il numero di partita IVA o di registrazione dell'azienda, oppure il relativo identificativo Peppol (Account → Aziende → ID Peppol). Ciascun cliente a cui invii i documenti deve disporre di uno di questi dati nella propria scheda anagrafica partner.

Connessione del punto di accesso

Accedi a Account → Conformità → UE → Punto di accesso Peppol, seleziona il tuo fornitore nel campo Fornitore, compila i campi specifici del fornitore come descritto di seguito e salva. Lascia vuoto il campo URL di base dell'API a meno che il tuo fornitore non ti abbia fornito un indirizzo differente. Dopo il salvataggio, la pagina mostrerà l'URL del webhook della tua azienda: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}, dove {provider} corrisponde a recommand, storecove o e-invoice-be e {companyId} è l'ID della tua azienda. Ogni azienda su Nordlet possiede un proprio URL webhook dedicato.

Nordlet accetta una chiamata webhook esclusivamente se viene dimostrata la conoscenza del tuo segreto del webhook, rifiutando pertanto qualsiasi chiamata non proveniente dall'account del tuo punto di accesso. Nordlet contatta unicamente indirizzi internet pubblici quando effettua chiamate al tuo punto di accesso.

Recommand

1. In Recommand, apri la tua azienda e copia il relativo ID azienda nel campo ID account presso il punto di accesso.
2. In Recommand, crea una chiave API e inserisci la chiave e la relativa stringa segreta nei campi Chiave API e Segreto API.
3. Idea un testo casuale e complesso noto solo a te e a Recommand, quindi inseriscilo nel campo Segreto del webhook. Salva.
4. In Recommand, crea un webhook per la tua azienda utilizzando l'URL del webhook mostrato da Nordlet e lo stesso segreto del webhook.

Recommand firma ogni chiamata webhook utilizzando quel segreto.

Storecove

1. In Storecove, crea un'entità giuridica (legal entity) per la tua azienda, configurata per l'invio e la ricezione, e copia il suo ID nel campo ID account presso il punto di accesso.
2. In Storecove, nella sezione Chiavi API (API Keys), crea una chiave API e copiala nel campo Chiave API. Lascia vuoto il campo Segreto API.
3. Idea un testo casuale e complesso e inseriscilo nel campo Segreto del webhook. Salva.
4. In Storecove, configura un webhook di tipo push utilizzando l'URL del webhook mostrato da Nordlet, protetto tramite autenticazione di base HTTP: un nome utente qualsiasi e il segreto del webhook come password.

Storecove non prevede una chiamata per verificare lo stato di un documento inviato; di conseguenza, con Storecove lo stato di consegna viene aggiornato esclusivamente tramite il suo webhook e la pagina della fattura non include il pulsante Verifica stato Peppol. Un account sandbox di Storecove effettua gli invii sulla rete di test Peppol; le chiavi API di produzione vengono rilasciate dall'assistenza di Storecove.

e-invoice.be

1. Nell'applicazione e-invoice.be, alla voce Impostazioni API (API Settings), copia la chiave API della tua azienda nel campo Chiave API. Lascia vuoti i campi ID account presso il punto di accesso e Segreto API. Salva.
2. Crea un webhook tramite l'API di e-invoice.be (POST https://api.e-invoice.be/api/webhooks/) specificando l'URL del webhook mostrato da Nordlet e gli eventi document.received, document.sent e document.sent.failed.
3. Copia il valore secret restituito dall'API per il nuovo webhook nel campo Segreto del webhook in Nordlet e salva nuovamente.

e-invoice.be firma ogni chiamata webhook utilizzando tale segreto. Un'azienda in ambiente di prova (sandbox) su e-invoice.be invia via email i documenti che avrebbe dovuto trasmettere tramite Peppol.

Invio di una fattura

1. Emetti la fattura o la nota di credito.
2. Verifica che il cliente disponga di un ID Peppol, di un numero di partita IVA o di un numero di registrazione nella propria scheda anagrafica partner.
3. Nella pagina della fattura, all'interno della sezione Consegna, fai clic su Invia tramite Peppol e conferma. La sezione Consegna viene visualizzata per le fatture emesse non ancora saldate, mentre il pulsante compare unicamente se il punto di accesso è connesso.

Nordlet genera il file Peppol e lo trasmette al tuo punto di accesso. La pagina della fattura mostrerà quindi una sezione dedicata alla Consegna Peppol:

Stato	Significato
pending	Consegnato al punto di accesso; il punto di accesso del cliente non ha ancora confermato la ricezione
delivered	Il punto di accesso del cliente ha confermato la ricezione della fattura
rejected	Il cliente ha rifiutato la fattura; il motivo viene mostrato al di sotto dello stato
failed	Impossibile consegnare la fattura; il motivo viene mostrato al di sotto dello stato qualora il punto di accesso ne fornisca uno

Lo stato si aggiorna automaticamente non appena il punto di accesso segnala una modifica tramite il proprio webhook. La funzione Verifica stato Peppol richiede a Recommand o e-invoice.be lo stato attuale in tempo reale; nel caso di e-invoice.be, legge inoltre la risposta del cliente alla fattura, e un eventuale rifiuto (codice di risposta RE) viene visualizzato come rifiutato (rejected). Una fattura rifiutata o non consegnata può essere inviata nuovamente dopo aver corretto la causa del problema. Qualora il punto de accesso rifiuti nettamente una fattura, ad esempio perché il cliente non è registrato su Peppol, Nordlet ne mostra la motivazione e la fattura rimane nello stato di non inviata.

Il pulsante XML Peppol situato nella parte superiore della pagina della fattura consente di scaricare il medesimo file Peppol senza procedere all'invio.

Le cessioni intracomunitarie riportano la data di emissione come data di consegna e il paese del cliente come paese di consegna, come richiesto dalle specifiche Peppol.

Ricezione delle fatture

Quando il punto di accesso segnala un documento ricevuto tramite il proprio webhook, Nordlet scarica il file Peppol dal punto di accesso. Le fatture e le note di credito ricevute dalla tua azienda compaiono in Acquisti → Acquisizione documenti, contrassegnate come ricevute tramite Peppol e associate all'ID Peppol del mittente. Nordlet elabora direttamente il file Peppol, pertanto la ricezione non consuma crediti di riconoscimento documenti.

1. Apri il documento ricevuto.
2. Verifica il fornitore, le date e le righe; seleziona il fornitore dall'elenco dei tuoi partner oppure creane uno nuovo.
3. Fai clic su Salva bozza. Nordlet genera una bozza di fattura d'acquisto, oppure una bozza di nota di credito d'acquisto in caso di nota di credito ricevuta, allegando il file Peppol originale. Registrala come qualsiasi altra fattura d'acquisto.

Le righe delle fatture d'acquisto su Nordlet non possono riportare importi negativi. Gli sconti e gli oneri applicati all'intero documento, così come le righe negative, vengono ripartiti proporzionalmente sulle righe soggette alla medesima aliquota IVA. Un importo che non può essere associato ad alcuna riga della rispettiva aliquota IVA, ad esempio un reso riferito a un'aliquota IVA non presente in altre righe della fattura, viene visualizzato in una seconda tabella: Righe nota di credito nel caso di una fattura ricevuta, oppure Righe fattura nel caso di una nota di credito ricevuta. Tali righe vengono salvate come un secondo documento intestato allo stesso fornitore: una nota di credito d'acquisto a storno della nuova fattura, numerata nel formato "-CR", oppure una fattura d'acquisto numerata nel formato "-INV". I due documenti, considerati insieme, corrispondono ai totali del documento ricevuto.

Verifica della registrazione di un cliente su Peppol

La chiamata POST /v1/peppol/participants/lookup con i parametri partnerId o participantId (nel formato ":") interroga la rete Peppol per verificare se il destinatario è registrato e quali tipi di documenti è in grado di accettare. Questa operazione può essere eseguita anche senza un punto di accesso configurato.

Esecuzione delle stesse operazioni tramite API

Operazione	Chiamata
Connessione del punto di accesso	POST /v1/declarations/configs/update con i parametri system: "peppol" e config contenente provider (recommand, storecove o e-invoice-be), accountId, apiKey, apiSecret, webhookSecret e il parametro opzionale apiBaseUrl
Ricezione del webhook del punto di accesso	POST /v1/peppol/webhooks/{provider}/{companyId}, richiamato dal punto di accesso
Download del file Peppol	POST /v1/sales/invoices/peppol-xml
Invio	POST /v1/sales/invoices/peppol-send (restituisce 422 in assenza di un punto di accesso)
Lettura dello stato di consegna	POST /v1/sales/invoices/peppol-status (restituisce 422 con Storecove); le fatture contengono i campi peppolMessageId, peppolStatus, peppolDetail, peppolSentAt, peppolCheckedAt
Ricerca dei documenti ricevuti	POST /v1/capture/documents/list; i documenti ricevuti presentano i campi provider: "peppol" e senderId
Conversione in fattura d'acquisto	POST /v1/capture/documents/confirm, con l'aggiunta di oppositeLines per il secondo documento

Eventi webhook: sale_invoice.peppol_sent, sale_invoice.peppol_delivered, sale_invoice.peppol_rejected, sale_invoice.peppol_failed e document_capture.peppol_received. Consulta la sezione Convenzioni API per informazioni dettagliate su errori, idempotenza e webhook.