Koncoví uživatelé a účastníci

Napojení zákazníka obnáší tři volání Partner API: založit koncového uživatele, zaregistrovat jeho účastníka a vydat mu API klíč.

Země a jejich pravidla

Pravidla Peppol závisí na zemi, kde má koncový uživatel sídlo: jakými identifikátory smí být registrován a kde je zveřejněn. Obsluhované země a jejich pravidla vypíšete takto:

curl -s "$PARTNER_API/v1/jurisdictions" -H "X-Api-Key: $PARTNER_KEY"

Založení koncového uživatele

curl -s -X POST "$PARTNER_API/v1/end-users" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "name": "Dodavatel s.r.o.",
  "countryCode": "CZ",
  "legalForm": "Company",
  "ico": "12345678",
  "externalRef": "crm-4711",
  "street": "Vinohradská 123/45",
  "city": "Praha",
  "postCode": "12000"
}'

Odpověď je 201 s koncovým uživatelem a jeho endUserId. Další volání:

• GET /v1/end-users vypíše vaše koncové uživatele od nejstaršího.
• PUT /v1/end-users/{endUserId} nahradí name, externalRef a adresu. Pošlete vždy úplnou sadu: co vynecháte, bude vymazáno. countryCode, ico a legalForm změnit nelze; pokud je některé chybně, založte koncového uživatele znovu.
• GET /v1/end-users/{endUserId}/participants vypíše jeho účastníky včetně odregistrovaných.

Registrace účastníka

Účastník zpřístupní koncového uživatele v síti Peppol. Jeho ID je adresa, na kterou ostatní firmy posílají.

curl -s -X POST "$PARTNER_API/v1/participants" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "endUserId": "6f1b…",
  "participantId": "9929:CZ12345678",
  "ownershipConfirmed": true,
  "directoryOptIn": false
}'

{
  "participantId": "iso6523-actorid-upis::9929:cz12345678",
  "endUserId": "6f1b…",
  "state": "SmpRegistered",
  "capabilities": [ … ],
  "directoryOptIn": false,
  "ownershipConfirmedAt": "2026-10-14T09:12:31Z",
  "registeredAt": null,
  "updatedAt": "2026-10-14T09:12:31Z"
}

ID účastníka lze zadat jako 9929:CZ12345678 i v plném tvaru iso6523-actorid-upis::9929:CZ12345678; odpovědi používají plný tvar.

Vlastnictví identifikátoru je vaše odpovědnost

DIČ i IČO jsou veřejné, takže nikdo nemůže prokázat, že je ovládá, pouhým nahlédnutím do registru. Před registrací ověřte, že koncový uživatel je oprávněným držitelem identifikátoru, a pak pošlete ownershipConfirmed: true. Redque zaznamená, kdy a kterým API klíčem jste to potvrdili. Účastník zaregistrovaný pro nesprávnou firmu dostává faktury této firmy.

Stavy účastníka

Odesílat lze už ve stavu SmpRegistered. Aby účastníka našli všichni odesílatelé v síti, dotazujte se GET /v1/participants/{participantId}, dokud nebude ve stavu Live.

Slovensko: koncový uživatel si Redque volí sám

Na Slovensku smí poskytovatele zmocnit jen koncový uživatel. Přihlásí se na portál Finanční správy SR a zvolí si Redque jako svého poskytovatele doručovací služby. Finanční správa pak Redque pošle ověřovací token, který Redque uloží spolu s registrací do centrálního SMP.

• Zaregistrujete-li účastníka 0245:… dřív, než si koncový uživatel Redque zvolí, zůstane ve stavu Requested a nic nepřijímá. Jakmile token dorazí, pokračuje sám do SmpRegistered a Live.
• Zvolil-li si koncový uživatel Redque už předem, registrace rovnou pokračuje do SmpRegistered.

Sandbox centrální SMP nemá: slovenské účastníky zveřejňuje ve vlastním SMP hned, stejně jako české, a na volbu nečeká. Finanční správa do sandboxu nic neposílá; její oznámení o volbě lze přesto nasimulovat:

curl -s -X POST "$PARTNER_API/v1/sandbox/sk/provider-selections" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "dic": "2020123456"
}'

Chyby při registraci

• 404: neznámý koncový uživatel nebo koncový uživatel jiného partnera.
• 409: ID účastníka už je zaregistrováno. ID jsou jedinečná v celé síti Peppol, takže to platí i pro registrace u jiných poskytovatelů.
• 422: ownershipConfirmed není true, schéma není v zemi koncového uživatele povoleno nebo není podporován některý typ dokumentu. detail uvede příklad očekávaného formátu.

Co může účastník přijímat

Ve výchozím stavu je účastník registrován pro všechny typy dokumentů, které Redque zpracovává: fakturu a dobropis podle Peppol BIS Billing 3.0. Sadu změníte voláním PUT /v1/participants/{participantId}/capabilities, kterému pošlete úplný seznam:

curl -s -X PUT "$PARTNER_API/v1/participants/9929:CZ12345678/capabilities" -H "X-Api-Key: $PARTNER_KEY" \
  -H "Content-Type: application/json" -d '{
  "capabilities": [{
    "documentTypeId": "busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
    "processId": "cenbii-procid-ubl::urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
  }]
}'

Aby účastník mohl typ dokumentu odesílat, musí pro něj být také registrován: odebráním dobropisu koncový uživatel přijde o možnost dobropisy posílat.

Pozastavení, obnovení a odregistrace

Když koncový uživatel přechází k jinému poskytovateli, odregistrujte jeho účastníka, aby ho nový poskytovatel mohl zaregistrovat. Některé země stanoví lhůtu: na Slovensku 3 pracovní dny. Odregistrované ID lze později znovu zaregistrovat, čímž začne nová registrace.

Zápis do Peppol Directory

Peppol Directory umožňuje odesílatelům najít firmu podle názvu. Zápis je vypnutý, dokud o něj nepožádáte, a to při registraci (directoryOptIn: true) nebo později:

curl -s -X PUT "$PARTNER_API/v1/participants/9929:CZ12345678/directory" -H "X-Api-Key: $PARTNER_KEY" \
  -H "Content-Type: application/json" -d '{ "optIn": true }'

• Zápis obsahuje název koncového uživatele, zemi, adresu, IČO a datum registrace — nikdy vaše kontaktní údaje.
• Koncový uživatel musí mít vyplněno alespoň city (jinak 422).
• Změna názvu nebo adresy přes PUT /v1/end-users/{endUserId} zápis aktualizuje.
• Pozastavení a odregistrovaní účastníci jsou z Directory odstraněni automaticky.
• Účastníky zveřejněné v národním centrálním SMP, jako na Slovensku, zapisuje toto SMP; nastavení na ně nemá vliv.

Nakonec: vydejte klíč koncového uživatele

Nakonec vydejte koncovému uživateli API klíč, aby jeho software mohl používat Document API — viz Klíče koncových uživatelů.