Bevor Sie eine Rechnung oder Bestellung versenden, möchten Sie wissen, ob der Empfänger erreichbar ist. Mit dem queryRecipientParty-Endpunkt prüfen Sie in einem einzigen Aufruf, ob eine Organisation im Peppol-Netzwerk registriert ist, welche Dokumenttypen akzeptiert werden und über welchen Kanal die PSB das Dokument zustellt. So vermeiden Sie Zustellfehler und können Ihren Benutzern direktes Feedback geben.

Die PSB führt bei jeder Zustellung automatisch ein SML/SMP-Lookup durch, um den richtigen Access Point des Empfängers zu finden. Mit queryRecipientParty können Sie dasselbe Lookup vorab durchführen, ohne tatsächlich ein Dokument zu versenden.

Die API prüft:

• Ob der Empfänger im Peppol-Netzwerk registriert ist (SMP-Registrierung)
• Welche Dokumenttypen der Empfänger akzeptieren kann (Capabilities)
• Über welchen Access Point die Zustellung geroutet wird
• Welchen Kanal die PSB verwenden wird (Peppol, DICO, E-Mail-Fallback usw.)

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

Ersetzen Sie {schemeID} durch das Identifikationsschema und {id} durch die Nummer des Empfängers. Verwenden Sie einen der gängigen Peppol-Identifier:

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

Wenn der Empfänger erreichbar ist, gibt die API den empfohlenen Identifier und den Kanal zurück, den die PSB verwenden wird:

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

Verwenden Sie den Wert aus id als EndpointID in Ihrem UBL-Dokument.

Wenn der Empfänger nicht in Peppol gefunden wird, gibt die API einen 404 mit einer Fehlermeldung zurück:

{
  "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"
}

Tipp: Hat eine Organisation mehrere Identifier (KvK, USt-Nr., OIN)? Versuchen Sie eine andere schemeID. Nicht alle Empfänger sind unter jedem Identifier registriert. Zum Beispiel: Eine Organisation ist als 0106:12345678 (KvK) registriert, aber nicht als 0088:5412345678908 (GLN). Bei einem 404 sollten Sie immer die Handelskammernummer (0106) oder Umsatzsteuernummer (9944) als Alternative versuchen oder die POST-Variante nutzen, um mehrere Identifier gleichzeitig zu prüfen.

Wenn Sie mehrere Identifier gleichzeitig prüfen möchten, verwenden Sie die POST-Variante. Die PSB bewertet alle Identifier und gibt die beste Option zurück:

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

Die {partyId} in der URL ist Ihre eigene (sendende) partyId. Im Request-Body übergeben Sie ein Array möglicher Identifier des Empfängers:

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

Dies ist nützlich, wenn Sie nicht wissen, unter welchem Identifier der Empfänger registriert ist. Die API wählt automatisch die beste Übereinstimmung.

Mit ?includeOptions=true enthält die Antwort ein options-Array mit allen verfügbaren Zustellkanälen:

{
  "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
        }
      ]
    }
  ]
}

Verwenden Sie queryRecipientParty als Pre-Flight-Check in folgenden Situationen:

• Vor dem Versand: Prüfen Sie, ob der Empfänger erreichbar ist, bevor Sie den Send-Endpunkt aufrufen, damit Sie Ihren Endbenutzern direktes Feedback geben können
• Onboarding von Geschäftspartnern: Überprüfen Sie beim Anlegen eines neuen Kunden oder Lieferanten, ob dieser bereits im Peppol-Netzwerk registriert ist
• Multi-Channel-Routing: Sehen Sie, welchen Zustellkanal die PSB auswählen wird (Peppol, DICO, E-Mail), und erzwingen Sie optional beim Versand einen alternativen Kanal über den Parameter ?channel
• Self-Billing: Prüfen Sie, ob ein Lieferant über die Self-Billing-Fähigkeit verfügt, bevor Sie eine Gutschrift versenden

Hinweis: Das Lookup prüft die Registrierung zum Zeitpunkt des Aufrufs. Zwischen dem Lookup und der tatsächlichen Zustellung kann sich eine Registrierung ändern. In der Praxis kommt das selten vor, aber bedenken Sie dies bei großen Stapelverarbeitungen mit einer Verzögerung zwischen Prüfung und Zustellung.

Tipp: Möchten Sie eine SMP-Registrierung manuell prüfen, außerhalb der API? OpenPeppol bietet den Peppol Lookup Service, mit dem Sie die SMP- und Business-Card-Daten eines Peppol-Teilnehmers direkt abfragen können. Nützlich, um zu überprüfen, ob eine Registrierung korrekt konfiguriert ist.

Möchten Sie auch sehen, welchen Access Point und welche Dokumentformate ein Empfänger genau unterstützt? Der Peppol-Zustelloptionen-Endpunkt bietet eine detailliertere Übersicht der SMP-Registrierung.

• Peppol-Netzwerk über die API: SMP und Capabilities
• Eine Rechnung über die API versenden
• Peppol-Registrierung über die API (Enrollment)
• Multi-Channel-Zustellung konfigurieren
• Was ist Peppol und wie funktioniert das Netzwerk?
• Bei Peppol registrieren (Plattform)

• Peppol-Netzwerk über die API: SMP und Capabilities
• Rechnung über die API versenden
• Peppol-Registrierung über die API (Enrollment)
• Multi-Channel-Zustellung konfigurieren
• Was ist Peppol und wie funktioniert das Netzwerk?
• Auf Peppol registrieren (Plattform)
• E-Rechnungsstellung mit eConnect