Docs

Eine Rechnung übergeben, die der Kunde über einen Übermittlungsweg erhalten hat

  • In der Sandbox
POST
/received

Seit 0.35.0 (17. Okt. 2026). Der Body ist das XML genau so, wie der Übermittlungsweg es geliefert hat (UBL, CII oder FA(3)); nichts wird geändert und nichts wird gesendet. Die Datei wird zuerst gespeichert, versiegelt unter dem Datenschlüssel des Kunden, weil sie rechtlich bereits empfangen ist; dann prüfen die eigenen Validatoren des Übermittlungswegs sie, wie bei einer Übermittlung im Durchreichen, und das Ergebnis kommt als Statusereignis (received, dann validated oder validation_failed, mit direction: in) am Webhook des Kunden und unter GET /received/{id}/events an. Eine Datei, die die Regeln nicht erfüllt, wird aufbewahrt und lautet validation_failed mit den Fehlern; sie wird nie verworfen. Eine Datei, die keine aufzubewahrende Rechnung ist, wird mit 422 abgelehnt, und nichts wird gespeichert, wie bei POST /invoices/xml: ein DOCTYPE (EI-XML-DTD, nie geparst), XML, das nicht wohlgeformt ist (EI-XML-SYNTAX), oder ein Dokument, das keine Rechnung ist, die der Übermittlungsweg kennt (EI-XML-TYPE). Eine Prüfung, die nicht laufen konnte (ein Validator ist ausgefallen), wird wiederholt, und nach der letzten Wiederholung kommt die Rechnung auf die Betreuungsliste und bleibt received. Ein Kunde übergibt höchstens 120 Dokumente pro Minute und 2.000 pro Tag, mit welchem Schlüssel auch immer (429, nicht unter dem Idempotency-Key aufbewahrt). Die Datei wird als Download zurückgegeben (Content-Disposition: attachment).

Ein Dokument des Übermittlungswegs ist eine empfangene Rechnung des Kunden: nach rail_id, wenn sie angegeben ist, sonst nach dem SHA-256 der Datei. Dasselbe Dokument erneut wird mit 202 und duplicate_of beantwortet; dieselbe rail_id mit anderen Bytes wird mit 409 received-id-conflict beantwortet, und nichts wird gespeichert. Empfangene Rechnungen werden getrennt von den Rechnungen aufbewahrt, die der Kunde sendet: Sie stehen nicht in GET /invoices, in der Serie, in den Metriken oder im Monatsbericht, und sie blockieren nie das Senden derselben Datei. Eine empfangene Rechnung wird mit der Aufbewahrungsfrist des Kunden gelöscht, sobald nichts mehr an ihr offen ist (ihre Prüfung ist beendet, oder eine Person hat ihre Betreuungszeile erledigt), und sie steht im Export des Kunden unter received/. Der Scope submit; ein Kundenschlüssel handelt nur für seinen eigenen Kunden.

Autorisierung

apiKey
headerAuthorizationBearer <token>

Senden Sie Ihren Schlüssel als Bearer-Token: Authorization: Bearer <your-api-key>. Der Systemzustand ist der einzige Aufruf, der keinen Schlüssel braucht.

Query-Parameter

route*string

Der Übermittlungsweg, über den das Dokument kam.

Wert in"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"
rail_id?string

Die eigene ID des Übermittlungswegs für das Dokument (die Dokument-ID des Access Points, die KSeF-Nummer, die Download-ID der ANAF). 1 bis 200 Buchstaben, Ziffern und . _ : / @ + = # -.

