PeppolDokumentace pro partnery Swagger UI: sandbox · produkce

Začínáme

Tento návod vás provede od partnerského klíče až k faktuře ISDOC, kterou jeden koncový uživatel odešle a druhý přijme — celé v prostředí Sandbox.

Sandbox je samostatná uzavřená síť Peppol, takže i příjemce musí být účastníkem v sandboxu. Založíte proto dva koncové uživatele: dodavatele, který fakturu odešle, a odběratele, který ji přijme.

Příklady používají curl v POSIX shellu. Každé volání můžete udělat i ve Swagger UI: Partner API a Document API v sandboxu. Klikněte na Authorize a vložte klíč. V produkci stejně fungují Partner API a Document API.

  1. Připravte si shell

    Při založení vašeho partnerského účtu vám Redque předá partnerský klíč pro sandbox (rqp_sandbox_…). Pro získání přístupu do sandbox prostředí nás kontaktujte na adrese info@redque.cz.

    export PARTNER_API=https://partnerapi-sandbox.peppol.redque.com
export DOCUMENT_API=https://api-sandbox.peppol.redque.com
export PARTNER_KEY=rqp_sandbox_…

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

    Odpověď vypíše vaše dva sloty klíčů. Pokud dostanete 401, pole detail řekne proč — například že klíč patří jinému prostředí.

  2. Zjistěte, které země jsou obsluhovány

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

    U každé země je uvedeno, jaká schémata identifikátorů účastníků smí její koncoví uživatelé používat. Tento návod používá Česko, kde se koncový uživatel adresuje svým DIČ: 9929:CZ a 8–10 číslic.

  3. Založte dva koncové 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", "ico": "12345678",
  "legalForm": "Company", "externalRef": "supplier-1",
  "street": "Vinohradská 123/45", "city": "Praha", "postCode": "12000"
}'

curl -s -X POST "$PARTNER_API/v1/end-users" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "name": "Odběratel a.s.", "countryCode": "CZ", "ico": "87654321",
  "legalForm": "Company", "externalRef": "customer-1"
}'

    Každá odpověď obsahuje endUserId. Obě si poznamenejte:

    export SUPPLIER_ID=…   # endUserId firmy Dodavatel s.r.o.
export CUSTOMER_ID=…   # endUserId firmy Odběratel a.s.

  4. Zaregistrujte každému účastníka

    Účastník je adresa koncového uživatele v síti Peppol. Hodnotou ownershipConfirmed: true potvrzujete, že jste ověřili, že identifikátor koncovému uživateli skutečně patří — viz vlastnictví identifikátoru.

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

curl -s -X POST "$PARTNER_API/v1/participants" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" -d '{
  "endUserId": "'"$CUSTOMER_ID"'", "participantId": "9929:CZ87654321", "ownershipConfirmed": true
}'

    Stav začíná jako SmpRegistered a po zveřejnění, obvykle během několika sekund, se změní na Live:

    curl -s "$PARTNER_API/v1/participants/9929:CZ12345678" -H "X-Api-Key: $PARTNER_KEY"

  5. Vydejte každému klíč koncového uživatele

    Document API se volá vlastním klíčem koncového uživatele, který vydáváte vy. Vrátí se pouze v této odpovědi.

    curl -s -X POST "$PARTNER_API/v1/end-users/$SUPPLIER_ID/api-keys/1/rotate" -H "X-Api-Key: $PARTNER_KEY"
curl -s -X POST "$PARTNER_API/v1/end-users/$CUSTOMER_ID/api-keys/1/rotate" -H "X-Api-Key: $PARTNER_KEY"

export SUPPLIER_KEY=rqe_sandbox_…
export CUSTOMER_KEY=rqe_sandbox_…

  6. Přihlaste se k webhookům (volitelné)

    Zadejte svůj HTTPS endpoint. Odpověď obsahuje podpisové secret, které se zobrazí jen jednou. Pro rychlý pohled bez psaní kódu poslouží v sandboxu i nástroj na zachytávání požadavků, například webhook.site.

    curl -s -X POST "$PARTNER_API/v1/webhooks" -H "X-Api-Key: $PARTNER_KEY" -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/peppol/webhook" }'

  7. Odešlete fakturu ISDOC

    Pošlete soubor ISDOC tak, jak je, jako dodavatel. senderId je účastník dodavatele a receiverId účastník odběratele. Hlavička Idempotency-Key zajistí, že opakování požadavku je bezpečné.

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

    202 Accepted znamená, že faktura prošla validací Peppol a je na cestě; tělo odpovědi obsahuje její transmissionId. 422 se stavem "state": "Rejected" znamená, že validací neprošla, a validationReport uvádí, která pravidla porušila.

  8. Sledujte doručení

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

    Stav postupuje Queued → Validating → Sending → Delivered. Po doručení dostane váš webhook událost transmission.status.

  9. Přijměte ji jako odběratel

    Váš webhook dostane událost document.received. Bez webhooku se podívejte do schránky odběratele:

    curl -s "$DOCUMENT_API/v1/inbox/9929:CZ87654321" -H "X-Api-Key: $CUSTOMER_KEY"

curl -s "$DOCUMENT_API/v1/inbox/9929:CZ87654321/$TRANSMISSION_ID/document?format=Isdoc" \
  -H "X-Api-Key: $CUSTOMER_KEY" -o received.isdoc

curl -s -X POST "$DOCUMENT_API/v1/inbox/9929:CZ87654321/$TRANSMISSION_ID/ack" -H "X-Api-Key: $CUSTOMER_KEY"

    Přijatý přenos má vlastní transmissionId, jiné než u odesílatele; vezměte ho ze schránky nebo z webhooku.

Co dál

PředchozíPřehled DalšíSandbox a produkce