Prima di inviare una fattura o un ordine, vuoi sapere se il destinatario è raggiungibile. Con l'endpoint queryRecipientParty verifichi in una singola chiamata se un'organizzazione è registrata su Peppol, quali tipi di documento accetta e tramite quale canale il PSB consegnerà il documento. Questo previene errori di consegna e ti consente di dare ai tuoi utenti un feedback diretto.

Il PSB esegue automaticamente un lookup SML/SMP ad ogni consegna per trovare l'Access Point corretto del destinatario. Con queryRecipientParty puoi eseguire lo stesso lookup in anticipo, senza inviare effettivamente un documento.

L'API verifica:

• Se il destinatario è registrato nella rete Peppol (registrazione SMP)
• Quali tipi di documento può accettare il destinatario (capabilities)
• Tramite quale Access Point viene instradata la consegna
• Quale canale utilizzerà il PSB (Peppol, DICO, email fallback, ecc.)

GET /api/v1/queryRecipientParty?identifier={schemeID}:{id}

Sostituisci {schemeID} con lo schema di identificazione e {id} con il numero del destinatario. Utilizza uno dei comuni identificatori Peppol:

GET /api/v1/queryRecipientParty?identifier=0106:12345678

Se il destinatario è raggiungibile, l'API restituisce l'identificatore raccomandato e il canale che il PSB utilizzerà:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery"
}

Usa il valore di id come EndpointID nel tuo documento UBL.

Se il destinatario non viene trovato su Peppol, l'API restituisce un 404 con un messaggio di errore:

{
  "helpLink": "https://psb.econnect.eu/endpoints/v1/SalesInvoice.html#query-recipient-party",
  "message": "PartyId 'NL:KVK:12345678' not found in Peppol.",
  "code": "API404",
  "requestId": "41cd5529904be94d941137068c1c3fa1",
  "dateTime": "2026-03-14T10:22:19.4878393+00:00"
}

Suggerimento: un'organizzazione ha più identificatori (KvK, IVA, OIN)? Prova un schemeID diverso. Non tutti i destinatari sono registrati sotto ogni identificatore. Ad esempio: un'organizzazione è registrata come 0106:12345678 (KvK) ma non come 0088:5412345678908 (GLN). Ricevi un 404? Prova sempre il numero della Camera di Commercio (0106) o il numero IVA (9944) come alternativa, oppure usa la variante POST per verificare più identificatori contemporaneamente.

Se desideri verificare più identificatori contemporaneamente, usa la variante POST. Il PSB valuta tutti gli identificatori e restituisce l'opzione migliore:

POST /api/v1/{partyId}/salesInvoice/queryRecipientParty

Il {partyId} nell'URL è il tuo partyId (mittente). Nel corpo della richiesta, fornisci un array di possibili identificatori del destinatario:

["0106:12345678", "9944:NL123456789B01", "0190:00000001234567890000"]

Questo è utile quando non sai sotto quale identificatore è registrato il destinatario. L'API seleziona automaticamente la migliore corrispondenza.

Con ?includeOptions=true la risposta contiene un array options con tutti i canali di consegna disponibili:

{
  "id": "NL:KVK:12345678",
  "channel": "peppol",
  "description": "default send via peppol delivery",
  "options": [
    {
      "channel": "peppol",
      "description": "default send via peppol delivery",
      "identifiers": [
        {
          "partyId": {
            "text": "NL:KVK:12345678",
            "value": "12345678",
            "schemeAuthority": "iso6523-actorid-upis",
            "schemeIdText": "NL:KVK",
            "schemeIdNumber": "0106"
          },
          "isValid": true
        }
      ]
    }
  ]
}

Usa queryRecipientParty come verifica preliminare nelle seguenti situazioni:

• Prima dell'invio: verifica se il destinatario è raggiungibile prima di chiamare l'endpoint di invio, in modo da poter dare un feedback diretto ai tuoi utenti finali
• Onboarding delle relazioni: verifica durante la creazione di un nuovo cliente o fornitore se è già registrato su Peppol
• Instradamento multicanale: consulta quale canale di consegna selezionerà il PSB (Peppol, DICO, email) e opzionalmente forza un canale alternativo tramite il parametro ?channel durante l'invio
• Self-billing: verifica se un fornitore ha la capability di self-billing prima di inviare una fattura di autofatturazione

Nota: il lookup verifica la registrazione al momento della chiamata. Tra il lookup e la consegna effettiva, una registrazione potrebbe cambiare. In pratica questo è raro, ma tienilo presente per lotti di grandi dimensioni con un ritardo tra la verifica e la consegna.

Suggerimento: vuoi verificare manualmente una registrazione SMP, al di fuori dell'API? OpenPeppol offre il Peppol Lookup Service, dove puoi interrogare direttamente i dati SMP e Business Card di un partecipante Peppol. Utile per verificare se una registrazione è configurata correttamente.

Vuoi anche vedere quale Access Point e quali formati documento supporta esattamente un destinatario? L'endpoint Peppol delivery options fornisce una panoramica più dettagliata della registrazione SMP.

• Rete Peppol tramite l'API: SMP e capabilities
• Inviare una fattura tramite l'API
• Registrazione Peppol tramite l'API (Enrollment)
• Configurare la consegna multi-canale
• Cos'è Peppol e come funziona la rete?
• Registrarsi su Peppol (piattaforma)
• Fatturazione elettronica con eConnect