Dokumentace API

1. Jednoduché – Client Credentials

Nejlepší volba, pokud integrujete API přímo do své vlastní aplikace a jednáte jménem sebe. Neexistuje žádné přesměrování OAuth pro uživatele – svůj API klíč vyměníte za krátkodobý bearer token, který připojíte ke každé žádosti.

1. Otevřete Nastavení / API klíč v aplikaci a zkopírujte svůj client_id and client_secret.
2. Požádejte o token:

   POST /api/auth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=client_credentials
   &client_id=YOUR_CLIENT_ID
   &client_secret=YOUR_CLIENT_SECRET
   &scope=send_documents receive_documents

3. Použijte vrácený access_token jako Bearer token v následujících požadavcích:

   Authorization: Bearer <access_token>

4. Když vyprší platnost přístupového tokenu, použijte refresh_token ze stejné odpovědi k získání nového páru tokenů bez opětovného zadání přihlašovacích údajů:

   POST /api/auth/renew
   Content-Type: application/json
   
   { "refresh_token": "YOUR_REFRESH_TOKEN" }

   Případně jednoduše požádejte o zcela nový token opakováním kroku 2 s vaším client_id a client_secret.

2. Jednoduché OAuth – Authorization Code (vlastní aplikace)

Nejlepší volba, pokud integrujete do své vlastní aplikace, ale chcete použít standardní tok OAuth 2.0 Authorization Code. Uživatel (vy) bude přesměrován na obrazovku souhlasu a požádán o udělení požadovaných oprávnění. To je užitečné, pokud chcete, aby byl token vázán na interaktivní relaci.

1. Otevřete Nastavení / API klíč a zkopírujte svůj client_id and client_secret. Nastavte tam URI přesměrování.
2. Přesměrujte uživatele na autorizační endpoint:

   GET /oauth/authorize
     ?response_type=code
     &client_id=YOUR_CLIENT_ID
     &redirect_uri=https://your-app.example.com/callback
     &scope=send_documents receive_documents
     &state=RANDOM_STATE

3. Uživatel udělí přístup. Vyměňte vrácený code za token:

   POST /api/auth/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code
   &code=RETURNED_CODE
   &redirect_uri=https://your-app.example.com/callback
   &client_id=YOUR_CLIENT_ID
   &client_secret=YOUR_CLIENT_SECRET

3. Normální OAuth – Developer Application

Nejlepší volba, pokud vytváříte multi-tenantní aplikaci která bude používána vašimi vlastními zákazníky. Každý zákazník se přihlásí se svým vlastním účtem a explicitně udělí vaší aplikaci přístup ke svým datům. Jednáte jejich jménem pomocí tokenu, který vydají.

1. Přejděte na /developers/ a vytvořte novou Developer Application. Obdržíte dedikovaný client_id and client_secret pro tuto aplikaci.
2. Přesměrujte zákazníka na autorizační endpoint (stejný jako výše), ale s přihlašovacími údaji Developer Application a obory, které vaše aplikace potřebuje.

   GET /oauth/authorize
     ?response_type=code
     &client_id=YOUR_DEVELOPER_APP_CLIENT_ID
     &redirect_uri=https://your-app.example.com/callback
     &scope=send_documents
     &state=RANDOM_STATE

   Pokud již víte, kterou společnost chcete připojit, předejte jeden z následujících parametrů k předvýběru na obrazovce souhlasu – uživatel uvidí daného účastníka zvýrazněného/předvyplněného:

   Parametr(y)	Kdy použít	Příklad
   vatId	Znáte DIČ společnosti. Kontroluje se jako první; rn/countryCode jsou ignorovány, pokud je nalezena shoda.	&vatId=CZ12345678
   rn + countryCode	Znáte registrační číslo a zemi společnosti. Oba parametry jsou vyžadovány společně.	&rn=12345678&countryCode=CZ

   Porovnávání je case-insensitive a normalizuje mezery. Pokud žádný účastník v uživatelově účtu neodpovídá, obrazovka souhlasu zobrazí všechny dostupné účastníky bez předvýběru.

3. Zákazníkovi je zobrazena obrazovka souhlasu vázaná na jeho účet a udělí vaší aplikaci přístup.
4. Vyměňte autorizační kód za token. Vydaný token je omezen na zákazníkův účet a oprávnění, která schválil.

4. Affiliate ID – Lehký přístup pro vyhledávání

Zjednodušené přihlašovací údaje určené pro veřejné vyhledávání jen pro čtení (např. kontrola, zda je účastník registrován v síti Peppol). affiliateId je UUID, které se může objevit v URL a referrer hlavičkách – je považováno za semi-veřejné. Jeho hlavním účelem je ochrana proti anonymnímu zneužití a DoS útokům, nikoli striktní autentizace.

Předejte jako query parametr k vyhledávacím endpointům:

GET /api/lookup?affiliateId=YOUR_AFFILIATE_UUID&...

Oprávnění (Obory)

Při žádosti o token zadáte jeden nebo více oborů. K dispozici jsou následující obory:

Požadujte pouze obory, které vaše integrace skutečně potřebuje. Tokeny vydané prostřednictvím toku Developer Application jsou dále omezeny na obory, které zákazník schválil na obrazovce souhlasu.