Odesílání dokumentů

Fakturu nebo dobropis pošlete do Document API klíčem koncového uživatele. Redque dokument během požadavku zvaliduje, převede na Peppol BIS Billing 3.0 a doručí na přístupový bod příjemce.

1. Najděte příjemce

Před odesláním si ověřte, že je zákazník v síti Peppol a může faktury přijímat. Vyhledání účastníka převede identifikátory, které už znáte, na ID účastníků a každé ověří v síti:

curl -s "$DOCUMENT_API/v1/participant-lookup?vatNumber=CZ87654321" -H "X-Api-Key: $END_USER_KEY"

{
  "matches": [{
    "participantId": "iso6523-actorid-upis::9929:cz87654321",
    "schemeId": "CZ:VAT",
    "status": "Registered",
    "certain": true,
    "derivedFrom": "vatNumber",
    "canReceiveFromRedque": true,
    …
  }],
  "notes": []
}

• status: Registered — můžete mu posílat; NotRegistered — pod tímto ID v síti Peppol není; Unknown — vyhledání selhalo, zkuste to později.
• certain: false označuje ID odvozené pravidlem, které neplatí vždy. DIČ české právnické osoby je CZ + IČO, u OSVČ však obvykle ne, takže NotRegistered u IČO znamená „pod tímto ID ne". Požádejte zákazníka o jeho DIČ.
• canReceiveFromRedque: příjemce přijímá alespoň jeden typ dokumentu, který Redque odesílá.
• Registrované ID říká, že adresa je dosažitelná, ne že patří zákazníkovi, kterého máte na mysli.
• Vyhledávání je omezeno na 60 za minutu, sdílených všemi vašimi koncovými uživateli (nad limit 429). Odpovědi se ukládají do mezipaměti až na 15 minut.

2. Odešlete dokument

curl -s -X POST "$DOCUMENT_API/v1/documents?senderId=9929:CZ12345678&receiverId=9929:CZ87654321" \
  -H "X-Api-Key: $END_USER_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: 2026/FV-0042" \
  --data-binary @FV-2026-0042.isdoc

Formáty

Zda jde o fakturu, nebo dobropis, se čte z dokumentu samotného. Cokoli jiného vrací 415.

Odpovědi

Protokol validace

Validace používá oficiální pravidla OpenPeppol pro BIS Billing 3.0 včetně EN 16931 a pravidel jednotlivých zemí. Odmítnutý dokument nese úplný protokol:

{
  "transmissionId": "0d6c…",
  "state": "Rejected",
  "lastError": "PEPPOL-EN16931-R003: A buyer reference or purchase order reference MUST be provided.",
  "validationReport": {
    "vesid": "…",
    "success": false,
    "items": [{
      "severity": "error",
      "errorId": "PEPPOL-EN16931-R003",
      "location": "/:Invoice[1]",
      "text": "A buyer reference or purchase order reference MUST be provided.",
      "artefact": "…"
    }]
  },
  …
}

Položky se severity warning dokument nezastaví; i validní dokument může mít ve validationReport varování. Texty pravidel jsou anglicky, tak jak je vydává OpenPeppol.

Idempotence

Opakovaný požadavek se stejným Idempotency-Key, odesílatelem, příjemcem a tělem vrátí původní přenos a nic znovu neodešle, takže opakování po timeoutu nebo ztracené odpovědi je vždy bezpečné. Použití klíče pro jiný dokument vrací 422. Odvozujte klíč z dokumentu — například z čísla faktury —, aby opakování odkudkoli z vašeho systému použilo tentýž klíč.

3. Sledujte doručení

curl -s "$DOCUMENT_API/v1/documents/$TRANSMISSION_ID" -H "X-Api-Key: $END_USER_KEY"

• Odpověď obsahuje events, úplnou historii stavů, a po odeslání i as4MessageId.
• Když je přístupový bod příjemce dočasně nedostupný, Redque doručení automaticky opakuje v prodlužujících se intervalech (od 30 sekund po několik hodin), celkem zhruba osm hodin. attempt počítá pokusy. Teprve pak přenos skončí ve stavu Failed.
• Failed znamená, že se dokument k příjemci nedostal — například proto, že pro něj příjemce není registrován, nebo ho jeho přístupový bod odmítl. Důvod uvádí lastError. Odstraňte příčinu a odešlete znovu s novým Idempotency-Key.
• S odběrem webhooků dostanete událost transmission.status při Delivered, Failed a Rejected, takže se nemusíte dotazovat. Viz Webhooky.
• Delivered znamená, že dokument převzal přístupový bod příjemce. Neznamená to, že ho přijímající firma zpracovala nebo schválila.
• messageStatus je odpověď přístupového bodu příjemce (Peppol Message Level Status), obvykle do 10 minut po doručení: AP nebo AB — dokument dorazil k příjemci, RE — příjemce ho odmítl; důvody jsou v lines (každá chyba s kódem pravidla). Odpověď si stáhnete i jako dokument: GET /v1/documents/{id}/message-status/document. Její příchod oznámí webhook transmission.message_status.

