SOAP wysyłanie | eConnect

Za pomocą endpointu SendDocument legacy SOAP API wysyła się faktury i inne dokumenty przez platformę eConnect. Platforma automatycznie określa najlepszą trasę: przez samą platformę eConnect, przez Peppol lub jako fallback przez e-mail.

Ważne: To jest legacy SOAP API. Dla nowych integracji zalecamy REST API.

Jak działa SendDocument

Przy wywołaniu SendDocument przekazuje się dokument źródłowy wraz z danymi nadawcy i odbiorcy. Platforma następnie wyszukuje odbiorcę w trzech krokach:

Platforma eConnect: czy odbiorca jest również użytkownikiem platformy? Wówczas dokument jest dostarczany bezpośrednio do inbox.
Peppol: czy odbiorca jest wyszukiwalny w sieci Peppol? Wówczas dokument jest routowany przez Peppol.
E-mail (fallback): jeśli żadna z opcji nie jest możliwa i podano adres e-mail, dokument jest wysyłany e-mailem.

Wymagane parametry

Parametr

Opis

Via/ReferenceId

Identyfikacja nadawcy (własne EConnectPartyId, numer XCNL)

To/ReferenceId

Identyfikacja odbiorcy (EConnectPartyId lub identyfikator Peppol jak 0106:numer-KvK)

To/EmailAddress

Adres e-mail odbiorcy (używany jako fallback, gdy routing przez platformę i Peppol nie jest możliwy)

Subject

Temat dokumentu

Payload

Sam dokument, jako UBL-XML. Uwaga: należy wysyłać XML bez prologu XML (<?xml ...?>)

TemplateId

ID szablonu wskazujące typ dokumentu

Przykład wywołania

<SendDocument>
  <Document>
    <Via>
      <ReferenceId>XCNL-123456</ReferenceId>
    </Via>
    <To>
      <ReferenceId>0106:12345678</ReferenceId>
      <EmailAddress>facturatie@voorbeeld.nl</EmailAddress>
    </To>
    <Subject>Factuur 2026-001</Subject>
    <Payload><!-- UBL-XML zonder prolog --></Payload>
    <TemplateId>GLDT9223370666504283001RA000000006DTP2000001</TemplateId>
  </Document>
</SendDocument>

TemplateId GLDT9223370666504283001RA000000006DTP2000001 to MasterTemplateId dla standardowej faktury. Zawsze należy używać MasterTemplateId (nie kodu wersji), ponieważ pozostaje stabilny między wersjami szablonu.

Odpowiedź i ExternalId

Po udanym wywołaniu API zwraca ExternalId. Jest to unikalny ID wysłanego dokumentu na platformie eConnect. Jeśli odpowiedź nie zawiera ExternalId, dokument nie został wysłany. W takim przypadku należy sprawdzić komunikat o błędzie w odpowiedzi.

ExternalId należy zawsze przechowywać: jest potrzebny do późniejszego zapytania o status dokumentu.

DeliveryMethod

API zwraca w odpowiedzi również DeliveryMethod, dzięki czemu wiadomo, jakim kanałem dokument został dostarczony:

Wartość

Znaczenie

ToInbox

Dostarczony do inbox odbiorcy na platformie eConnect

ToPeppol

Wysłany przez sieć Peppol

ToEmail

Wysłany e-mailem

OutboxOnly

Zapisany tylko we własnym outbox (niedostarczony)

None

Dostarczenie niemożliwe

Śledzenie statusu

Po wysłaniu można śledzić status dokumentu za pomocą dwóch endpointów:

Endpoint

Funkcja

GetOutboxDocuments

Pobranie listy wysłanych dokumentów. Filtrowanie po ModifiedOn, aby widzieć tylko ostatnio zmienione dokumenty.

GetOutboxDocument

Zapytanie o konkretny dokument na podstawie ExternalId.

GetOutboxDocumentStatus

Zapytanie tylko o status, bez pełnego dokumentu.

Wskazówki

UBL-XML bez prologu: Payload musi zawierać UBL-XML bez deklaracji <?xml version="1.0" encoding="UTF-8"?>. Jeśli dołączy się prolog, dokument może nie zostać prawidłowo przetworzony.

Używać MasterTemplateId: zawsze filtrować po Template/MasterId zamiast po specyficznym ID szablonu. MasterTemplateId nie zmienia się przy aktualizacjach wersji szablonu.

Obsługa błędów: sprawdzać odpowiedź pod kątem kodów błędów. Serie błędów 400 (walidacja) i 200 (funkcjonalny) są najczęstsze przy błędach wysyłki. Na stronie uwierzytelniania znajduje się pełny przegląd serii kodów błędów.

REST API oferuje przy wysyłaniu dodatkowe możliwości, takie jak webhooki do powiadomień o statusie i automatyczne ponowienia przy błędach. Dokumentacja na psb.econnect.eu prezentuje nowoczesne podejście.

Migruj do REST API

Powiązane