/ docs
ProduktZnalostiVývojáři
Platforma Control
SOAP API: přijímání faktur

Získávání faktur přes legacy SOAP API: GetInboxDocuments, GetInboxDocument, správa stavů a stahování PDF.

Přes legacy SOAP API získáváte přijaté dokumenty prostřednictvím pollingu. Periodicky kontrolujete, zda jsou ve Vašem inboxu nové dokumenty, stáhnete je a aktualizujete stav. Tento článek popisuje kompletní tok přijímání.

Důležité: Toto je legacy SOAP API. Pro nové integrace doporučujeme REST API. REST API nabízí webhooky, takže nemusíte pollovat.

Tok přijímání v pěti krocích
Krok 1: Získání nových dokumentů

Zavolejte GetInboxDocuments s filtrem CreatedOn.From pro získání pouze nových dokumentů. Po každém volání si uložte nejvyšší hodnotu CreatedOn a použijte ji jako výchozí bod pro další kontrolu.

<GetInboxDocuments>
  <Filter>
    <CreatedOn>
      <From>2026-03-01T00:00:00</From>
    </CreatedOn>
  </Filter>
</GetInboxDocuments>
Krok 2: Filtrování podle typu dokumentu

Odpověď obsahuje metadata všech dokumentů v inboxu. Filtrujte podle Template/MasterId pro výběr pouze správného typu dokumentu. Pro standardní faktury použijte MasterTemplateId:

GLDT9223370666504283001RA000000006DTP2000001

Vždy používejte MasterTemplateId a ne ID specifické verze, protože se nemění při aktualizacích šablon.

Krok 3: Získání kompletního dokumentu

Pro každý dokument si stáhněte kompletní payload přes GetInboxDocument pomocí ExternalId ze seznamu metadat:

<GetInboxDocument>
  <ExternalId>het-external-id-uit-stap-1</ExternalId>
</GetInboxDocument>
Krok 4: Stažení PDF

Použijte GetDocumentPdf pro získání PDF verze dokumentu. PDF se vrací jako base64 zakódovaný řetězec.

Pozor: pokud se PDF ještě generuje, API vrátí chybový kód ERRDMN8000003. V takovém případě počkejte několik sekund a zkuste to znovu.

Krok 5: Aktualizace stavu

Aktualizujte stav dokumentu přes SetInboxDocumentStatus. Je to důležité pro tok zpracování a viditelnost stavu na platformě.

Dostupné stavové kódy

Inbox používá následující stavové kódy. Při filtrování a aktualizaci vždy používejte kód (ne název).

KódStavVysvětlení05UloženoAutomaticky přiřazeno při přijetí10PřijatoStandardní počáteční stav20OtevřenoPříjemce si dokument prohlédl30StaženoAutomaticky nastaveno při stažení35Ke schváleníDokument je zařazen do schvalovacího workflow40SchválenoFaktura byla odsouhlasena50ZamítnutoFaktura byla zamítnuta60Připraveno k platběDokument je připraven k úhradě70ZaplacenoFaktura byla uhrazena
Filtry dokumentů

Při získávání dokumentů můžete použít různé filtry pro omezení výsledků:

FiltrPoužitíExternalIdZískání konkrétního dokumentu podle unikátního IDCreatedOnRozsah dat pro nové dokumentyModifiedOnRozsah dat pro detekci změn stavůSender / ReceiverFiltrování podle názvu nebo routing IDTemplate/MasterIdFiltrování podle typu dokumentuStatusFiltrování podle stavového kódu
Outbox dokumenty

Kromě inbox dokumentů si můžete vyžádat i vlastní odeslané dokumenty. Použijte k tomu GetOutboxDocuments a GetOutboxDocument. Fungování je srovnatelné s inbox endpointy, ale pro dokumenty, které jste sami odeslali.

Konceptové dokumenty

Pro dokumenty, které ještě nebyly odeslány (koncepty), použijte GetDocuments a GetDocument. Tyto endpointy pracují s DocumentId místo ExternalId. Koncepty mají vlastní stavové kódy:

KódStav10Vytvořeno20Rozpracováno40Schváleno50Zamítnuto
Tipy pro polling

Interval: nepollujte častěji než jednou za minutu. Pro většinu integrací stačí jednou za 5 až 15 minut.

Inkrementální získávání: vždy si uložte nejvyšší hodnotu CreatedOn a použijte ji jako filtr From při dalším volání. Tak předejdete opakovanému získávání stejných dokumentů.

Detekce změn stavů: použijte filtr ModifiedOn, pokud chcete detekovat, kdy se stav existujících dokumentů změnil, například po schválení nebo zaplacení.

S REST API nemusíte pollovat: webhooky automaticky odešlou notifikaci, jakmile přijde nový dokument. Podívejte se na psb.econnect.eu pro moderní přístup.

Přechod na REST API

Související
PreviousSOAP odesílání