Validate API | eConnect

Za pomocą Validate API mogą Państwo zwalidować dokument XML bez jego zapisywania ani wysyłania przez PSB. Dzięki temu jest idealna jako pre-flight check przed faktycznym wysłaniem dokumentu lub do testowania dokumentów podczas tworzenia integracji.

Endpoint

POST /api/v1/generic/validate

Dokument XML wysyła się jako body z content-type application/xml. PSB analizuje dokument i zwraca wynik walidacji.

Inteligentne wykrywanie dokumentu

Validate API automatycznie rozpoznaje, jaki format dokumentu został dostarczony, na podstawie zawartości XML. Nie trzeba określać, czy jest to faktura NLCIUS, faktura Peppol BIS Billing V3, zamówienie UBL czy inny format. API wykrywa to samodzielnie i stosuje odpowiednie reguły walidacji.

Działa to dla wszystkich typów dokumentów obsługiwanych przez PSB: faktur, not kredytowych, zamówień, order response i innych.

Wynik walidacji

Odpowiedź zawiera boolean isValid i listę assertions:

{
  "isValid": false,
  "assertions": [
    {
      "artifact": "schema",
      "flag": "error",
      "text": "Element 'cbc:InvoiceTypeCode' is missing."
    },
    {
      "artifact": "business-rules",
      "flag": "warning",
      "text": "BR-NL-10: TaxTotal should contain at least one TaxSubtotal."
    }
  ]
}

Każda asercja ma flag z jedną z następujących wartości:

Flag

Znaczenie

success

Reguła walidacji przeszła pomyślnie

warning

Punkt uwagi, ale nie błąd blokujący

error

Błąd walidacji, dokument nie zostanie zaakceptowany

Walidacja sprawdza zarówno schemat XSD (strukturę), jak i reguły biznesowe (reguły treści, takie jak wymagane pola i zakresy wartości).

Podwójna walidacja

PSB domyślnie waliduje względem najnowszej wersji artefaktów walidacji. Jeśli dokument nie jest prawidłowy względem najnowszej wersji, ale jest prawidłowy względem poprzedniej wersji wciąż akceptowanej w sieci, zwracane są oba wyniki. Dzięki temu wiedzą Państwo, czy dokument może jeszcze zostać wysłany teraz i czy potrzebna jest aktualizacja dla przyszłej kompatybilności.

Niestandardowe reguły walidacji (optionId)

Dla specyficznych potrzeb walidacji można dodać optionId jako parametr zapytania:

POST /api/v1/generic/validate?optionId=jouw-optie-id

Aktywuje to predefiniowany zestaw reguł walidacji, np. wymagania specyficzne dla klienta lub standardy branżowe. Dostępne opcje można sprawdzić przez:

GET /api/v1/generic/validate/options

Ustawienia języka

Domyślnie asercje są w języku angielskim. Chcą Państwo otrzymywać komunikaty walidacji po holendersku? Należy wysłać header X-EConnect-Language:

X-EConnect-Language: nl

Obsługiwane języki to m.in. nl (holenderski) i en (angielski).

Kiedy stosować?

Validate API jest szczególnie przydatna w następujących scenariuszach:

Podczas rozwoju: testowanie dokumentów przed wywołaniem endpointu wysyłki
Pre-flight check: walidacja dokumentów we własnej aplikacji przed wysłaniem do PSB, aby móc zapewnić bezpośrednią informację zwrotną użytkownikom
Walidacja wsadowa: sprawdzanie dużego zestawu dokumentów pod kątem błędów przed wysyłką

Techniczne: Validate API nie zapisuje dokumentu w PSB. Dokument jest walidowany, a wynik zwracany natychmiast. Webhooki nie są wyzwalane i nie są naliczane opłaty.

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

Zwaliduj dokument

Powiązane