API Dokumentácia | VerifyEU Developer Hub

Pokrytie API

Kontroloval som to aj voči dodaným referenciám: nechávame si praktické onboarding prvky, ale pridávame širší workflow okolo validácie, lookupu, dokumentov a opráv.

Validácia XML

Batch aj single-file requesty pre UBL Invoice/CreditNote, SBDH obálky, EN 16931, Peppol profil a slovenskú aplikačnú vrstvu s issues, root causes, summary a remediation odkazmi.

POST /validateroot causesSBDHSK CIUS

Preview vystavenia

/api/invoice-issue-preview prijme draft faktúry, vygeneruje UBL XML, spustí validáciu a vráti readiness checklist bez uloženia alebo odoslania dokumentu.

POST /invoice-issue-previewdraft → XMLreadiness

Dôkazový balík

/api/validation-evidence vytvorí validačný dôkaz s XML SHA-256, root causes, markdown reportom a developer summary. Pri ?format=zip vráti ZIP bez serverového uloženia XML.

POST /validation-evidenceSHA-256ZIP

Čitateľný náhľad XML

/api/invoice-render prijme UBL, SBDH alebo CII/ZUGFeRD XML a vráti summary + print-ready HTML. CII je preview-only; validácia pravidiel zatiaľ zostáva pre UBL/SBDH.

POST /invoice-renderCII previewprint PDF

Delivery workflow

Dokumentový lifecycle drží status, event timeline, artefakty na stiahnutie, idempotency kľúč a prípravu send kroku cez pripojeného certifikovaného partnera po validácii.

POST /documents/send/acknowledgements

Lookup a opravy

Peppol participant lookup, batch radar, VIES kontrola, error catalog a remediation API pre vysvetlenie chýb bez hľadania v normách.

/peppol-radar/error-catalog/remediation

AI agenti a MCP

JSON-RPC endpoint pre asistentov, ktorí potrebujú validovať XML, vyhľadať pravidlo alebo prehľadať SK/EN katalóg bez parsovania webu.

POST /mcptools/listtools/call

Quickstart

Pre batch používajte JSON payload. Pre jednu faktúru môžete poslať aj raw XML priamo na /api/validate-file alebo /api/validate s Content-Type: application/xml. Podporované sú UBL Invoice, UBL CreditNote a SBDH obálka s vnútorným UBL dokumentom; CII/ZUGFeRD sa vráti ako explicitný CII-UNSUPPORTED issue.

1. Načítajte XMLObsah súboru pošlite ako string v poli content, alebo ako raw application/xml body.

2. Zavolajte validáciuPre viac faktúr použite files, pre jednu faktúru filename + content.

3. Opravte podľa rule_idKaždý issue má vrstvu, závažnosť, XPath/context, SK fix a odkaz na error catalog alebo remediation flow.

# Batch validácia XML faktúr
curl -X POST https://efakturacentrum.sk/api/validate \
  -H "Content-Type: application/json" \
  -d '{
    "files": [
      {
        "filename": "faktura.xml",
        "content": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>"
      }
    ]
  }'

# Jedna faktúra môže ísť aj priamo ako raw XML
curl -X POST https://efakturacentrum.sk/api/validate-file \
  -H "Content-Type: application/xml" \
  --data-binary "@faktura.xml"

# Draft faktúry → UBL XML + validácia + readiness checklist
curl -X POST https://verifyeu.com/api/invoice-issue-preview \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": {
      "invoiceNumber": "FA-2026-001",
      "issueDate": "2026-06-23",
      "dueDate": "2026-07-07",
      "sellerName": "Dodavatel s.r.o.",
      "sellerDic": "2020123456",
      "sellerIban": "SK8911000000002600123456",
      "buyerName": "Odberatel a.s.",
      "buyerDic": "2021654321",
      "lines": [{ "description": "Sluzba", "quantity": "1", "unit": "EA", "unitPrice": "100", "vatRate": "23" }]
    }
  }'

