/ docs
ProduktWiedzaDeweloperzy
Platforma Control
SOAP API: odbieranie faktur

Pobieranie faktur przez legacy SOAP API: GetInboxDocuments, GetInboxDocument, zarządzanie statusem i pobieranie PDF.

Za pomocą legacy SOAP API otrzymane dokumenty pobiera się przez polling. Okresowo sprawdza się, czy w inbox pojawiły się nowe dokumenty, pobiera się je i aktualizuje status. Ten artykuł opisuje pełny przebieg odbierania.

Ważne: To jest legacy SOAP API. Dla nowych integracji zalecamy REST API. REST API oferuje webhooki, dzięki czemu polling nie jest konieczny.

Przebieg odbierania w pięciu krokach
Krok 1: pobranie nowych dokumentów

Wywołanie GetInboxDocuments z filtrem CreatedOn.From, aby pobrać tylko nowe dokumenty. Po każdym wywołaniu należy zapisać najwyższą wartość CreatedOn i użyć jej jako punktu startowego dla kolejnego sprawdzenia.

<GetInboxDocuments>
  <Filter>
    <CreatedOn>
      <From>2026-03-01T00:00:00</From>
    </CreatedOn>
  </Filter>
</GetInboxDocuments>
Krok 2: filtrowanie po typie dokumentu

Odpowiedź zawiera metadane wszystkich dokumentów w inbox. Należy filtrować po Template/MasterId, aby wybrać tylko właściwy typ dokumentu. Dla standardowych faktur używa się MasterTemplateId:

GLDT9223370666504283001RA000000006DTP2000001

Zawsze używać MasterTemplateId, a nie ID specyficznego dla wersji, ponieważ nie zmienia się on przy aktualizacjach szablonu.

Krok 3: pobranie pełnego dokumentu

Dla każdego dokumentu pobrać pełny payload za pomocą GetInboxDocument, na podstawie ExternalId z listy metadanych:

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

Użyć GetDocumentPdf, aby pobrać wersję PDF dokumentu. PDF jest zwracany jako ciąg zakodowany w base64.

Uwaga: jeśli PDF jest jeszcze generowany, API zwraca kod błędu ERRDMN8000003. W takim przypadku należy odczekać kilka sekund i spróbować ponownie.

Krok 5: aktualizacja statusu

Aktualizacja statusu dokumentu za pomocą SetInboxDocumentStatus. Jest to ważne dla przepływu przetwarzania i widoczności statusu na platformie.

Dostępne kody statusu

Inbox wykorzystuje następujące kody statusu. Przy filtrowaniu i aktualizacji zawsze należy używać kodu (nie nazwy).

KodStatusUwagi05ZapisanyAutomatycznie przypisany przy odbiorze10OtrzymanyDomyślny status początkowy20OtwartyOdbiorca obejrzał dokument30PobranyAutomatycznie ustawiany przy pobieraniu35Do zatwierdzeniaDokument umieszczony w przepływie zatwierdzania40ZatwierdzonyFaktura została zaakceptowana50OdrzuconyFaktura została odrzucona60Skierowany do zapłatyDokument jest gotowy do płatności70ZapłaconyFaktura została uregulowana
Filtry dokumentów

Przy pobieraniu dokumentów można używać różnych filtrów do ograniczenia wyników:

FiltrZastosowanieExternalIdPobranie konkretnego dokumentu po unikalnym IDCreatedOnZakres dat dla nowych dokumentówModifiedOnZakres dat do wykrywania zmian statusuSender / ReceiverFiltrowanie po nazwie lub ID routingowymTemplate/MasterIdFiltrowanie po typie dokumentuStatusFiltrowanie po kodzie statusu
Dokumenty outbox

Oprócz dokumentów inbox można również pobierać własne wysłane dokumenty. Służą do tego GetOutboxDocuments i GetOutboxDocument. Działanie jest analogiczne do endpointów inbox, ale dla dokumentów wysłanych.

Dokumenty robocze

Dla dokumentów jeszcze niewysłanych (wersje robocze) używa się GetDocuments i GetDocument. Te endpointy pracują z DocumentId zamiast ExternalId. Wersje robocze mają własne kody statusu:

KodStatus10Utworzony20W przygotowaniu40Zatwierdzony50Odrzucony
Wskazówki dotyczące pollingu

Interwał: nie należy pollować częściej niż raz na minutę. Dla większości integracji raz na 5 do 15 minut jest wystarczające.

Pobieranie przyrostowe: zawsze zapisywać najwyższą wartość CreatedOn i używać jej jako filtra From przy następnym wywołaniu. Zapobiega to wielokrotnemu pobieraniu tych samych dokumentów.

Wykrywanie zmian statusu: filtr ModifiedOn służy do wykrywania, kiedy status istniejących dokumentów został zmieniony, na przykład po zatwierdzeniu lub płatności.

Z REST API polling nie jest potrzebny: webhooki automatycznie wysyłają powiadomienie, gdy wpływa nowy dokument. Dokumentacja na psb.econnect.eu prezentuje nowoczesne podejście.

Przejdź na REST API

Powiązane
PreviousSOAP wysyłanie