Paper messages

The paper messages endpoints drive the two-phase paper delivery workflow: prepare then send. You first submit a prepare request to validate the recipient address (potentially enriching it from national registries), then submit a send request to dispatch the physical correspondence.

Base path: /paper-channel-private/v1/b2bThis is an internal API. It is not exposed publicly and requires network-level access to the private Paper Channel service.

Send a prepare request

POST /paper-channel-private/v1/b2b/paper-deliveries-prepare/{requestId} Submit a preparation request for paper correspondence. Paper Channel validates the request synchronously and either:

Returns 204 — the service has accepted the request and will asynchronously resolve the final address (potentially querying pn-national-registries).
Returns 200 — if the same requestId was already processed, returns the latest update event.

Address data is stored in anonymised form using a hash. The request may include an optional F24 document URL; the prepare response will contain the SafeStorage file keys generated by pn-f24 to replace that URL.

Path parameters

requestId

string

required

Unique identifier for this prepare request. Used to correlate the asynchronous callback with the original request.

Minimum length: 5
Maximum length: 100

Request body

requestId

string

required

Must match the requestId path parameter.Example: ABCD-HILM-YKWX-202202-1_rec0_try1

iun

string

required

Notification IUN (Identificativo Univoco Notifica), required for audit purposes.Example: ABCD-HILM-YKWX-202202-1

clientRequestTimeStamp

string

required

Timestamp of the request in UTC (ISO 8601 date-time format).

proposalProductType

string

required

Proposed postal product type.Allowed values:

AR — Raccomandata Andata e Ritorno
890 — Recapito a norma della legge 890/1982
RS — Raccomandata Semplice (per Avviso di mancato Recapito)

printType

string

required

Print type requested from the consolidator.Examples: BN_FRONTE, BN_FRONTE_RETRO

receiverFiscalCode

string

required

Recipient fiscal code. Used to query ANPR for a registered address. Also passed to couriers for value-added services.

receiverType

string

required

Recipient type: PF (natural person) or PG (legal entity).

attachmentUrls

string[]

required

SafeStorage URLs for the documents to attach to the paper correspondence. Used to count the number of pages to print.

receiverAddress

object

Address to attempt delivery at. May be omitted if only a fiscal code is provided.

Show AnalogAddress properties

fullname

string

required

Recipient full name or company name.

address

string

required

Street address line 1.

nameRow2

string

Second name row on the envelope.

addressRow2

string

Second address line on the envelope.

cap

string

Postal code. Optional for international deliveries.

city

string

required

Municipality.

city2

string

Frazione (sub-municipality). Useful when the caller does not supply a postal code.

string

Province code. Optional for international deliveries.

country

string

Country, in UPU standard. Required for international deliveries.

When present, indicates that this request is a follow-up attempt to the request identified by this value.

discoveredAddress

object

Address discovered during a previous attempt. Same structure as receiverAddress.

notificationSentAt

string

Date and time the notification was created, in UTC.Example: 2022-07-27T12:22:33.444Z

aarWithRadd

boolean

Set to true if the notification is part of the RADD (Rete di Accesso Dedicata al Domicilio) pilot.

senderPaId

string

Identifier of the sending Public Administration.

Responses

Status	Meaning
`200`	The `requestId` was already processed. Returns the latest `PaperChannelUpdate` event.
`204`	New request accepted. Paper Channel will asynchronously resolve the address and push a `PaperChannelUpdate` via SQS.
`400`	Syntactic validation error.
`409`	A request with the same `requestId` but different parameters was already submitted.

200 response — `PaperChannelUpdate`

prepareEvent

object

The prepare phase event, when the update relates to address resolution.

Show PrepareEvent properties

requestId

string

required

The request identifier.

statusCode

string

required

PROGRESS — request is still being processed
OK — address validated and attachments retrieved
KO — no valid address could be determined

statusDetail

string

required

Detail code associated with the event.

statusDateTime

string

required

Event timestamp with timezone (ISO 8601).

failureDetailCode

string

Reason for failure when statusCode is KO:

D00 — address not found
D01 — invalid address
D02 — address matches the first-attempt address

receiverAddress

object

Resolved recipient address. Present when statusCode is OK.

Show AnalogAddress properties

fullname

string

required

Recipient full name or company name.

address

string

required

Street address.

nameRow2

string

Second name row on the envelope.

addressRow2

string

Second address line.

cap

string

Postal code.

city

string

required

Municipality.

city2

string

Frazione.

string

Province code.

country

string

Country (UPU standard).

productType

string

The effective product type to use for the send phase.

