/ docs
ProduktWiedzaDeweloperzy
Platforma Control
Wysyłanie zamówienia przez API

Wysyłanie zamówienia UBL przez PSB API: endpoint, profile, idempotency i śledzenie statusu.

Za pomocą PSB API mogą Państwo wysyłać zamówienia zakupowe (purchase orders) do dostawców przez sieć Peppol. Proces działa podobnie jak wysyłanie faktur: wysyła się dokument UBL Order XML do API, a PSB zajmuje się walidacją, routingiem i dostarczeniem.

Endpoint
POST /api/v1/{partyId}/purchaseOrder/send

Żądanie zawiera dokument UBL Order XML jako body z content-type application/xml. {partyId} to identyfikator Peppol organizacji wysyłającej (nabywcy).

Profile zamówień

PSB obsługuje dwa profile zamówień Peppol:

ProfilProfileIDZastosowanieOrder Onlyurn:fdc:peppol.eu:poacc:bis:order_only:3Zamówienie jednokierunkowe bez responseAdvanced Orderingurn:fdc:peppol.eu:poacc:bis:advanced_ordering:3Pełny proces zamówienia z response, zmianami i anulowaniami

Przy Order Only nabywca wysyła zamówienie i proces się kończy. Przy Advanced Ordering dostawca może odpowiedzieć Order Response, a nabywca może później zmienić lub anulować zamówienie.

Wskazówka: profil Advanced Ordering należy stosować, gdy chce się, aby dostawca potwierdził zamówienie, lub gdy zamówienia mają być modyfikowalne w późniejszym czasie.

Podstawowy przepływ
  1. Upload: wysyłka dokumentu UBL Order XML do endpointu
  2. Walidacja: PSB waliduje dokument względem schematu XSD i reguł biznesowych
  3. Routing: PSB wyszukuje przez SML/SMP, jak dotrzeć do odbiorcy
  4. Dostarczenie: dokument jest dostarczany przez Peppol do dostawcy
  5. Aktualizacja statusu: otrzymanie webhooka OrderSent ze statusem dostarczenia
Idempotency

Należy używać headera X-EConnect-DocumentId, aby zapobiec podwójnemu przetworzeniu:

X-EConnect-DocumentId: 550e8400-e29b-41d4-a716-446655440000

Jeśli ten sam documentId zostanie wysłany ponownie, API zwraca 409 Conflict. Zawsze należy używać UUID/GUID, nigdy numeru zamówienia.

Obsługa błędów

W przypadku nieudanego dostarczenia PSB automatycznie stosuje ponowienia:

  • Maksymalnie 8 prób rozłożonych na ok. 35 godzin
  • Tylko przy błędach serwera 5xx (tymczasowe błędy po stronie odbiorcy)
  • Przy każdej próbie publikowane jest zdarzenie OrderSentRetry
  • W przypadku ostatecznego niepowodzenia otrzymują Państwo zdarzenie OrderSentError
BłądPrzyczynaRozwiązanieBłąd walidacji (4xx)Dokument nie jest zgodny ze standardem PeppolNależy sprawdzić dokument za pomocą Validate APIOdbiorca nie znalezionyIdentyfikator nie jest zarejestrowany w PeppolNależy sprawdzić za pomocą queryRecipientParty, czy dostawca może odbierać zamówienia409 ConflictDokument o tym documentId został już przetworzonyNie jest wymagana żadna akcja
Topiki webhook

Należy skonfigurować webhooki dla następujących topików, aby śledzić proces zamówienia:

TopikKiedyOrderSentZamówienie zostało pomyślnie dostarczoneOrderSentRetryDostarczenie jest ponawianeOrderSentErrorZamówienie nie mogło zostać dostarczoneOrderResponseReceivedDostawca odpowiedział na zamówienieOrderChangeReceivedOtrzymano zmianę zamówieniaOrderCancellationReceivedOtrzymano anulowanie zamówienia
Odpowiedź

Pomyślny upload zwraca 201 Created z identyfikatorem dokumentu w PSB. Tego identyfikatora należy używać do śledzenia zamówienia przez API lub webhooki.

Często zadawane pytania
Kiedy wybrać Order Only, a kiedy Advanced Ordering?

Order Only (urn:fdc:peppol.eu:poacc:bis:order_only:3) to zamówienie jednokierunkowe bez dalszego przepływu wiadomości. Advanced Ordering (urn:fdc:peppol.eu:poacc:bis:advanced_ordering:3) jest wymagane, gdy dostawca musi odpowiedzieć za pomocą Order Response lub gdy chcą Państwo później modyfikować lub anulować zamówienia. Należy wybrać Advanced, jeśli potrzebny jest ten pełny proces.

Jak zapobiec podwójnemu przetwarzaniu przy wysyłaniu zamówienia?

Należy wysłać nagłówek X-EConnect-DocumentId z unikalnym UUID lub GUID. Jeśli ponownie użyją Państwo tego samego documentId, API odpowie 409 Conflict. Nie należy używać numeru zamówienia jako klucza idempotencji, ponieważ nie jest on przeznaczony do tego mechanizmu.

Co się dzieje przy tymczasowych błędach dostarczenia i jakie webhooki otrzymuję?

W przypadku błędów 5xx po stronie odbiorcy, PSB automatycznie ponawia próbę dostarczenia (maksymalnie 8 prób w ciągu około 35 godzin). Zobaczą Państwo OrderSentRetry przy każdej próbie oraz OrderSentError przy trwałym niepowodzeniu. W przypadku sukcesu otrzymają Państwo OrderSent.

Pełna specyfikacja API dostępna jest na psb.econnect.eu ze wszystkimi parametrami i przykładowymi payloadami.

Wypróbuj w API

Powiązane
PreviousOdbieranie self-billing
NextOdbieranie zamówienia