Tabella dei contenuti
FAQ inserimento notifiche
Quando chiamo le API sulla pagina swagger ottengo errore
Se non è stato già fatto, è necessario intraprendere il processo di accreditamento, contattando l'indirizzo preposto: account@pagopa.it
Se è stato già completato il processo di accreditamento, assicurarsi che si stia utilizzando correttamente l'API Key ed il Voucher.
Le chiamate ai servizi esposti da PN sono sicuri?
Dopo aver fatto l'upload dei documenti della notifica nella fase 1, quanto tempo ho per inviare la notifica?
Quali sono i passi da seguire per effettuare l’inoltro della notifica in modalità B2B?
- Pre inoltro della documentazione (atto di notifica e modello di pagamento).
Occorre chiamare il servizio presignedUploadRequest per ottenere il/gli url da utilizzare per effettuare l'upload dei documenti**.** Non è obbligatorio caricare il modello di pagamento. - Upload della documentazione.
Occorre effettuare, per ogni documento, una richiesta HTTP con metodo ed url restituiti dal servizio presignedUploadRequest nella chiamata al punto precedente**.** - Invio della notifica.
A seguito dell'upload dei documenti , bisogna chiamare il servizio sendNewNotification per completare l'invio della notifica, avendo cura di valorizzare correttamente i riferimenti ai documenti caricati al punto precedente.
Come avviene l’inoltro della notifica?
Cosa NON inserire tra i metadati della notifica?
- subject
- abstract
Quali controlli vengono effettuati contestualmente all'inserimento della notifica (controlli sincroni)?
I controlli effettuati da PN sono i seguenti:
- verifica che le informazioni inserite siano sintatticamente corrette e rispettino i vincoli applicati sui campi delle entities.
- verifica che le combinazioni di creditorTaxId/noticeCode e creditorTaxId/alternativeNoticeCode siano univoche.
- verifica che la combinazione dei campi senderPaId, paProtocolNumber, idempotenceToken siano univoci.
Quali controlli vengono effettuati a seguito dell'inserimento della notifica (controlli asincroni)?
I controlli effettuati da PN sono i seguenti:
- verifica che lo sha256 inserito nella notifica corrisponda a quello del documento associato ad essa
- verifica che ciascun CF fornito esista veramente
- verifica che l'indirizzo fisico associato a ciascun destinatario sia esistente e che il CAP inserito sia specifico della località e non generico. Queste verifiche vengono effettuate con Postel.
Vedi l'art. 4 comma 3 lettera d) dei T&C della piattaforma.
Come si sviluppa il workflow dell'invio della notifica?
- Workflow Digitale
Questo processo parte dopo aver verificato che il destinatario abbia ALMENO UN domicilio digitale tra quelli previsti (Domicilio digitale di piattaforma, Domicilio digitale speciale, Domicilio digitale generale).
Una volta avviato questo Workflow, nel caso di fallimento del primo tentativo di invio digitale, PND effettuerà un secondo tentativo di invio a distanza di 7 giorni. Al primo successo PND interromperà il tentativo di invio, mentre se anche il secondo tentativo di invio fallisce, verrà effettuato un invio con raccomandata semplice. - Workflow Analogico
Questo processo parte solo dopo aver verificato che il destinatario NON abbia nessun domicilio digitale e prevede l'invio all'indirizzo del destinatario inserito nel campo recipients.physicalAddress con invio di raccomandata del tipo valorizzato in physicalCommunicationType
Cos'è il codice di tassonomia (taxonomyCode)?
Come si individua il domicilio del destinatario di una notifica in base alla tipologia del destinatario (PF e PG)?
- Se il destinatario è Persona Fisica (PF), l'ordine di individuazione è il seguente:
- Domicilio digitale di piattaforma (se disponibile, quello configurato dal destinatario per l'ente mittente della notifica; in alternativa, quello configurato dal destinatario per la genericità degli enti mittenti)
- Domicilio digitale speciale indicato dall’ente mittente nella creazione della notifica
- Domicilio digitale generale fornito dal registro pubblico INAD
- se il destinatario è Persona Giuridica (PG), l'ordine di individuazione è il seguente:
- Domicilio digitale di piattaforma (se disponibile, quello configurato dal destinatario per l'ente mittente della notifica; in alternativa, quello configurato dal destinatario per la genericità degli enti mittenti)
- Domicilio digitale speciale indicato dall’ente mittente nella creazione della notifica
- Domicilio digitale generale fornito dal registro delle imprese IniPEC
Quale relazione esiste tra eventi di timeline e stati della notifica?
Cosa fare quando eseguendo l’upload del documento si ottiene il seguente errore: <Code>SignatureDoesNotMatch</Code><Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.</Message>
- In uploadAllegati si è utilizzato uno sha256 diverso da quello utilizzato in presignedUploadRequest.
- In uploadAllegati è stato inserito uno sha256 che non corrisponde al documento che si desidera effettivamente inviare.
- Lo sha256 è corretto in presignedUploadRequest e coincidente con quello caricato in uploadAllegati, ma il secret errato.
- Se si utilizza Postman assicurarsi che gli header siano valorizzati correttamente e che il documento che si sta caricando sia effettivamente quello dal quale è stato generato lo Sha256(a volte è necessario rimuovere e ricaricare il file dalla scheda di Postman affinchè venga recepito)
- Assicurarsi che gli header siano valorizzati correttamente ed inseriti nel giusto ordine (vedi 1.b del Ciclo di vita della notifica lato mittente)
Cosa fare quando si invoca il servizio di upload di un documento, passando x-amz-checksum-sha256 del file, si ottiene il seguente errore: Value for x-amz-checksum-sha256 header is invalid
- Applicare al documento l’algoritmo di crittazione, ottenendo una rappresentazione di 64 caratteri in formato esadecimale ^[A-Fa-f0-9]{64}$
- Ottenere la relativa rappresentazione binaria.
- Applicare la codifica Base64.
import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.security.MessageDigest;
byte[] encodedhash = digest.digest( StreamUtils.copyToByteArray( docInputStream ) );
String x-amz-checksum-sha256 = Base64Utils.encodeToString( hash )
Come si può verificare che lo "x-amz-checksum-sha256" sia corretto?
Come posso simulare l'upload di un documento su S3?
-H"Content-type: application/pdf" \
-H"x-amz-meta-secret: <secret>" \
-H"trailer: x-amz-checksum-sha256" \
-H"x-amz-checksum-sha256: <checkSum>" \
--data-binary "@<filePath>" \
"<url>"
<secret>: è il secret ottenuto nella response della preload
<checksum>: è il checksum sha256, codificato in base 64, del contenuto binario del file da caricare
<file>: è il path del file da caricare
<url>: è l'url del bucket S3 ottenuto nella response della preload, sul quale effettuare l'upload del documento
NOTA: l'header -H"trailer: x-amz-checksum-sha256" è non obbligatorio ai fini del buon esito della chiamata, per tanto può essere omesso qualora si riscontrassero problemi durante questa fase; inoltre si evidenzia che in questa chiamata NON deve essere inserito l'Autorization Header "Authorization: Bearer <PDNDVoucher>con il Vocuher.
Quanto tempo ho per scaricare le Attestazioni Opponibili a Terzi?
Quali sono le Attestazioni Opponibili a Terzi?
- Notifica presa in carico - generato dall’evento REQUEST_ACCEPTED ed avente come legalFactType: SENDER_ACK
- Notifica digitale - generato dall’evento DIGITAL_SUCCESS_WORKFLOW ed avente come legalFactType: DIGITAL_DELIVERY
- Mancato recapito digitale - generato dall’evento DIGITAL_FAILURE_WORKFLOW ed avente come legalFactType: DIGITAL_DELIVERY
- Avvenuto accesso - generato dall’evento NOTIFICATION_VIEWED ed avente come legalFactType: RECIPIENT_ACCESS
- Deposito di avvenuta ricezione - generato dall’evento COMPLETELY_UNREACHABLE ed avente come legalFactType: ANALOG_FAILURE_DELIVERY
- Malfunzionamento e ripristino - generata nei casi di downtime del servizio PND, scaricabile direttamente dalla pagina di Piattaforma Notifiche nella sezione “Stato della Piattaforma”
- Ricevute XML dell’esito relativo all’invio PEC - generate dagli eventi SEND_DIGITAL_PROGRESS e SEND_DIGITAL_FEEDBACK, ed aventi come legalFactType: PEC_RECEIPT
- Ricevuta di accettazione raccomandata - generato dall’evento SEND_ANALOG_PROGRESS ed avente come legalFactType: ANALOG_DELIVERY
- Ricevuta di consegna raccomandata e Ricevuta di mancata consegna raccomandata – generato dall’evento SEND_ANALOG_FEEDBACK ed avente come legalFactType: ANALOG_DELIVERY
Dopo aver lanciato il servizio sendNewNotificationottengo un messaggio di errore su: "Max one recipient", "No recipient physical address", "No recipient payment", "Alternative notice code equals to notice code". Cosa devo fare?
Dopo aver lanciato il servizio sendNewNotificationottengo un messaggio di errore "400: invaild request body"
In questo caso fare è necessario fare attenzione alle seguenti:
- se il campo sullo Swagger risulta opzionale ma nella request che si sta inviando è valorizzato con null, è necessario eliminare del tutto questo campo dal body ed in generale dal JSON della request.
- se il campo è di tipo enum, fare attenzione che non sia valorizzato con stringa vuota "" ma che abbia un valore coerente con quelli dell'enum di appartenenza
- se il campo è di tipo stringa, fare attenzione che non sia valorizzato come numero intero
- configurare l’ObjectMapper per far sì che includa solamente i campi NON_NULL con la seguente configurazione: mapper.setSerializationInclusion(Include.NON_NULL);
- se si utilizza la libreria Jackson per la serializzazione delle request, è possibile aggiungere questa annotation a livello di Classe:
@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_NULL)
Posso riutilizzare lo stesso IUV di una notifica rifiutata?
Come si possono testare più Enti?
Come posso testare il caso d'uso della Multa per violazione del Codice della Strada?
- NewNotificationRequest.recipients.payments.noticeCode: col numero avviso corrispondente al prezzo ridotto; questo verrà visualizzato in Piattaforma nella sezione di pagamento online con l'importo corrispondente entro 5 giorni dalla data di perfezionamento della notifica.
- NewNotificationRequest.recipients.payments.noticeCode: col numero avviso corrispondente al prezzo intero; questo verrà visualizzato in Piattaforma nella sezione di pagamento online con l'importo corrispondente tra i 5 ed i 60 giorni dalla data di perfezionamento della notifica.
- il bollettino di pagamento può essere caricato nel campo NewNotificationRequest.recipients.payment.pagoPa se è contenuto in un file diverso da quello dell'atto e sarà scaricabile dal destinatario nella sezione "Scarica l'avviso PagoPA".
Se invece questo è già presente nello stesso pdf contenente l'atto, potrà essere caricato come unico pdf all'interno del campo NewNotificationRequest.documents e sarà scaricabile dal destinatario unitamente all'atto nella sezione "DOCUMENTI ALLEGATI"
Quali sono i passaggi per visualizzare la funzione di pagamento online?
- NewNotificationRequest.recipients.payments.creditorTaxId: con la partita iva della PA Mittente
- NewNotificationRequest.recipients.payments.noticeCode: con il numero avviso.
Come si può testare la correttezza del Codici Fiscale?
^([A-Z]{6}[0-9LMNPQRSTUV]{2}[A-Z]{1}[0-9LMNPQRSTUV]{2}[A-Z]{1}[0-9LMNPQRSTUV]{3}[A-Z]{1})|([0-9]{11})$
Quali sono i passaggi per testare la visualizzazione della notifica?
- Michelangelo Buonarroti con codice fiscale: BNRMHL75C06G702B
https://login.uat.notifichedigitali.it/login
inserendo le credenziali dell’utente a cui sono state inviate le notifiche:
- per Michelangelo Buonarroti username: michelangelo e password: password123
NOTE: lo stato della notifica Visualizzata NON corrisponde necessariamente al Perfezionamento per presa visione. Per i dettagli sul perfezionamento vedi Perfezionamento della notifica.
Come gestisce un Ente le spese di notifica verso il destinatario?
Nello specifico, quando l’Ente effettua una richiesta di notifica tramite il servizio di invio notifica deve valorizzare l’elemento notificationFeePolicy per indicare la politica di addebitamento dei costi di notifica.
In quale modo l’Ente comunica a Piattaforma Notifiche il costo forfettario?
Il costo forfettario si applica nei casi in cui l'Ente voglia assumersi completamente i costi di notifica, oppure nel caso in cui esista una legge che impone all’Ente l'utilizzo di costi di notifica diversi da quelli previsti dal DPCM Costi di Piattaforma Notifiche.
Con quale logica l'API notificationPrice risponde?
- 0 se il notificationFeePolicy=FLAT_RATE. Questo permette alla PA mittente di applicare al destinatario un costo forfettario stabilito dalla PA mittente stessa.
- € 1 (per PND) se il notificationFeePolicy=DELIVERY_MODE e la notifica NON ha comportato invio cartaceo
- € 1 (per PND) se il notificationFeePolicy=DELIVERY_MODE + X € costo dell'invio cartacea
NOTA: il costo X dell'invio cartaceo dipende dai tabellari dei prezzi di aggiudicazione delle gare pubbliche di recapito, visibili qui:
https://pagopa.portaleamministrazionetrasparente.it/moduli/downloadFile.php?file=oggetto_allegati/23501547570O__OPREZZI+DI+AGGIUDICAZIONE+GARA+SERVIZI+POSTALI+E+SERVIZI+%26%238220%3BA+VALLE%26%238221%3B+DEL+RECAPITO.docx.pdf
E' possibile sfruttare questa informazione per anticipare la chiamata al servizio e completare l'attualizzazione del costo di notifica anche prima del tentativo di pagamento da parte del destinatario. In tutti gli altri casi è sempre necessario completare l'attualizzazione del costo di notifica durante la fase di pagamento da parte del destinatario.
NOTE: la presenza della notificationViewDate valorizzata NON comporta necessariamente il Perfezionamento per presa visione. Per i dettagli sul perfezionamento vedi: https://docs.pagopa.it/f.a.q.-per-integratori/knowledge-base-di-piattaforma-notifiche/focus-sul-perfezionamento-della-notifica
Il servizio notificationPrice può restituire valori diversi nel tempo per la stessa combinazione paTaxId/noticeCode?
Come avviene la fatturazione di PN nei confronti della PA mittente?
- € 1 per servizio PN per ogni destinatario della notifica (a copertura dei servizi di PND)
- il costo di tutti gli invii cartacei (a copertura dei servizi di postalizzazione)
Cosa rappresenta lo status "Unreachable"?
In questi casi si applicano le spese di notifica sostenute e l'atto depositato è considerato notificato.
Quando invio la notifica ricevo un'errore sulla lunghezza dei campi dell'address, come procedo?
In questa pagina
Quando chiamo le API sulla pagina swagger ottengo errore
Cosa devo fare se ricevo {"message": "Unauthorized"}
quando chiamo le API?
Le chiamate ai servizi esposti da PN sono sicuri?
Dopo aver fatto l'upload dei documenti della notifica nella fase 1, quanto tempo ho per inviare la notifica?
Quali sono i passi da seguire per effettuare l’inoltro della notifica in modalità B2B?
Come avviene l’inoltro della notifica?
Cosa NON inserire tra i metadati della notifica?
Quali controlli vengono effettuati contestualmente all'inserimento della notifica (controlli sincroni)?
Quali controlli vengono effettuati a seguito dell'inserimento della notifica (controlli asincroni)?
Come si sviluppa il workflow dell'invio della notifica?
Cos'è il codice di tassonomia (taxonomyCode)?
Come si individua il domicilio del destinatario di una notifica in base alla tipologia del destinatario (PF e PG)?
Quale relazione esiste tra eventi di timeline e stati della notifica?
Cosa fare quando eseguendo l’upload del documento si ottiene il seguente errore: <Code>SignatureDoesNotMatch</Code>
<Message>The request signature we calculated does not match the signature you provided. Check your key and signing method.</Message>
Cosa fare quando si invoca il servizio di upload di un documento, passando x-amz-checksum-sha256 del file, si ottiene il seguente errore: Value for x-amz-checksum-sha256 header is invalid
Come si può verificare che lo "x-amz-checksum-sha256" sia corretto?
Come posso simulare l'upload di un documento su S3?
Quanto tempo ho per scaricare le Attestazioni Opponibili a Terzi?
Quali sono le Attestazioni Opponibili a Terzi?
Dopo aver lanciato il servizio sendNewNotificationottengo un messaggio di errore su: "Max one recipient", "No recipient physical address", "No recipient payment", "Alternative notice code equals to notice code". Cosa devo fare?
Dopo aver lanciato il servizio sendNewNotificationottengo un messaggio di errore "400: invaild request body"
Posso riutilizzare lo stesso IUV di una notifica rifiutata?
Come si possono testare più Enti?
Come posso testare il caso d'uso della Multa per violazione del Codice della Strada?
Quali sono i passaggi per visualizzare la funzione di pagamento online?
Come si può testare la correttezza del Codici Fiscale?
Quali sono i passaggi per testare la visualizzazione della notifica?
Come gestisce un Ente le spese di notifica verso il destinatario?
In quale modo l’Ente comunica a Piattaforma Notifiche il costo forfettario?
Con quale logica l'API notificationPrice risponde?
Il servizio notificationPrice può restituire valori diversi nel tempo per la stessa combinazione paTaxId/noticeCode?
Come avviene la fatturazione di PN nei confronti della PA mittente?
Cosa rappresenta lo status "Unreachable"?
Quando invio la notifica ricevo un'errore sulla lunghezza dei campi dell'address, come procedo?