replacedF24AttachmentUrls

string[]

SafeStorage file keys that replace the original F24 URL.

categorizedAttachments

object

Categorisation result for the provided attachments.

Show CategorizedAttachmentsResult properties

acceptedAttachments

object[]

Attachments that passed validation.

Show ResultFilter properties

fileKey

string

SafeStorage file key.

result

string

Outcome: SUCCESS, DISCARD, or NEXT.

reasonCode

string

Reason code for the outcome.

reasonDescription

string

Human-readable reason.

discardedAttachments

object[]

Attachments that were discarded. Same structure as acceptedAttachments.

sendEvent

object

The send phase event, when the update relates to dispatch status. See the send request section for SendEvent field details.

clientId

string

Identifier of the client that generated the request, when available.

Asynchronous callback

After a 204 response, Paper Channel pushes one or more PaperChannelUpdate objects to an SQS queue associated with the caller. Poll GET prepare to check the current state, or consume updates from SQS.

curl --request POST \
  --url https://api.paperchannel.pagopa.local/paper-channel-private/v1/b2b/paper-deliveries-prepare/ABCD-HILM-YKWX-202202-1_rec0_try1 \
  --header 'Content-Type: application/json' \
  --data '{
    "requestId": "ABCD-HILM-YKWX-202202-1_rec0_try1",
    "iun": "ABCD-HILM-YKWX-202202-1",
    "clientRequestTimeStamp": "2024-03-15T10:30:00.000Z",
    "proposalProductType": "AR",
    "printType": "BN_FRONTE_RETRO",
    "receiverFiscalCode": "RSSMRA80A01H501U",
    "receiverType": "PF",
    "receiverAddress": {
      "fullname": "Mario Rossi",
      "address": "Via Roma 42",
      "cap": "00184",
      "city": "Roma",
      "pr": "RM",
      "country": "IT"
    },
    "attachmentUrls": [
      "safestorage://PN_NOTIFICATION_ATTACHMENTS-abc123def456"
    ],
    "senderPaId": "00414580183"
  }'

Retrieve prepare status

GET /paper-channel-private/v1/b2b/paper-deliveries-prepare/{requestId} Poll the current status of a previously submitted prepare request. Returns the latest PrepareEvent for that request.

Path parameters

requestId

string

required

The identifier of the prepare request to retrieve.

Minimum length: 5
Maximum length: 100

Responses

Status	Meaning
`200`	Returns the current `PrepareEvent`.
`404`	No prepare request found for the given `requestId`.

200 response — `PrepareEvent`

requestId

string

required

The request identifier.

statusCode

string

required

Current status:

PROGRESS — address resolution is still in progress
OK — address resolved and validated
KO — address resolution failed

statusDetail

string

required

Detail code for the status.

statusDateTime

string

required

Event timestamp with timezone (ISO 8601).

failureDetailCode

string

Failure reason when statusCode is KO:

D00 — address not found
D01 — invalid address
D02 — address matches the first-attempt address

receiverAddress

object

Resolved recipient address. Present only when statusCode is OK.

Show AnalogAddress properties

fullname

string

required

Recipient full name or company name.

address

string

required

Street address.

nameRow2

string

Second name row on the envelope.

addressRow2

string

Second address line.

cap

string

Postal code.

city

string

required

Municipality.

city2

string

Frazione.

string

Province code.

country

string

Country (UPU standard).

productType

string

The effective product type to use for the send phase.

replacedF24AttachmentUrls

string[]

SafeStorage file keys that replace the original F24 URL.

categorizedAttachments

object

Attachment categorisation result. See POST prepare response for full field details.

curl --request GET \
  --url https://api.paperchannel.pagopa.local/paper-channel-private/v1/b2b/paper-deliveries-prepare/ABCD-HILM-YKWX-202202-1_rec0_try1

{
  "requestId": "ABCD-HILM-YKWX-202202-1_rec0_try1",
  "statusCode": "OK",
  "statusDetail": "OK",
  "statusDateTime": "2024-03-15T10:30:05.123Z",
  "receiverAddress": {
    "fullname": "Mario Rossi",
    "address": "Via Roma 42",
    "cap": "00184",
    "city": "Roma",
    "pr": "RM",
    "country": "IT"
  },
  "productType": "AR"
}

Send a send request

POST /paper-channel-private/v1/b2b/paper-deliveries-send/{requestId} Dispatch a paper correspondence that was previously prepared. Paper Channel validates the request against the stored requestId, then synchronously calls External Channel. On success it returns the delivery cost in eurocents, the page count, and the envelope weight. If you submit multiple requests with the same requestId, the service returns the previously calculated result.