Daňová hlášení (Slovensko)

U koncových uživatelů v zemi, která vyžaduje hlášení daňovému úřadu, Redque ke každé faktuře a dobropisu vytvoří a odešle hlášení. V současnosti se to týká slovenských koncových uživatelů (daňové datové dokumenty, lhůta 15 minut). Hlásí se tuzemské faktury (dodavatel i odběratel na Slovensku), na kterých má váš koncový uživatel uvedené DIČ pro DPH (IČ DPH); přeshraniční faktury se nehlásí.

• Průběh. taxReports u přenosu a GET /v1/documents/{id}/tax-reports ukazují každé hlášení: stav Pending, Sent, Accepted (daňový úřad potvrdil), Rejected (daňový úřad odmítl), NotRequired nebo Failed, a odpověď úřadu v authorityResponse. Každou změnu oznámí webhook tax_report.status.
• Archiv. Hlášení i odpověď úřadu si stáhnete přesně tak, jak byly odeslány a přijaty: GET /v1/tax-reports/{id}/document a GET /v1/tax-reports/{id}/message-status/document. Přehled všech hlášení koncového uživatele (filtry from, to, state, role, participantId): GET /v1/tax-reports.
• Opravy. K jedné faktuře patří řetězec hlášení: první (typeCode S), opravné (R) a zrušení (D). Když příjemce fakturu odmítne, Redque hlášení sám zruší. Opravená faktura se stejným číslem, datem a typem se nahlásí jako oprava (R) té původní. Zrušenou fakturu ohlásíte přes POST /v1/documents/{id}/tax-reports/disregard s tělem {"reason": "…"}.
• Odběratel mimo Peppol. Fakturu tuzemskému odběrateli, který Peppol nepoužívá, odešlete s receiverId=0245:9970300001. Redque ji zvaliduje a archivuje, nikomu ji nedoručí (stav Recorded) a odešle jen daňové hlášení. Fakturu odběrateli doručte jako dosud. Hlášení je pak jediným záznamem, uschovejte si ho.

Samofakturace

Peppol BIS Self-Billing 3.0 (fakturu vystavuje odběratel za dodavatele) se odesílá v UBL nebo kanonickém JSON s CustomizationID urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0 a typem 389 (dobropis 261). Odesílající účastník je odběratel a musí být pro samofakturaci registrován — není to výchozí schopnost, požádejte o ni při registraci účastníka. V ISDOC samofakturace vyjádřit nelze.

Poznámky k ISDOC

ISDOC a evropská norma EN 16931, kterou Peppol používá, se překrývají, ale ani jeden formát neobsahuje celý ten druhý. Redque převádí ISDOC na EN 16931 tak věrně, jak to formáty dovolují. Většina českých faktur projde bez problémů; níže uvedené body způsobují nejvíc odmítnutí.

• Reference odběratele. Peppol vyžaduje referenci odběratele nebo číslo objednávky (pravidlo PEPPOL-EN16931-R003). ISDOC referenci odběratele nemá, vyplňte proto OrderReferences/OrderReference/ExternalOrderID.
• Zálohové (proforma) faktury (DocumentType 4) Peppol nepovoluje a jsou odmítnuty.
• Součty musí sedět. Částky řádků musí dát dohromady TaxExclusiveAmount; zaokrouhlení patří do PayableRoundingAmount.
• Kategorie DPH se odvozují: neplátce DPH → O, tuzemský přenos daňové povinnosti → AE, sazba nad nulou → S, jinak E (osvobozeno). Nulovou sazbu nebo dodání do jiného členského státu přesně vyjádříte jen v UBL nebo JSON.
• Jednotky. Běžné české jednotky (ks, hod, kg, …) se převádějí na kódy UN/ECE; neznámé se stanou C62 (kus). Raději používejte kódy.
• Elektronické adresy dodavatele a odběratele se doplní ze senderId a receiverId; nemusíte je uvádět.
• Nepřenáší se: slevy a příplatky na úrovni dokladu (použijte záporné řádky), fakturační období, údaje o platbě kartou a inkasu, přílohy (balíčky .isdocx nejsou podporovány) a pole specifická pro ISDOC, například konstantní a specifický symbol. Variabilní symbol se stane platební referencí.

Pokud potřebujete plnou kontrolu nad obsahem podle EN 16931, posílejte UBL. ISDOC, který vytvoří Redque (viz Příjem), obsahuje celou fakturu, takže se převede zpět beze ztrát.