How pn-paper-channel models procurement contracts (tenders), delivery drivers, and postal cost calculations.
A tender (gara d’appalto) is a procurement contract between PagoPA and one or more postal operators. It defines which operators can deliver which postal products, at what price, to which geographic zones, during a specific validity period. Every shipment cost calculation in pn-paper-channel traces back to an active tender.
A PnTender record can be in one of three effective states, computed at runtime by PnTender.getActualStatus():
Status
Meaning
CREATED
Tender created but not yet validated
VALIDATED
Tender validated; becomes IN_PROGRESS when now is between startDate and endDate
IN_PROGRESS
Currently active — used for cost lookups
ENDED
endDate is in the past — no longer used for new shipments
Only one tender should be IN_PROGRESS at a time for a given product and geographic zone. The system picks the active tender during the Prepare phase via PaperTenderService.getSimplifiedCost().
A PnDeliveryDriver represents a postal operator (recapitista) assigned to a tender. One tender can have multiple delivery drivers — for example, a national carrier and regional sub-carriers.
PnDeliveryDriver is stored in DynamoDB with tenderCode as the partition key and taxId as the sort key. A secondary index (tender-index) supports lookups by tender.
PnCost is stored in DynamoDB with driverCode as the partition key and uuidCode as the sort key. A secondary index (tender-index) on tenderCode supports cost lookups by tender.
A GeoKey maps a specific postal code (CAP) and product combination to a delivery zone and driver. PnPaperChannelGeoKey holds this mapping and is used during the cost lookup step in phase 1 of the Prepare flow.The composite partition key tenderProductGeokey is constructed as:
The Utility.isNational() helper checks the country field of the resolved address. When a delivery is domestic (Italy), phase 1 of the Prepare flow looks up the cost from the active tender using the postal code (CAP). When the delivery is international, the request is forwarded to the phase-2 queue, which handles attachment processing separately and uses country-code–based zone lookups.
International deliveries use the destination country code as the geokey instead of a CAP. Make sure your tender configuration includes PnCost records for each destination country you intend to serve.