If the cost changed between the prepare and send phases, the service returns 422. You must re-run the prepare phase before retrying.

Path parameters

requestId

string

required

Identifier of the send request. Must correspond to a completed prepare request.

Minimum length: 5
Maximum length: 100

Request body

requestId

string

required

Must match the requestId path parameter.Example: ABCD-HILM-YKWX-202202-1_rec0_try1

iun

string

required

Notification IUN, required for audit purposes.

clientRequestTimeStamp

string

required

Timestamp of the request in UTC (ISO 8601).

requestPaId

string

required

Identifier of the PA that requested delivery. Used to authorise retrieval of original paper documents by public administrations.Example: 00414580183

productType

string

required

Postal product type for this send request.Allowed values:

AR — Raccomandata nazionale Andata e Ritorno
890 — Recapito a norma della legge 890/1982
RS — Raccomandata nazionale Semplice
RIS — Raccomandata internazionale Semplice
RIR — Raccomandata internazionale Andata e Ritorno

printType

string

required

Print type: e.g. BN_FRONTE, BN_FRONTE_RETRO.

receiverFiscalCode

string

required

Recipient fiscal code.

receiverType

string

required

PF or PG.

receiverAddress

object

required

Address to deliver to. Use the address returned by the prepare phase.

Show AnalogAddress properties

fullname

string

required

Recipient full name or company name.

address

string

required

Street address.

nameRow2

string

Second name row on envelope.

addressRow2

string

Second address line.

cap

string

Postal code.

city

string

required

Municipality.

city2

string

Frazione.

string

Province.

country

string

Country (UPU standard). Required for international deliveries.

senderAddress

object

required

Return address for the sender. Same structure as receiverAddress.

arAddress

object

Address for the acknowledgement of receipt (AR) document, if applicable. Same structure as receiverAddress.

attachmentUrls

string[]

required

SafeStorage URLs for the documents to attach to the correspondence.

senderPaId

string

Identifier of the sending Public Administration.

Responses

Status	Meaning
`200`	Delivery registered with External Channel. Returns cost and envelope details.
`400`	Syntactic validation error.
`404`	The `requestId` was not found, or the CAP/zone does not exist or has been decommissioned.
`409`	A send request with this `requestId` already exists and cannot be overwritten.
`422`	Cost changed since the prepare phase. Re-run the prepare phase.

200 response — `SendResponse`

amount

integer

required

Delivery cost in eurocents.

numberOfPages

integer

required

Number of pages in the postal shipment.

envelopeWeight

integer

required

Envelope weight in grams.

Asynchronous callbacks

After a successful send, Paper Channel pushes PaperChannelUpdate objects containing SendEvent entries to SQS as the shipment progresses through the postal network. Poll GET send to check the current state.

curl --request POST \
  --url https://api.paperchannel.pagopa.local/paper-channel-private/v1/b2b/paper-deliveries-send/ABCD-HILM-YKWX-202202-1_rec0_try1 \
  --header 'Content-Type: application/json' \
  --data '{
    "requestId": "ABCD-HILM-YKWX-202202-1_rec0_try1",
    "iun": "ABCD-HILM-YKWX-202202-1",
    "clientRequestTimeStamp": "2024-03-15T10:35:00.000Z",
    "requestPaId": "00414580183",
    "productType": "AR",
    "printType": "BN_FRONTE_RETRO",
    "receiverFiscalCode": "RSSMRA80A01H501U",
    "receiverType": "PF",
    "receiverAddress": {
      "fullname": "Mario Rossi",
      "address": "Via Roma 42",
      "cap": "00184",
      "city": "Roma",
      "pr": "RM",
      "country": "IT"
    },
    "senderAddress": {
      "fullname": "Comune di Milano",
      "address": "Piazza della Scala 2",
      "cap": "20121",
      "city": "Milano",
      "pr": "MI",
      "country": "IT"
    },
    "attachmentUrls": [
      "safestorage://PN_NOTIFICATION_ATTACHMENTS-abc123def456"
    ],
    "senderPaId": "00414580183"
  }'

{
  "amount": 350,
  "numberOfPages": 4,
  "envelopeWeight": 28
}

Retrieve send status

GET /paper-channel-private/v1/b2b/paper-deliveries-send/{requestId} Poll the current delivery status for a previously submitted send request. Returns the latest SendEvent for that request.

Path parameters

requestId

string

required

The identifier of the send request to retrieve.

Minimum length: 5
Maximum length: 100

