What is PN Paper Channel?
PN Paper Channel (pn-paper-channel) is the microservice within PagoPA’s Piattaforma Notifiche platform that handles every aspect of paper-based notification delivery. When a digital notification cannot be delivered, the platform falls back to physical mail. Paper Channel owns that entire physical-mail lifecycle: it validates delivery addresses, calculates postage costs, coordinates document preparation, dispatches postal requests, and processes the resulting delivery status events.
The service exposes two sets of REST APIs:
- Internal API (
/paper-channel-private/v1/...) — used by other PN microservices (primarily Delivery Push) to submit and monitor prepare and send requests. - Back-office API (
/paper-channel-bo/v1/...) — used for managing tender contracts, delivery drivers, and postal rate tables.
Roles in the notification lifecycle
Prepare phase
Before any letter is sent, Paper Channel must validate the recipient’s address and determine the correct postal product and cost. A caller submits aPOST /paper-channel-private/v1/b2b/paper-deliveries-prepare/{requestId} request. Paper Channel responds synchronously with HTTP 204 (accepted) or HTTP 200 (address confirmed immediately). If further processing is needed — for example, a lookup in the National Registries or document weight calculation — the service continues asynchronously and pushes the result back through SQS.
Send phase
Once an address is confirmed, the caller submits aPOST /paper-channel-private/v1/b2b/paper-deliveries-send/{requestId} request. Paper Channel validates the request against the prior prepare result, checks for any cost delta, and forwards the postal request synchronously to External Channel. The response includes the confirmed delivery address and the cost in euro cents.
Event processing
External Channel sends delivery status updates (tracking events, acceptance scans, custody notices, refinement codes) back to Paper Channel over SQS. Paper Channel processes these events through a chain of message handlers, updates DynamoDB state, and forwards outcome events to Delivery Push via SQS and EventBridge.System context
Paper Channel integrates with the following services:| Service | Role |
|---|---|
| External Channel | Dispatches postal requests to physical carriers; sends back tracking events |
| National Registries | Provides verified recipient addresses from civil registry sources |
| Safe Storage | Stores and retrieves notification documents (PDFs, attachments) |
| Data Vault | Pseudonymises and encrypts personally identifiable information |
| Address Manager | Normalises and validates Italian postal addresses |
| F24 | Generates F24 tax-payment PDF attachments on demand |
| RADD Alt | Provides alternative access points for paper-based document retrieval |
| Paper Tracker | Tracks physical mail item progress for supported products |
Technologies
| Technology | Purpose |
|---|---|
| Spring Boot 3 | Application framework (parent pn-parent 2.1.2-SPRINGBOOT3) |
| Spring WebFlux / Project Reactor | Fully reactive, non-blocking request handling |
| DynamoDB Enhanced Client | Persistence for delivery requests, costs, events, and tender data |
| AWS SQS (Spring Cloud AWS) | Asynchronous messaging between PN services |
| AWS KMS + AWS Encryption SDK | Envelope encryption of sensitive address data at rest |
| AWS EventBridge | Publishing PaperChannelOutcomeEvent outcomes to downstream consumers |
| Apache PDFBox | PDF document inspection and page-count calculation |
Architecture
Understand the layered design, REST controllers, DynamoDB tables, and queue topology.
Quickstart
Clone the repo, configure LocalStack, and send your first prepare request in minutes.