Przekazywanie plików

ERP, który potrafi tylko zapisywać pliki, może przekazywać faktury przez jeden folder. Usługa obserwuje folder i traktuje każdy plik jak przesłanie: plik JSON jak POST /invoices, plik XML jak POST /invoices/xml. Wyniki wracają jako pliki w tym samym folderze.

KonfiguracjaKopiuj link do tej sekcji

Folder ustawia się przy instalacji usługi. Usługa sprawdza go raz na sekundę, a gdy folder nie jest ustawiony, niczego nie obserwuje. Plik przechodzi przez to samo przyjęcie co wywołanie API, więc jest odrzucany z tych samych powodów.

Nazwa plikuKopiuj link do tej sekcji

• Numer referencyjny faktury ma maksymalnie 100 znaków i nie zawiera / ani \.
• Plik większy niż 5 MB jest odrzucany.
• Plik, którego nazwa zaczyna się od kropki, zawiera .. lub nie pasuje do żadnego z wzorców, jest pomijany.
• Idempotency-Key to pierwsze 32 znaki skrótu SHA-256 pliku. Ponowne umieszczenie identycznego pliku jest powtórzeniem, a nie drugą fakturą.

Co wracaKopiuj link do tej sekcji

drop/
  DE-4711.json            you write this
  status/
    DE-4711-1.json        one file per status event
    DE-4712-error.json    the answer to a refused file
  done/
    DE-4711.json          an accepted file moves here
  failed/
    DE-4712.json          a refused file moves here

Przyjęty plik trafia do done/. Zdarzenia faktury są zapisywane w status/, jeden plik na zdarzenie, o nazwie INVOICE-REF-<sequence>.json. Każdy z nich to jeden element odpowiedzi GET /invoices/{id}/events. Zawierają skrót faktury, ale nie jej treść.

{
  "occurred_at": "2026-10-02T17:17:55.857Z",
  "sequence": 1,
  "environment": "sandbox",
  "invoice_ref": "CAPTURE-JSON-1790961440",
  "document_sha256": "3b41395db498666777b74f9f5b9fae82871720304bc25bbb590e25b7b75ea1d4",
  "event_id": "evt_200c0def79ed702df81d702f",
  "country_route": "DE-XRECHNUNG",
  "invoice_number": "CAPTURE-JSON-1790961440",
  "status": "validated"
}

Zdarzenia, które istnieją w chwili przyjęcia pliku, są zapisywane od razu. Każde późniejsze zdarzenie jest zapisywane, gdy nadejdzie, aż faktura osiągnie stan końcowy (accepted, delivered, rejected, validation_failed, dead_letter lub cancelled) albo minie 30 dni.

Odrzucony plik trafia do failed/, a status/INVOICE-REF-error.json zawiera odpowiedź, której udzieliłoby API. Dla pliku, który nie jest fakturą, jest to poniższe 422. Należy poprawić dane i ponownie umieścić plik pod tą samą nazwą.

{
  "type": "https://eurinvoice.com/problems/validation-failed",
  "title": "The invoice did not pass the checks",
  "errors": [
    {
      "code": "EI-XML-TYPE",
      "fix_hint": "Send the invoice itself, in the format agreed for the route.",
      "who_fixes": "erp",
      "source": "XML-safety",
      "message": "The file is not an invoice in a format this route accepts. Please send the invoice in the agreed format."
    }
  ],
  "status": 422
}

Czego tu nie maKopiuj link do tej sekcji

• SFTP i magazynu obiektów.
• Sposobu na odczytanie z folderu identyfikatora inv_ przyjętej faktury. Pliki statusu zawierają invoice_ref i invoice_number.