Responses

Status	Meaning
`200`	Returns the current `SendEvent`.
`404`	No send request found for the given `requestId`.

200 response — `SendEvent`

requestId

string

required

The request identifier.

statusCode

string

required

Current status:

PROGRESS — shipment update in transit
OK — delivery completed successfully
KO — delivery failed

statusDetail

string

required

Delivery status code. Mirrors External Channel codes plus internal Paper Channel codes (PNXXX).Format: statusDetail - [product] - [statusCode] - statusDescriptionCommon values:

CON080 — [ALL] [PROGRESS] Stampato ed Imbustato
RECRN001C — [AR] [OK] Consegnato - Fascicolo Chiuso
RECRN002C — [AR] [KO] Mancata consegna - Fascicolo Chiuso
RECAG001C — [890] [OK] Consegnato - Fascicolo Chiuso
RECRS001C — [RS] [OK] Consegnato - Fascicolo Chiuso
RECRI003C — [RIR] [OK] Consegnato - Fascicolo Chiuso
RECRSI003C — [RIS] [OK] Consegnato - Fascicolo Chiuso

statusDescription

string

Human-readable description of the delivery status.Example: Distacco d'ufficio 23L - Fascicolo Chiuso

statusDateTime

string

required

Event timestamp with timezone (ISO 8601).

registeredLetterCode

string

Tracking code for traceable postal products.Example: 123456789abc

deliveryFailureCause

string

Mandatory when statusCode is KO. Reason for failed delivery:

M01 — recipient not found at address
M02 — recipient deceased
M03 — recipient unknown
M04 — recipient relocated
M05 — delivery refused
M06 — inaccurate address
M07 — address does not exist
M08 — address insufficient
F01 — theft
F02 — loss
F03 — deterioration

attachments

object[]

Documents produced during the postal process.

Show AttachmentDetails properties

string

required

Row identifier.

documentType

string

required

Type of attached document.

url

string

required

URL to the correlated document.

date

string

required

Document production date (ISO 8601).

discoveredAddress

object

An updated address discovered during the delivery attempt.

Show AnalogAddress properties

fullname

string

required

Recipient full name or company name.

address

string

required

Street address.

cap

string

Postal code.

city

string

required

Municipality.

string

Province.

country

string

Country.

clientRequestTimeStamp

string

Timestamp of the original client request (ISO 8601).

curl --request GET \
  --url https://api.paperchannel.pagopa.local/paper-channel-private/v1/b2b/paper-deliveries-send/ABCD-HILM-YKWX-202202-1_rec0_try1

{
  "requestId": "ABCD-HILM-YKWX-202202-1_rec0_try1",
  "statusCode": "OK",
  "statusDetail": "RECRN001C",
  "statusDescription": "Consegnato - Fascicolo Chiuso",
  "statusDateTime": "2024-03-16T09:15:22.000Z",
  "registeredLetterCode": "123456789abc",
  "attachments": [
    {
      "id": "att-001",
      "documentType": "Ricevuta di ritorno",
      "url": "safestorage://PN_PAPER_CHANNEL-xyza9876",
      "date": "2024-03-16T09:15:00.000Z"
    }
  ]
}

Internal API

Back-Office API

Lambda API

Send a prepare request

Path parameters

Request body

Responses

200 response — `PaperChannelUpdate`

Asynchronous callback

Retrieve prepare status

Path parameters

Responses

200 response — `PrepareEvent`

Send a send request

Path parameters

Request body

Responses

200 response — `SendResponse`

Asynchronous callbacks

Retrieve send status

Path parameters

Responses

200 response — `SendEvent`

Build docs developers (and LLMs) love

Internal API

Back-Office API

Lambda API

​Send a prepare request

​Path parameters

​Request body

​Responses

​200 response — PaperChannelUpdate

​Asynchronous callback

​Retrieve prepare status

​Path parameters

​Responses

​200 response — PrepareEvent

​Send a send request

​Path parameters

​Request body

​Responses

​200 response — SendResponse

​Asynchronous callbacks

​Retrieve send status

​Path parameters

​Responses

​200 response — SendEvent

Build docs developers (and LLMs) love

Send a prepare request

Path parameters

Request body

Responses

200 response — `PaperChannelUpdate`

Asynchronous callback

Retrieve prepare status

Path parameters

Responses

200 response — `PrepareEvent`

Send a send request

Path parameters

Request body

Responses

200 response — `SendResponse`

Asynchronous callbacks

Retrieve send status

Path parameters

Responses

200 response — `SendEvent`