# Dôkazový balík: validácia + hash + reporty v ZIP
curl -X POST https://verifyeu.com/api/validation-evidence?format=zip \
  -H "Content-Type: application/json" \
  -H "Accept: application/zip" \
  -d '{
    "filename": "faktura.xml",
    "content": "<Invoice xmlns=\"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2\">...</Invoice>",
    "include_xml": false
  }' \
  -o "verifyeu-evidence.zip"

# Print-ready HTML náhľad z XML
curl -X POST https://verifyeu.com/api/invoice-render?format=html \
  -H "Content-Type: application/xml" \
  --data-binary "@faktura.xml" \
  -o "faktura-preview.html"

import { readFile } from "node:fs/promises";

const xml = await readFile("faktura.xml", "utf8");
const response = await fetch("https://efakturacentrum.sk/api/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    files: [{ filename: "faktura.xml", content: xml }]
  })
});

const result = await response.json();
console.log(result.valid, result.invalid, result.results[0].issues);

import json
from urllib.request import Request, urlopen

with open("faktura.xml", "r", encoding="utf-8") as f:
    xml = f.read()

payload = json.dumps({
    "files": [{"filename": "faktura.xml", "content": xml}]
}).encode("utf-8")

req = Request(
    "https://efakturacentrum.sk/api/validate",
    data=payload,
    headers={"Content-Type": "application/json"},
    method="POST",
)

print(json.loads(urlopen(req, timeout=30).read()))

{
  "total": 1,
  "valid": 0,
  "invalid": 1,
  "results": [
    {
      "filename": "faktura.xml",
      "valid": false,
      "fatal_count": 1,
      "warning_count": 1,
      "summary": { "invoice_id": "FV-2026-0001", "currency": "EUR", "detected_profile": "Peppol BIS Billing 3.0" },
      "issues": [
        {
          "level": "fatal",
          "layer": "EN16931",
          "rule_id": "BR-CO-10",
          "message": "Súčet riadkov nesedí s LegalMonetaryTotal.",
          "location": "/Invoice/cac:LegalMonetaryTotal/cbc:LineExtensionAmount",
          "ruleUrl": "/chyby/BR-CO-10/",
          "fix": { "sk": "Sčítajte LineExtensionAmount..." }
        }
      ]
    }
  ]
}

MCP pre AI asistentov

Endpoint /api/mcp používa JSON-RPC 2.0. Je určený pre agentov, ktorí chcú volať validačné nástroje priamo namiesto čítania HTML stránok. Samostatný setup návod je na /mcp/.

Tool discoveryZavolajte tools/list a klient zistí dostupné nástroje.

Validácia XMLvalidate_peppol_xml vráti issues obohatené o SK rule linky.

Katalóg pravidielget_peppol_rule a search_peppol_rules vracajú SK+EN vysvetlenia, XPath a fix.

curl -X POST https://verifyeu.com/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_peppol_rule",
      "arguments": { "ruleId": "BR-CO-10" }
    }
  }'

Otvoriť MCP setup guide Discovery JSON

Auth, limity a bezpečnosť

Voľný validator pomáha pri testovaní. Produkčná integrácia má mať oddelené workspace oprávnenia, audit a idempotency.

Verejný režim

Endpointy validácie a PDF bridge môžu bežať bez API kľúča, ale sú metered cez verejný denný soft limit. Pri limite API vráti public_soft_limit_reached s hodnotami used a limit.

Workspace režim

Pre dôverné faktúry používajte workspace API kľúč, role developer alebo admin, a pri vytváraní dokumentu posielajte Idempotency-Key, aby retry nevytvoril duplicitu.

Živé endpointy

Zoznam nižšie sa skladá z /api/openapi.json. Ak backend pribudne alebo sa zmení, táto časť to ukáže bez ručnej úpravy stránky.

...OpenAPI paths

...sandbox endpoints

...artifact registry

...public daily limit

/api/openapi.json /api/mcp /api/error-catalog /api/remediation /api/sandbox-status /api/billing-status