Muster^[A-Za-z0-9._:/@+=#-]{1,200}$
client?string

Der Kunde, der es erhalten hat. Der Schlüssel des Betreibers nennt ihn (weggelassen: der eigene Kunde local des Betreibers); ein Kundenschlüssel darf ihn weglassen oder seinen eigenen Kunden nennen, und jeder andere wird mit 403 beantwortet.

Muster^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$

Header-Parameter

Idempotency-Key*string

Ein eindeutiger Schlüssel je logischer Anfrage (eine UUID genügt). Ein Schlüssel, der mit erp: beginnt (das erp:{connector}:{scope}:{entity}:{id} eines ERP-Transportrezepts, mit dem Schlüssel des Betreibers oder eines Kunden), hat kein Zeitfenster; er wird mit seiner ersten Antwort aufbewahrt, bis der Kunde oder die Rechnung, die er erzeugt hat, gelöscht wird, sodass ein geändertes Dokument, das Wochen später erneut übergeben wird, weiterhin 409 idempotency-conflict erhält. Ein solcher Schlüssel wird nur bei einem Export eines ERP-Connectors angenommen (POST /invoices mit einem connector, den dieser Build liest, einem export, das ein nicht leeres JSON-Objekt ist, und mit dem Schlüssel des Betreibers client); bei jeder anderen Anfrage, einem kanonischen Dokument, POST /invoices/xml oder einem Storno, wird er mit 400 idempotency-key-not-allowed beantwortet, und nichts wird aufbewahrt; ein Export mit einer Zahl von mehr als 40 Zeichen erhält die 422 EI-SCHEMA, die er auch unter jedem anderen Schlüssel erhält, ebenfalls unter keinem Schlüssel aufbewahrt. Gibt der Betreiber eine Dead Letter frei (storniert sie), gehen die früheren Antworten zu dieser Rechnung mit, die der Übermittlung und, seit 0.35.0, die eines früheren abgelehnten Stornos, sodass eine Wiederholung dieses Stornos erneut läuft und mit 200 und der stornierten Rechnung antwortet. Seit 0.32.0 werden eine 5xx-Antwort und eine 422 connector-settings-missing nicht aufbewahrt, sodass dieselbe Anfrage mit demselben Schlüssel erneut gesendet werden kann. Mit dem Schlüssel des Betreibers darf er nicht mit client: beginnen (400), der Form, unter der Kundenschlüssel gespeichert werden.

Länge8 <= length <= 100

Anfrage-Body

body*stringapplication/xml

Antwort-Body

Gespeichert und für die Prüfung des Übermittlungswegs eingereiht, sofern sie nicht schon fehlgeschlagen ist; oder bereits vorhanden (duplicate_of).

application/json
  1. response

Seit 0.35.0. Eine Rechnung, die der Kunde über einen Übermittlungsweg erhalten hat, so wie POST /received sie angenommen hat. Wie Invoice enthält sie keinen Rechnungsinhalt: keinen Verkäufer, Käufer und keine Beträge.

id*string
Muster^rcv_[0-9a-f]{24}$
invoice_ref*string

Die eigene Rechnungsnummer der Datei (BT-1; FA(3) Fa/P_2), sonst die rail_id, sonst die ID.

invoice_number?string
route*Route

Der Übermittlungsweg. Dieselben Werte wie country_route in Statusereignissen.

Wert in"PEPPOL""PL-KSEF""RO-EFACTURA""FR-PA""DE-XRECHNUNG"
client*string
environment*string
Wert in"sandbox""production"
state*string
Wert in"received""validated""validation_failed"
direction*"in"
Wert in"in"
rail_id?string

Die eigene ID des Übermittlungswegs für das Dokument, wie bei POST /received angegeben.

document_sha256*string
Muster^[a-f0-9]{64}$
duplicate_of?string

Nur bei POST /received, wenn das Dokument für den Kunden und den Übermittlungsweg bereits vorhanden war.

links?
errors?array<>
documents?array<>
created_at*string
Formatdate-time
updated_at*string
Formatdate-time
curl -X POST "https://example.com/received?route=PEPPOL" \  -H "Authorization: Bearer <your-api-key>" \  -H "Idempotency-Key: order-2026-0001" \  -H "Content-Type: application/xml" \  -d 'string'
{  "id": "string",  "invoice_ref": "string",  "invoice_number": "string",  "route": "PEPPOL",  "client": "string",  "environment": "sandbox",  "state": "received",  "direction": "in",  "rail_id": "string",  "document_sha256": "string",  "duplicate_of": "string",  "links": {    "self": "string",    "events": "string"  },  "errors": [    {      "code": "string"    }  ],  "documents": [    {      "kind": "received-xml",      "sha256": "string",      "href": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z"}