Skip to main content

​
Overview

pn-national-registries is an aggregation gateway that routes address resolution requests to Italian public registries — primarily ANPR (Anagrafe Nazionale della Popolazione Residente) for physical persons and InfoCamere for legal entities. Paper Channel consults National Registries during the prepare phase when no valid delivery address is available for a recipient. The integration is asynchronous: Paper Channel fires a lookup request and immediately transitions the delivery request to the NATIONAL_REGISTRY_WAITING status. National Registries delivers the result later via a callback on the SQS queue pn.paper-channel.queue-national-registries.

Outbound: HTTP POST

NationalRegistryClient.finderAddress(...) submits an address lookup for a given fiscal code.

Inbound: SQS

National Registries pushes the resolved address (or a not-found indicator) back to the Paper Channel queue.

​
Prepare-phase lookup flow

Paper Channel (prepare)
  └─▶ NationalRegistryServiceImpl.finderAddressFromNationalRegistries(...)
        ├─▶ builds correlationId via Utility.buildNationalRegistriesCorrelationId(requestId)
        ├─▶ NationalRegistryClientImpl.finderAddress(correlationId, fiscalCode, personType)
        │     └─▶ POST /national-registries-private/{recipient-type}/addresses
        ├─▶ on success: sets entity.correlationId and transitions status → NATIONAL_REGISTRY_WAITING
        └─▶ on error:   saves NationalRegistryError, calls PrepareFlowStarter.redrivePreparePhaseOneAfterNationalRegistryError

... (async, via SQS) ...

National Registries → SQS queue-national-registries
  └─▶ Paper Channel SQS consumer processes AddressOKDto callback
        └─▶ resumes prepare phase with the resolved address

​
Client interface

// NationalRegistryClient.java
public interface NationalRegistryClient {
    Mono<AddressOKDto> finderAddress(
        String correlationId,
        String recipientTaxId,
        String recipientType   // "PF" for physical person, "PG" for legal entity
    );
}

​
Implementation — NationalRegistryClientImpl

The client calls the AddressApi.getAddresses operation:
  • Endpoint: POST /national-registries-private/{recipient-type}/addresses
  • Header: pn-national-registries-cx-id set from pnPaperChannelConfig.getNationalRegistryCxId()

​
Request body built by the client

// NationalRegistryClientImpl.java
AddressRequestBodyDto addressRequestBodyDto = new AddressRequestBodyDto();
AddressRequestBodyFilterDto filterDto = new AddressRequestBodyFilterDto();
filterDto.setCorrelationId(correlationId);
filterDto.setDomicileType(AddressRequestBodyFilterDto.DomicileTypeEnum.PHYSICAL);
filterDto.setTaxId(recipientTaxId);
filterDto.setReferenceRequestDate(DateUtils.getOffsetDateTimeFromDate(Instant.now()));
addressRequestBodyDto.setFilter(filterDto);
​
correlationId
string
required
Correlation identifier used to match the asynchronous callback. Built by Utility.buildNationalRegistriesCorrelationId(requestId).
​
taxId
string
required
Recipient fiscal code (or VAT number for legal entities).
​
domicileType
string
required
Always PHYSICAL — Paper Channel only requests physical postal addresses.
​
referenceRequestDate
string
required
ISO-8601 timestamp representing the reference date for the address lookup.

​
Response — AddressOKDto

The synchronous HTTP response acknowledges receipt of the request. The actual resolved address arrives asynchronously via SQS. The SQS payload is mapped to an AddressOKDto by the queue consumer and then used to resume the prepare flow.

​
Service layer — NationalRegistryServiceImpl

NationalRegistryServiceImpl implements NationalRegistryService and orchestrates the full lookup lifecycle: 
// NationalRegistryServiceImpl.java
public void finderAddressFromNationalRegistries(
    String requestId,
    String relatedRequestId,
    String fiscalCode,
    String personType,
    String iun,
    Integer attempt
) { ... }
On success (HTTP 200 from National Registries):
  1. Stores the correlationId on the PnDeliveryRequest entity.
  2. Transitions the request status to NATIONAL_REGISTRY_WAITING.
On error (any exception from finderAddress):
  1. Builds a NationalRegistryError object carrying iun, requestId, relatedRequestId, fiscalCode, and receiverType.
  2. Persists the error and transitions status to NATIONAL_REGISTRY_ERROR.
  3. Schedules a re-drive via PrepareFlowStarter.redrivePreparePhaseOneAfterNationalRegistryError(payload, attempt).

​
Configuration

PropertyDescriptionExample
pn.paper-channel.client-national-registries-basepathBase URL of the National Registries servicehttp://localhost:1080
pn.paper-channel.national-registry-cx-idClient identity header sent on every requestpn-paper-channel
pn.paper-channel.queue-national-registriesSQS queue name for incoming address callbackslocal-ext-channels-inputs
pn.paper-channel.attempt-queue-national-registriesMax consumer retry attempts on the inbound queue3

​
Error handling

Exception / StatusCauseBehaviour
NATIONAL_REGISTRY_LISTENER_EXCEPTIONError processing the inbound SQS callbackLogged; exception propagated to the queue consumer
NATIONAL_REGISTRY_ADDRESS_NOT_FOUNDNational Registries confirms no address exists for the fiscal codePrepare flow terminates with an unreachable-address outcome
NATIONAL_REGISTRY_ERROR (status)HTTP error from the synchronous finderAddress callError is persisted and re-drive is attempted
WebClientResponseExceptionNon-2xx HTTP responseResponse body is logged at ERROR level; exception re-emitted
The correlationId stored on the delivery request is the key used to correlate the asynchronous SQS callback with the original prepare request. Losing this value makes it impossible to resume the flow.
For physical persons (PF), National Registries routes the request to ANPR. For legal entities (PG), it routes to InfoCamere. The recipientType path parameter controls this routing.

Build docs developers (and LLMs) love

Get started for freeTalk to us