/ docs
ProduktZnalostiVývojári
Platforma Control
SOAP API: prijímanie faktúr

Získavanie faktúr cez legacy SOAP API: GetInboxDocuments, GetInboxDocument, správa stavov a sťahovanie PDF.

Cez legacy SOAP API získavate prijaté dokumenty prostredníctvom pollingu. Periodicky kontrolujete, či sú vo Vašom inboxe nové dokumenty, stiahnete ich a aktualizujete stav. Tento článok popisuje kompletný tok prijímania.

Dôležité: Toto je legacy SOAP API. Pre nové integrácie odporúčame REST API. REST API ponúka webhooky, takže nemusíte pollovať.

Tok prijímania v piatich krokoch
Krok 1: Získanie nových dokumentov

Zavolajte GetInboxDocuments s filtrom CreatedOn.From na získanie iba nových dokumentov. Po každom volaní si uložte najvyššiu hodnotu CreatedOn a použite ju ako východiskový bod pre ďalšiu kontrolu.

<GetInboxDocuments>
  <Filter>
    <CreatedOn>
      <From>2026-03-01T00:00:00</From>
    </CreatedOn>
  </Filter>
</GetInboxDocuments>
Krok 2: Filtrovanie podľa typu dokumentu

Odpoveď obsahuje metadáta všetkých dokumentov v inboxe. Filtrujte podľa Template/MasterId na výber iba správneho typu dokumentu. Pre štandardné faktúry použite MasterTemplateId:

GLDT9223370666504283001RA000000006DTP2000001

Vždy používajte MasterTemplateId a nie ID špecifickej verzie, pretože sa nemení pri aktualizáciách šablón.

Krok 3: Získanie kompletného dokumentu

Pre každý dokument si stiahnite kompletný payload cez GetInboxDocument pomocou ExternalId zo zoznamu metadát:

<GetInboxDocument>
  <ExternalId>het-external-id-uit-stap-1</ExternalId>
</GetInboxDocument>
Krok 4: Stiahnutie PDF

Použite GetDocumentPdf na získanie PDF verzie dokumentu. PDF sa vracia ako base64 zakódovaný reťazec.

Pozor: ak sa PDF ešte generuje, API vráti chybový kód ERRDMN8000003. V takom prípade počkajte niekoľko sekúnd a skúste to znova.

Krok 5: Aktualizácia stavu

Aktualizujte stav dokumentu cez SetInboxDocumentStatus. Je to dôležité pre tok spracovania a viditeľnosť stavu na platforme.

Dostupné stavové kódy

Inbox používa nasledujúce stavové kódy. Pri filtrovaní a aktualizácii vždy používajte kód (nie názov).

KódStavVysvetlenie05UloženéAutomaticky priradené pri prijatí10PrijatéŠtandardný počiatočný stav20OtvorenéPríjemca si dokument prezrel30StiahnutéAutomaticky nastavené pri stiahnutí35Na schválenieDokument je zaradený do schvaľovacieho workflow40SchválenéFaktúra bola odsúhlasená50ZamietnutéFaktúra bola zamietnutá60Pripravené na platbuDokument je pripravený na úhradu70ZaplatenéFaktúra bola uhradená
Filtre dokumentov

Pri získavaní dokumentov môžete použiť rôzne filtre na obmedzenie výsledkov:

FilterPoužitieExternalIdZískanie konkrétneho dokumentu podľa unikátneho IDCreatedOnRozsah dátumov pre nové dokumentyModifiedOnRozsah dátumov na detekciu zmien stavovSender / ReceiverFiltrovanie podľa názvu alebo routing IDTemplate/MasterIdFiltrovanie podľa typu dokumentuStatusFiltrovanie podľa stavového kódu
Outbox dokumenty

Okrem inbox dokumentov si môžete vyžiadať aj vlastné odoslané dokumenty. Použite na to GetOutboxDocuments a GetOutboxDocument. Fungovanie je porovnateľné s inbox endpointmi, ale pre dokumenty, ktoré ste sami odoslali.

Konceptové dokumenty

Pre dokumenty, ktoré ešte neboli odoslané (koncepty), použite GetDocuments a GetDocument. Tieto endpointy pracujú s DocumentId namiesto ExternalId. Koncepty majú vlastné stavové kódy:

KódStav10Vytvorené20Rozpracované40Schválené50Zamietnuté
Tipy pre polling

Interval: nepollujte častejšie ako raz za minútu. Pre väčšinu integrácií stačí raz za 5 až 15 minút.

Inkrementálne získavanie: vždy si uložte najvyššiu hodnotu CreatedOn a použite ju ako filter From pri ďalšom volaní. Tak predídete opakovanému získavaniu rovnakých dokumentov.

Detekcia zmien stavov: použite filter ModifiedOn, ak chcete detegovať, kedy sa stav existujúcich dokumentov zmenil, napríklad po schválení alebo zaplatení.

S REST API nemusíte pollovať: webhooky automaticky odošlú notifikáciu, akonáhle príde nový dokument. Pozrite si psb.econnect.eu pre moderný prístup.

Prechod na REST API

Súvisiace
PreviousSOAP odosielanie