# Predbežná validácia

URL: https://postman.slovakodata.com/developers/predbezna-validacia/
Aktualizované: 2026-09-29

Overte faktúru a dosiahnuteľnosť príjemcu ešte pred odoslaním.

Pred odoslaním dokumentu si ho môžete dať overiť. Endpoint prejde **rovnakým
päťúrovňovým validačným reťazcom**, aký beží po odoslaní — takže čo prejde tu, prejde aj
tam. Nevytvára faktúru, nič neukladá a **nespotrebúva kredit**.

## Overenie dokumentu

```http
POST /api/v1/documents/validate
X-Api-Key: …
Content-Type: application/json
Accept-Language: sk
```

```json
{
  "xml_content": "…",
  "receiver_peppol_id": "0245:2120984085"
}
```

Povinné je jediné pole — `xml_content`. **Prítomnosť `receiver_peppol_id` zapína aj
overenie príjemcu** cez Peppol SMP; bez neho sa overuje len samotný dokument.

Odpoveď má **vždy stav 200**, aj keď je dokument neplatný. Neplatná faktúra nie je chyba
volania — verdikt je súčasťou dát.

```json
{
  "valid": false,
  "network_ready": false,
  "overall_severity": "FATAL",
  "validation_levels": {
    "L1_xml": "OK", "L2_xsd": "OK", "L3_en16931": "OK",
    "L4_peppol": "FATAL", "L5_sk": "WARNING"
  },
  "errors": [{
    "rule_id": "PEPPOL-EN16931-R001",
    "rule_set": "PEPPOL",
    "level": 4,
    "severity": "FATAL",
    "raw_message": "Business process MUST be provided.",
    "raw_location": "/Invoice[1]/cbc:ProfileID",
    "title": "Chýba identifikátor obchodného procesu",
    "explanation": "Peppol vyžaduje, aby faktúra deklarovala…",
    "fix": "Doplňte element cbc:ProfileID s hodnotou…",
    "location": "Hlavička faktúry → Profil",
    "localized": true
  }],
  "warnings": [],
  "truncated": false,
  "total_findings": 1,
  "document": { "document_type": "INVOICE", "invoice_number": "FA-2026-001", "…": "…" },
  "receiver": {
    "peppol_id": "0245:2120984085",
    "registered": true,
    "supports_document_type": false,
    "reason": "NOT_SERVICED",
    "checked_at": "2026-08-05T10:00:00Z"
  },
  "duration_ms": 1840
}
```

## Nálezy sú lokalizované, originál zostáva

`title`, `explanation`, `fix` a `location` sa prekladajú podľa hlavičky `Accept-Language`
(podporujeme `sk` a `en`; bez hlavičky sa použije `en`). Použitý jazyk vraciame
v `Content-Language`.

Rovnaký tvar nálezu vracia aj `GET /api/v1/invoices/{id}/validation` — viď [Validácia](/developers/validacia/).

`raw_message` a `raw_location` sa **neprekladajú nikdy** — sú to originálny text
Schematronu a XPath. Práve ich potrebujete, keď riešite problém s dodávateľom svojho ERP.

Ak pravidlo v katalógu ešte nemáme, `localized` je `false` a `title` obsahuje originálnu
anglickú správu. Nález sa nikdy nestratí.

## Päť úrovní validácie

| Úroveň | Čo overuje |
|---|---|
| `L1_xml` | správnosť XML |
| `L2_xsd` | schéma UBL 2.1 |
| `L3_en16931` | pravidlá EN 16931 |
| `L4_peppol` | pravidlá Peppol BIS 3.0 |
| `L5_sk` | slovenské národné pravidlá |

Hodnoty sú `OK`, `WARNING`, `FATAL` alebo `SKIPPED`. `SKIPPED` znamená, že úroveň
nebežala — typicky preto, že skončila skôr: zlyhanie na `L1` zastaví všetko ostatné.

Pravidlá EN 16931 a Peppol BIS bežia v jednom reťazci, takže sa nikdy nespúšťajú dvakrát;
každá úroveň napriek tomu hlási vlastný výsledok.

Úroveň `L5_sk` môže navyše vrátiť `ERROR` — slovenskú sadu pravidiel sa nepodarilo spustiť.
Dokument to nezhodí, ale medzi upozorneniami nájdete nález s `rule_id` `SK_ENGINE`, aby bolo
zrejmé, že slovenské pravidlá overené neboli.

## Overenie príjemcu

`network_ready` je `true`, len keď je dokument platný **a** príjemca je v sieti **a**
podporuje daný typ dokumentu. Obe polia — `network_ready` aj `receiver` — sú v odpovedi
**len vtedy, keď ste o overenie požiadali**.

Pole `reason` rozlišuje tri situácie, ktoré sa nesmú zamieňať:

| `reason` | Význam | Čo s tým |
|---|---|---|
| `NOT_REGISTERED` | príjemca nie je v Peppol sieti | overte jeho Peppol ID |
| `NOT_SERVICED` | príjemca je v sieti, ale nepodporuje tento typ dokumentu | overte typ dokumentu |
| `LOOKUP_UNAVAILABLE` | **verdikt sa nezistil** — SMP neodpovedalo | skúste o chvíľu znova |

Pri `LOOKUP_UNAVAILABLE` sú `registered` aj `supports_document_type` `null`, nie `false` —
neoverili sme, že príjemca neexistuje, len sme sa to nedozvedeli.

## Overenie príjemcu bez dokumentu

Ak potrebujete len zistiť, či je zákazník dosiahnuteľný, dokument posielať nemusíte:

```http
GET /api/v1/participants/0245:2120984085/reachability?document_type=INVOICE
```

Odpoveď má rovnaký tvar ako blok `receiver` vyššie.

## Limity

- dokument najviac **10 MB**, rovnako ako pri odoslaní; väčší vráti **413**
- najviac **500 nálezov** v odpovedi; pri skrátení je `truncated: true` a `total_findings`
  nesie skutočný počet
- ak je validačná služba dočasne nedostupná, vrátime **503** a hlavičku `Retry-After`;
  odosielanie faktúr to neovplyvňuje
- počet validácií a dopytov na dostupnosť za minútu závisí od balíka — od **10 validácií
  a 30 dopytov** pri MINI po **300 validácií a 120 dopytov** pri ENTERPRISE
  ([Limity a kvóty](/developers/limity/)). Obe cesty majú vlastné počítadlo — validovanie
  v cykle vám nevyčerpá kvótu na odosielanie faktúr. Váš limit a zostatok nesú hlavičky
  `RateLimit-Policy` a `RateLimit`, pri prekročení príde **429** s `Retry-After`