-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathb2b.yaml
More file actions
10679 lines (10428 loc) · 397 KB
/
b2b.yaml
File metadata and controls
10679 lines (10428 loc) · 397 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
openapi: 3.0.3
info:
termsOfService: https://selfcare.notifichedigitali.it/termini-di-servizio
x-api-id: api-external-b2b-pa
title: 'Piattaforma Notifiche: API B2B per le Pubbliche Amministrazioni'
x-summary: 'Piattaforma Notifiche: API B2B per le Pubbliche Amministrazioni'
version: 1.0.0
description: >-
## Abstract
API utilizzate dalle pubbliche amministrazioni per __inviare richieste di notifiche__ e
__ottenere informazioni in modalità pull__ sullo stato della
_"richiesta di notifica"_ (accettata o rifiutata) e, in caso di richiesta accettata,
sulle comunicazioni effettuate, o solo tentate, nei confronti dei destinatari della notifica.
## Operazioni utilizzate, in sequenza temporale
<table>
<tr>
<td>
<img src="https://raw.githubusercontent.com/pagopa/pn-delivery/e6f1db9eac9ace7fc2ad0fe6de241ab4525b6b6a/docs/openapi/images/invio-notifica.png" height="790" width="515" alt="Invio notifica" />
</br>
</br>
</br>
#### 3. Verifica accettazione richiesta di invio notifica
Per questa verifica possono essere utilizzate due modalità:
1. __richiesta puntuale__: consigliato solo ai fini di test
2. __lettura da stream configurato__: consigliato per ambienti di produzione
La differenza tra le due modalità è nell'interazione e nell'efficienza.
Con la modalità _"richiesta puntuale"_ è necessaria l'invocazione per ogni notifica,
mentre con la modalità _"stream"_ è possibile avere gli aggiornamenti
di stato di più notifiche con una sola invocazione.
#### 3.1 Richiesta puntuale di verifica accettazione
Questa modalità è resa disponibile solo ai fini di test o di eventuali operazioni
di allineamento. Richiede l'invio di una richiesta per ogni notifica.
Se il passo (2) avviene con successo si utilizza l'operazione
[getNotificationRequestStatus](#/SenderReadB2B/retrieveNotificationRequestStatusV23)
per ottenere informazioni riguardo allo stato della "richiesta di invio di notifica". </br>
Nel campo _notificationRequestStatus_ sarà indicato:</br>
>\- <strong>WAITING:</strong> se la validazione è ancora in corso.</br>
\- <strong>ACCEPTED:</strong> se richiesta di notifica accettata, lo _IUN_ è valorizzato.</br>
\- <strong>REFUSED:</strong> se richiesta di notifica rifiutata, è valorizzato il campo _errors_.</br>
</br>
</br>
</br>
#### 3.2 Richiesta avanzamento via "stream" di verifica di accettazione
Questa è la modalità consigliata. Per essere utilizzata è necessaria un'operazione preliminare
tramite la chiamata alla API [createEventStream](https://petstore.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fpagopa%2Fpn-delivery-push%2Fmain%2Fdocs%2Fopenapi%2Fapi-external-b2b-webhook.yaml#/Streams/createEventStream)
per configurare uno "stream" che registri il cambio di stato della notifica con il seguente payload:</br></br>``
{
"title": "NotificationAccepted",
"eventType": "STATUS",
"filterValues": [
"ACCEPTED"
]
}
``</br></br>
Successivamente si possono ottenere i dati richiamando la API [consumeEventStream](https://petstore.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fpagopa%2Fpn-delivery-push%2Fmain%2Fdocs%2Fopenapi%2Fapi-external-b2b-webhook.yaml#/Events/consumeEventStream)
__NOTA__ saranno disponibili i dati di cambiamento di stato occorsi solo successivamente alla configurazione
dello stream.
</br>
</br>
</br>
</br>
</td>
<td>
### Ciclo di vita della notifica lato mittente
#### 1. Caricamento dei documenti della notifica
Prima di invocare la richiesta di notifica è necessario caricare i documenti della notifica (documenti e bollettini/metadata di pagamento).
[Schema Metadata F24](#/components/schemas/F24Metadata)
#### 1.a. Richiesta presigned Url
Invocare l'operazione [presignedUploadRequest](#/NewNotification/presignedUploadRequest)
con cui prenotare il caricamento. Possono essere effettuate un massimo di <span id="numberOfPresignedRequest">15</span> prenotazioni di caricamento
per ogni richiesta.</br>
In risposta si ottengono le seguenti informazioni:<br/>
\- httpMethod <br/>
\- secret <br/>
\- url <br/>
L'url restituito ha una validità di 1h.
</br>
#### 1.b Upload documenti della notifica
Per ogni documento utilizzare un richiesta HTTP con metodo _httpMethod_ (POST o PUT)
all'url indicato dal campo _url_. <br/>
In tale richiesta vanno aggiunti i seguenti header: <br/>
\- _content-type_: valorizzato come il campo "contentType" della richiesta di cui al punto (1.a) <br/>
\- _x-amz-meta-secret_: valorizzato con il valore del campo "secret" della risposta di cui al punto (1.a) <br/>
\- _trailer_: valorizzato con ```x-amz-checksum-sha256``` <br/>
\- _x-amz-checksum-sha256_: valorizzato con il checksum sha256, codificato in base 64, del contenuto binario del file che verrà caricato. (__N.B.__ questo è un trailer HTTP non un header).
Vedi [HTTP Trailer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Trailer) <br/>
__NOTA:__ se l'operazione di upload è stata eseguita con successo, si otterrà come risposta _status 200 OK_. <br/>
Nell'header di questa risposta, si otterrà il campo __x-amz-version-id__ che dovrà essere utilizzato durante <br/>
l'inserimento della notifica, nel campo ref.__versionToken__ in corrispondenza del documento ad esso associato.
</br>
</br>
</br>
#### 2. Richiesta di invio della notifica
Per effettuare una richiesta di invio notifica, invocare l'operazione
[sendNewNotification](#/NewNotification/sendNewNotificationV21) valorizzando il campo <b>payments</b> (scegliendo in base alla tipologia di file caricato <b>F24</b>/<b>pagoPa</b>) e il campo <b>documents</b> utilizzando i riferimenti dei file
caricati in precedenza nel seguente:
<br>
- <b>digests.sha256 </b>: SHA256 associato all'allegato caricato
- <b>contentType </b>: in caso la tipologia dell'allegato fosse <b>documento</b> e <b>avviso di pagamento</b> dovrà essere popolato con "application/pdf" in caso di <b>F24</b> invece dovrà contenere "application/json"
- <b>ref.key</b>: key ottenuta nella response della chiamata [presignedUploadRequest](#/NewNotification/presignedUploadRequest)
- <b>ref.versionToken</b>: valore dell'header x-amz-version-id ottenuto dalla response in fase di upload dell'allegato ad esso associato.
</br>
Nel caso si voglia valorizzare il campo <b>payments</b> con un bolletino di pagamento <b>pagoPa</b> oltre al riferimento al file tramite la sezione <b>pagoPaForm</b> con le indicazioni riportate sopra, sono da valorizzare i campi <b>noticeCode</b> "codice avviso pagoPA" ,univoco, di pagamento del sistema pagoPA utilizzato , usato per pagamento online;
<b> creditorTaxId</b>: codice fiscale dell'ente a cui fa riferimento il "codice avviso pagoPA"; il campo
<b>applyCost</b>: flag per indicare se l'avviso pagoPA deve contenere i costi di notifica e il campo
</br>
Nel caso,invece, nel campo payments si voglia valorizzare un pagamento <b>F24</b>,oltre al riferimento al file caricato tramite la sezione <b>metadataAttachment</b> con le indicazioni riportate sopra, sono da valorizzare i campi <b> title</b>: titolo del documento pdf da mostrare all'utente e
<b>applyCost</b>: flag per indicare se il modello F24 deve contenere i costi di notifica.
</br>
</br>
</br>
<img src="https://raw.githubusercontent.com/pagopa/pn-delivery/e6f1db9eac9ace7fc2ad0fe6de241ab4525b6b6a/docs/openapi/images/verifica-accettazione-richiesta-invio.png" height="731" width="489" alt="Verifica accettazione richiesta" />
</td>
</tr>
</table>
### 4. Monitorare l'avanzamento di una notifica
Per questa verifica possono essere utilizzate due modalità:
1. __monitoraggio puntuale__: consigliato solo ai fini di test
2. __monitoraggio tramite stream__: consigliato per ambienti di produzione
#### 4.1 Monitoraggio puntuale
Se la "richiesta di invio di notifica" passa le validazioni viene trasformata in "notifica" . Sarà possibile
identificarla dallo IUN restituito dall'operazione
[getNotificationRequestStatus](#/SenderReadB2B/retrieveNotificationRequestStatusV23).</br>
A questo punto, si potranno utilizzare l'operazione _GET /delivery/v2.4/notifications/sent/{iun}_ per
ottenere i dettagli della notifica, la _timeline_ che dettaglia il perfezionamento della
notifica per il mittente e l'avanzamento delle comunicazioni nei confronti dei destinatari.
#### 4.2 Monitoraggio tramite stream
Questa è la modalità consigliata in produzione. Per essere utilizzata è necessaria un'operazione preliminare
tramite la chiamata alla API [createEventStream](#/Streams/createEventStream)
per configurare uno "stream" che registri il cambio di stato della notifica con il seguente payload di esempio:</br></br>``
{
"title": "NotificationAccepted",
"eventType": "STATUS"
}
``</br></br>che permette di monitorare gli eventi di tipo "STATO". Successivamente si può ottenere il dettaglio della stream appena creata chiamando la
API [getEventStream](https://petstore.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fpagopa%2Fpn-delivery-push%2Fdevelop%2Fdocs%2Fopenapi%2Fapi-external-b2b-webhook.yaml#/Streams/getEventStream), mentre si possono ottenere i dati degli eventi richiamando la API [consumeEventStream](https://petstore.swagger.io/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fpagopa%2Fpn-delivery-push%2Fdevelop%2Fdocs%2Fopenapi%2Fapi-external-b2b-webhook.yaml#/Events/consumeEventStream)
``</br></br>che permette di monitorare gli eventi di tipo "STATO". Successivamente si può ottenere il dettaglio
dello stream appena creato chiamando la API [getEventStream](#/Streams/getEventStream)), mentre si possono
ottenere i dati degli eventi richiamando la API [consumeEventStream](#/Streams/consumeEventStream)
__NOTA__ saranno disponibili i dati di cambiamento di stato occorsi solo successivamente alla configurazione
dello stream.
</br>
### 5. Download dei Legal Facts
É possibile scaricare le Attestazioni Opponibili a Terzi e gli altri documenti conservati da Piattaforma Notifiche attraverso il servizio di [download Legal Fact](#/LegalFacts/downloadLegalFactById) passando all'interno del path lo <strong>Iun</strong>, il <strong>legalFactType</strong> ed il <strong>legalFactId</strong>; si otterrà nella response un link che permette di scaricare il documento richiesto.</br> Per ottenere il <strong>legalFactType</strong> ed il <strong>legalFactId</strong> bisogna chiamare il servizio di [lettura dettaglio notifica](#/SenderReadB2B/retrieveSentNotificationV21) con lo <code>{Iun}</code> della notifica di interesse: all'interno del campo <i>timeline</i> della response è possibile trovare l'elenco degli eventi di quella notifica ed i <strong>legalFactType</strong> e <strong>legalFactId</strong> in corrispondenza degli eventi che generano documenti.
</br>
<details>
<summary><strong><big><big><big><big>AMBIENTI</big></big></big></big></strong></summary>
<ul> <li><strong>https://api.notifichedigitali.it:</strong></br>Ambiente
di produzione</li>
<li><strong>https://api.uat.notifichedigitali.it:</strong></br>Ambiente di
collaudo. Potrebbe subire modifiche/integrazioni in futuro, rimanendo
comunque non-bloccante e rispettando il principio di retro
compatibilità</li> </ul> </details></br><br/>
# Piattaforma Notifiche: API B2B avanzamento notifiche
I mittenti di notifiche possono seguire il loro flusso di avanzamento in
modo automatico.
Tramite la configurazione di flussi (stream) è possibile ottenere, in modo
massivo, le informazioni informazioni relative a:
- cambiamento di stato delle notifiche
- inserimento di elementi di timeline delle notifiche
É possibile definire fino ad un __massimo di <span
id="webhookMaxStreams">10</span> configurazioni di flussi attive per singola
PA__.
__NOTA__: i flussi riportano gli eventi occorsi dal momento della loro
creazione, non quelli precedenti. Per cui si consiglia di creare i flussi di
interesse per il mittente prima dell'invio delle notifiche di cui si
vogliono ottenere gli aggiornamenti.
## Filtraggio degli eventi
La configurazione del flusso può prevedere un filtro per ricevere per
ricevere solo alcuni cambiamenti di stato o determinati eventi di timeline
di interesse per il mittente.</br>
__NEWS V2.3__: dalla versione 2.3 è possibile utilizzare il placeholder
__DEFAULT__ per ottenere SOLO gli eventi di timeline di maggior rilievo;
evitando di ricevere anche gli eventi interni del workflow che non hanno
ripercussione o informazioni utili per il mittente.
| Fase del workflow | Categoria eventi |
|-------------------|------------------|
| Eventi di validazione | REQUEST_REFUSED, REQUEST_ACCEPTED |
| Eventi del workflow digitale | SEND_DIGITAL_DOMICILE, SEND_DIGITAL_FEEDBACK, DIGITAL_SUCCESS_WORKFLOW, DIGITAL_FAILURE_WORKFLOW, SEND_SIMPLE_REGISTERED_LETTER, SIMPLE_REGISTERED_LETTER_PROGRESS |
| Eventi del workflow analogico | SEND_ANALOG_DOMICILE ,SEND_ANALOG_PROGRESS, SEND_ANALOG_FEEDBACK, ANALOG_SUCCESS_WORKFLOW, ANALOG_FAILURE_WORKFLOW, COMPLETELY_UNREACHABLE |
| Eventi di chiusura del workflow | REFINEMENT, NOTIFICATION_VIEWED, NOTIFICATION_CANCELLED |
| Altri eventi | NOTIFICATION_RADD_RETRIEVED, ANALOG_WORKFLOW_RECIPIENT_DECEASED|
Il placeholder __DEFAULT__ può essere usato assieme ad altri eventi di
timeline, ad esempio il filtro "DEFAULT,SEND_COURTESY_MESSAGE" permetterà di
ricevere anche gli eventi relativi agli invii dei messaggi di cortesia,
oltre che a tutti quelli di maggior rilievo.
### Filtri applicabili ai flussi di cambiamento di stato della notifica
Gli stati della notifica che possono essere inseriti come __filterValues__
sono i seguenti:
Stati - v1:
- __ACCEPTED__: L'ente ha depositato la notifica con successo.
- __REFUSED__: Notifica rifiutata a seguito della validazione.
- __DELIVERING__: L'invio della notifica è in corso.
- __DELIVERED__: La notifica è stata consegnata a tutti i destinatari.
- __VIEWED__: Il destinatario ha letto la notifica entro il termine stabilito.
- __EFFECTIVE_DATE__: Il destinatario non ha letto la notifica entro il termine stabilito.
- __UNREACHABLE__: Il destinatario non è reperibile.
- __CANCELLED__: L'ente ha annullato l'invio della notifica.
Stati - v2.6:
- __RETURNED_TO_SENDER__: La notifica è stata restituita al mittente.
### Filtri applicabili ai flussi di eventi di timeline
Le categorie degli eventi di timeline che possono essere inseriti come
__filterValues__ sono i seguenti:
<details>
<summary>Eventi di timeline - v1</summary>
| Categoria | Descrizione |
|-----------|-------------|
|__SENDER_ACK_CREATION_REQUEST__ | Invio della richiesta di creazione dell'atto opponibile a terzi di presa in carico per il mittente a safe storage |
|__VALIDATE_NORMALIZE_ADDRESSES_REQUEST__ | Invio della richiesta di validazione e normalizzazione indirizzi fisici presenti nella richiesta di notifica |
|__NORMALIZED_ADDRESS__ | Ricezione esito normalizzazione indirizzo |
|__REQUEST_ACCEPTED__ | Richiesta di notifica accettata a seguito dei controlli di validazione. |
|__AAR_CREATION_REQUEST__ | Invio della richiesta di creazione dell'AAR (Avviso di Avvenuta Ricezione) a safe storage |
|__SEND_COURTESY_MESSAGE__ | Invio di un messaggio di cortesia. |
|__GET_ADDRESS__ | Disponibilità dell’indirizzo specifico (domicilio digitale di piattaforma, domicilio digitale speciale, domicilio digitale generale, indirizzo fisico sulla notifica o sui registri nazionali). |
|__PUBLIC_REGISTRY_CALL__ | Richiesta ai registri pubblici per ottenere domicilio digitale generale o per ottenere indirizzo fisico da ANPR, da registro della imprese, da anagrafe tributaria. |
|__PUBLIC_REGISTRY_RESPONSE__ | Ricevuta la risposta dei registri pubblici. |
|__SCHEDULE_ANALOG_WORKFLOW__ | Pianificazione del workflow per invio cartaceo |
|__SCHEDULE_DIGITAL_WORKFLOW__ | Pianificazione del workflow per invio digitale (PEC) del secondo tentativo in caso di fallimento del primo. |
|__PREPARE_DIGITAL_DOMICILE__ | Preparazione per l’invio dell’avviso digitale.Va a valutare la timeline per capire quale sarà il prossimo indirizzo da usare. |
|__SEND_DIGITAL_PROGRESS__ | Tentativo di Invio PEC ad un determinato indirizzo. |
|__SEND_DIGITAL_DOMICILE__ | Invio digitale dell’avviso di notifica |
|__SEND_DIGITAL_FEEDBACK__ | Ottenuto esito ad un invio digitale |
|__REFINEMENT__ | Perfezionamento per decorrenza termini |
|__SCHEDULE_REFINEMENT__ | Pianificato il perfezionamento per decorrenza termini |
|__DIGITAL_SUCCESS_WORKFLOW__ | Completato con successo il workflow di invio digitale. |
|__DIGITAL_FAILURE_WORKFLOW__ | Completato con fallimento il workflow di invio digitale: __tutti i tentativi di invio ai domicili digitali sono falliti.__ |
|__ANALOG_SUCCESS_WORKFLOW__ | Completato con successo il workflow di invio cartaceo. |
|__ANALOG_FAILURE_WORKFLOW__ | Completato con fallimento il workflow di invio cartaceo. NOTA: se per tutti i destinatari si conclude il workflow con fallimento verrà scatenato l’evento COMPLETELY_UNREACHABLE |
|__PREPARE_SIMPLE_REGISTERED_LETTER__ | Invio richiesta di prepare (preparazione ad invio) raccomandata semplice a paperChannel |
|__SEND_SIMPLE_REGISTERED_LETTER__ | Invio di raccomandata semplice |
|__SIMPLE_REGISTERED_LETTER_PROGRESS__ | Ricezione informazioni intermedia relative ad una notificazione cartacea semplice |
|__NOTIFICATION_VIEWED_CREATION_REQUEST__ | Invio della richiesta di creazione dell'atto opponibile a terzi di presa visione a safe storage |
|__NOTIFICATION_VIEWED__ | Visualizzazione della notifica (perfeziona la notifica se non già perfezionata per decorrenza termini o da altro destinatario) |
|__PREPARE_ANALOG_DOMICILE__ | Invio richiesta di prepare (preparazione ad invio) cartaceo a paperChannel |
|__SEND_ANALOG_PROGRESS__ | Ricezione informazioni intermedia relative ad una notificazione cartacea |
|__SEND_ANALOG_FEEDBACK__ | Ricezione esito dell'invio cartaceo. |
|__SEND_ANALOG_DOMICILE__ | Invio cartaceo dell’avviso di notifica |
|__COMPLETELY_UNREACHABLE_CREATION_REQUEST__ | Invio della richiesta di creazione dell'atto (simile a opponibile a terzi) di completamento con fallimento del workflow di invio cartaceo |
|__COMPLETELY_UNREACHABLE__ | Tutti i destinatari risultano irraggiungibili |
|__REQUEST_REFUSED__ | Richiesta di notifica rifiutata per fallimento di validazione. |
|__AAR_GENERATION__ | Generazione dell’AAR (Avviso di Avvenuta Ricezione) |
|__PROBABLE_SCHEDULING_ANALOG_DATE__ |Data probabile di inizio del flusso analogico |
|__PREPARE_ANALOG_DOMICILE_FAILURE__ | Fallimento della richiesta di prepare (preparazione ad invio) cartaceo a paperChannel |
</details>
<details>
<summary>Eventi di timeline - v2 (tutti gli elementi v1 + gli elementi seguenti)</summary>
| Categoria | Descrizione |
|-----------|-------------|
|__NOTIFICATION_CANCELLATION_REQUEST__ | Richiesta di annullamento di una notifica |
|__NOTIFICATION_CANCELLED__ | Notifica annullata: completamento della richiesta di annullamento di una notifica |
|__PREPARE_ANALOG_DOMICILE_FAILURE__ | Fallimento della richiesta di prepare (preparazione ad invio) cartaceo a paperChannel |
</details>
<details>
<summary>Eventi di timeline - v2.3 (tutti gli elementi v1 + v2 + gli elementi seguenti)</summary>
| Categoria | Descrizione |
|-----------|-------------|
|__NOTIFICATION_RADD_RETRIEVED__ | Accesso alla notifica tramite la rete RADD. Non perfeziona la notifica |
</details>
<details>
<summary>Eventi di timeline - v2.6 (tutti gli elementi v1 + v2 + v2.3 + gli elementi seguenti)</summary>
| Categoria | Descrizione |
|-----------|-------------|
|__ANALOG_WORKFLOW_RECIPIENT_DECEASED__ | Destinatario deceduto |
</details>
## Segregazione per gruppi (dalla versione 2.3)
Così come notifiche, api-key e utenti dell'ente mittente possono essere
segregati in gruppi, nella versione 2.3 dell'API è stata introdotta la
segregazione dei flussi per gruppo.
Ad un flusso possono essere associati uno o più gruppi per cui: - presenterà
esclusivamente gli eventi relativi alle notifiche associate ai tali gruppi:
- in fase di creazione potranno essere associati i gruppi associati
all'api-key utilizzata. - solo le api-key con visibilità su tutti i gruppi
del flusso possano modificarlo, cancellarlo e consumare gli eventi.
__NOTA__: Le api-key senza associazione a gruppi possono agire su tutti i
gruppi.
## Operazioni sugli stream
Le operazioni sugli stream (tag __Streams__) per la gestione della
configurazione:
- [Creazione](#/Streams/createEventStream)
- [Elenco degli stream configurati](#/Streams/listEventStreams)
- [Recupero Configurazione](#/Streams/retrieveEventStream)
- [Modifica Configurazione](#/Streams/updateEventStream)
- [Cancellazione](#/Streams/removeEventStream)
- [Disabilitazione](#/Streams/disableEventStream)
## Procedura di migrazione agli stream v2.3
Per migrare uno stream dalla versione precedente è sufficiente indicare nel
parametro _replacedId_ l'identificativo dello stream precedente in fase di
creazione.
Il nuovo stream viene creato e contemporaneamente lo stream precedente viene
disabilitato.
Il mittente deve mantenere attiva la lettura sullo stream precedente fino a
consumare tutti gli eventi contenuti e poi migrare la lettura sul nuovo
stream.
## Disabilitazione di uno stream (dalla versione 2.3)
Dalla versione 2.3 è possibile disabilitare uno stream tramite la chiamata
alla API _disableEventStream_.
Uno stream disabilitato non può essere riabilitato, ma è possibile consumare
gli eventuali eventi e sarà eliminato automaticamente dopo <span
id="webhookTtlDisabled">14</span> giorni.
## Controllo della pubblicazione degli eventi (dalla versione 2.6)
Dalla versione 2.6 in fase di [creazione](#/Streams/createEventStreamV27) di
uno stream è stato introdotto <b>waitForAccepted</b> un flag booleano che
controlla la pubblicazione degli eventi in uno stream. Per gli stream di
<b>TIMELINE</b>, se impostato su true, ritarda la pubblicazione degli
eventi fino a quando non viene ricevuto un evento di accettazione o rifiuto
della notifica. Gli eventi con stato <b><code>IN_VALIDATION</code></b>
vengono comunque pubblicati immediatamente. Per gli stream di tipo
<b>STATUS</b>, assicura che il primo stato pubblicato sia
<b><code>ACCEPTED</code></b> o <b><code>REFUSED</code></b>. Sebbene
normalmente gli eventi dello stream arrivino nell'ordine cronologico in cui
si verificano, non è garantito che possano arrivare in un ordine differente.
Gli ID dello stream sono comunque crescenti, ma la data dell'evento potrebbe
non essere sempre successiva agli eventi precedenti.
## Lettura degli eventi dallo stream
Le operazioni con il tag __Events__ sono quelle utilizzate per la [lettura
degli eventi](#/Events/consumeEventStream) filtrati in base alla
configurazione impostata negli streams.
La API restituisce un __massimo di <span id="webhookMaxLength">50</span>
elementi per chiamata__.
Se esistono ulteriori eventi nello stream, allora la response del servizio
restituisce l'elemento `retryAfter = 0`; ed è quindi possibile richiamare
immediatamente il servizio per ottenere gli eventi successivi.
Per il corretto consumo degli eventi dello stream è necessario passare a
tutte le chiamate (ad esclusione della prima) il parametro _lastEventId_
valorizzato con l'ultimo _eventId_ della richiesta precedente. In questo
modo si informa che gli eventi precedenti sono stati elaborati e quindi
possibile procedere con la loro cancellazione dallo stream e restituire i
successivi.
Se non esistono ulteriori eventi nello stream, allora la response del
servizio restituisce il valore di `retryAfter > 0` ed è quindi necessario
attendere il tempo indicato dalla retryAfter per consumare eventualmente
nuovi eventi nello stream.
__NOTA__: gli eventi sono mantenuti per un massimo di __<span
id="webhookTtl">7</span> giorni__ dopo i quali sono automaticamente
cancellati anche se non sono stati consumati. Sarà comunque possibile
ottenere lo stato della notifica attraverso il servizio
[getNotificationRequestStatus](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/pagopa/pn-delivery/8e2dc3447abc5a338b9e7bc809fa2381d3dacada/docs/openapi/api-external-b2b-pa-bundle.yaml#/SenderReadB2B/retrieveSentNotificationV24)
<details>
<summary>Esempio di utilizzo della API</summary>
### Flusso contenente tutte le notifiche in stato Cancellato:
Il payload da passare alla API di creazione del flusso _createEventStream_ è
```json
{
"title": "NotificationCancelled",
"eventType": "STATUS",
"groups": [],
"filterValues": [
"CANCELLED"
]
}
```
### Flusso contenente tutte le notifiche in stato Accettato o Consegnato:
Il payload da passare alla API di creazione del flusso _createEventStream_ è
```json
{
"title": "NotificationAcceptedOrDelivered",
"eventType": "STATUS",
"groups": [],
"filterValues": [
"ACCEPTED","DELIVERED"
]
}
```
### Flusso contenente tutti gli eventi di timeline NOTIFICATION_VIEWED:
Il payload da passare alla API di creazione del flusso _createEventStream_ è
```json
{
"title": "TimelineNotificationViewed",
"eventType": "TIMELINE",
"groups": [],
"filterValues": [
"NOTIFICATION_VIEWED"
]
}
```
### Flusso contenente tutti gli eventi per le notifiche create con il gruppo
"contravvenzioni":
Il payload da passare alla API di creazione del flusso _createEventStream_ è
```json
{
"title": "TimelineNotificationViewed",
"eventType": "TIMELINE",
"groups": ["contravvenzioni"],
"filterValues": []
}
```
NOTA: solo api-key "master" o con il gruppo "contravvenzioni" possono creare
e consumare questo flusso.
### Flusso contenente tutti gli eventi di timeline NOTIFICATION_VIEWED per
le notifiche create con il gruppo "contravvenzioni" e "tributi":
Il payload da passare alla API di creazione del flusso _createEventStream_ è
```json
{
"title": "TimelineNotificationViewed",
"eventType": "TIMELINE",
"groups": ["contravvenzioni", "tributi"],
"filterValues": [
"NOTIFICATION_VIEWED"
]
}
```
NOTA: solo api-key "master" o con i gruppi "contravvenzioni" e "tributi"
possono creare e consumare questo flusso. Un'api-key con il SOLO gruppo
"contravvenzioni" infatti non potrà creare o accedere a questo flusso.
</details>
Le __FAQ__ possono essere consultate al seguente link:
[https://developer.pagopa.it/send/guides/knowledge-base](https://developer.pagopa.it/send/guides/knowledge-base)
contact:
name: 'SEND: supporto enti'
url: https://pagopa.atlassian.net/servicedesk/customer/portal/5
servers:
- url: https://api.notifichedigitali.it
description: Ambiente di produzione
- url: https://api.uat.notifichedigitali.it
description: Ambiente di collaudo
security:
- ApiKeyAuth: []
tags:
- name: HealthCheck
description: >-
Invocazioni per sapere lo stato di Piattaforma Notifiche # il servizio è
ancora in fase di sviluppo
- name: NewNotification
description: >-
Invocazioni per effettuare il pre-caricamento dei documenti della notifica
e inviare notifiche
- name: SenderReadB2B
description: >-
Invocazioni utilizzabili dai mittenti per verificare lo stato delle
richieste di notifica inviate e delle notifiche accettate.
- name: NotificationPrice
description: Invocazioni per determinare il costo della notifica per il destinatario.
- name: LegalFacts
description: Invocazioni per effettuare il download degli atti opponibili a terzi
- name: PaymentEvents
description: Invocazioni per comunicare eventi di pagamento dalla PA
- name: NotificationCancellation
description: Annullamento di una notifica
- name: Streams
description: Gestione degli stream di eventi che PN mette a disposizione
- name: Events
description: Metodi per la lettura degli eventi dagli stream
paths:
/status:
get:
summary: status path
description: status path per verificare lo stato di Piattaforma Notifiche
tags:
- HealthCheck
operationId: status
responses:
'200':
description: Ok
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PnStatusResponse'
example:
functionalities:
- NOTIFICATION_CREATE
- NOTIFICATION_VISUALIZATION
- NOTIFICATION_WORKFLOW
openIncidents: []
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/PnStatusResponse'
example:
functionalities:
- NOTIFICATION_CREATE
- NOTIFICATION_VISUALIZATION
- NOTIFICATION_WORKFLOW
openIncidents:
- functionality: NOTIFICATION_CREATE
status: KO
startDate: '2019-08-24T14:15:22Z'
/delivery/attachments/preload:
post:
summary: Richiesta di pre-caricamento dei documenti della notifica
description: >-
Operazione che richiede a Piattaforma Notifica le informazioni e le
autorizzazioni necessarie a precaricare uno o più file da allegare a
una notifica. <br/>
tags:
- NewNotification
operationId: presignedUploadRequest
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PreLoadRequest'
minItems: 1
maxItems: 15
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PreLoadResponse'
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/v2.5/requests:
post:
summary: EXPERIMENTAL - Richiesta invio notifica
description: >-
(EXPERIMENTAL)
Operazione utilizzata dalla Pubblica Amministrazione per richiedere
l'invio di una notifica.
La restituzione di uno stato HTTP 202 significa solo che la richiesta è
sintatticamente
valida, non che la richiesta sia stata validata ed accettata. <br/>
Per conoscere lo stato di accettazione della richiesta di notifica
bisogna utilizzare l'operazione
_getNotificationRequestStatus_ oppure utilizzare la modalità push
prevista dai webhook. <br/>
tags:
- NewNotification
operationId: sendNewNotificationV25
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewNotificationRequestV25'
required: true
responses:
'202':
description: Accepted
content:
application/json:
schema:
$ref: '#/components/schemas/NewNotificationResponse'
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'409':
description: Conflict
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
get:
operationId: retrieveNotificationRequestStatusV25
tags:
- SenderReadB2B
summary: EXPERIMENTAL - Verifica accettazione richiesta notifica
description: >-
(EXPERIMENTAL) Questa operazione serve per verificare se la richiesta di
notifica è stata accettata e ottenere lo IUN associato a tale richiesta.
<br/> Bisogna specificare il parametro _requestId_ oppure la coppia
costituita dai parametri _paProtocolNumber_ e _idempotenceToken_. <br/>
parameters:
- $ref: '#/components/parameters/notificationRequestId'
- $ref: '#/components/parameters/paProtocolNumber'
- $ref: '#/components/parameters/idempotenceToken'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NewNotificationRequestStatusResponseV25'
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/v2.7/notifications/sent/{iun}:
get:
summary: 'EXPERIMENTAL - Mittente: lettura dettagli notifica versione 2'
description: >-
(EXPERIMENTAL)
Questa operazione permette di leggere tutti i dettagli di una notifica
accettata. <br/>
tags:
- SenderReadB2B
operationId: retrieveSentNotificationV27
parameters:
- $ref: '#/components/parameters/pathIun'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FullSentNotificationV27'
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/notifications/sent/{iun}/attachments/documents/{docIdx}:
get:
description: Download documento notificato
summary: Download documento notificato
tags:
- SenderReadB2B
operationId: retrieveSentNotificationDocument
parameters:
- $ref: '#/components/parameters/pathIun'
- $ref: '#/components/parameters/pathDocumentIdx'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/NotificationAttachmentDownloadMetadataResponse
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/notifications/sent/{iun}/attachments/payment/{recipientIdx}/{attachmentName}:
get:
description: Download allegato per pagamento
summary: Download allegato per pagamento
tags:
- SenderReadB2B
operationId: retrieveSentNotificationAttachment
parameters:
- $ref: '#/components/parameters/pathIun'
- $ref: '#/components/parameters/pathRecipientIdx'
- $ref: '#/components/parameters/pathAttachmentName'
- $ref: '#/components/parameters/attachmentIdx'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: >-
#/components/schemas/NotificationAttachmentDownloadMetadataResponse
'400':
description: Bad request
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/v2.3/price/{paTaxId}/{noticeCode}:
get:
operationId: retrieveNotificationPriceV23
summary: Retrieve notification partial price and total price with effective date
description: >-
Usata dagli enti per recuperare il costo di notificazione tramite
l'identificativo della posizione debitoria paTaxId e noticeCode. Viene
restituito sia il costo parziale che il costo totale di notificazione.
tags:
- NotificationPriceV23
parameters:
- name: paTaxId
description: Payment PA fiscal code
in: path
required: true
example: '77777777777'
schema:
$ref: '#/components/schemas/paTaxId'
- name: noticeCode
description: Payment notice number numero avviso
in: path
required: true
example: '302000100000019421'
schema:
$ref: '#/components/schemas/noticeCode'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationPriceResponseV23'
'400':
description: Invalid input
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not Found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/events/payment/pagopa:
post:
operationId: paymentEventsRequestPagoPa
description: >-
Questa API è a disposizione della Pubblica Amministrazione per inviare
eventi di chiusura di una o più posizioni debitorie di tipo PagoPA.
<br/>
tags:
- PaymentEvents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEventsRequestPagoPa'
responses:
'204':
description: OK
'400':
description: Invalid input
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not found
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'500':
description: Internal Server Error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/delivery/events/payment/f24:
post:
deprecated: true
operationId: paymentEventsRequestF24
description: >-
Questa API è a disposizione della Pubblica Amministrazione per inviare
eventi di chiusura di una o più posizioni debitorie di tipo F24. <br/>
tags:
- PaymentEvents
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentEventsRequestF24'
responses:
'204':
description: OK
'400':
description: Invalid input
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'404':
description: Not found
content:
application/problem+json: