https://api.eurodebt.eu/api/{version}

1. Získejte klíč API z ovládacího panelu Eurodebt. Přejděte do sekce Správa > Nastavení > Klíče API a klikněte na tlačítko „Vytvořit klíč API“.
2. Zahrňte klíč API do všech požadavků prostřednictvím x-api-key hlavička
3. Odesílejte žádosti o ověření a získejte výsledky prostřednictvím webhooků nebo dotazování

Všechny požadavky API vyžadují ověření pomocí klíče API. Uveďte svůj klíč API v x-api-key záhlaví.

x-api-key: your-api-key-here

Klíče API mají oprávnění, která řídí přístup k různým koncovým bodům:

• čístPřístup k načtení žádostí o ověření, zpráv a údajů o využití
• zapsatMožnost odeslat nové žádosti o ověření

API je omezeno rychlostí 100 požadavků za minutu za klíč API. V případě omezení rychlosti obdržíte 429 Too Many Requests odpověď.

Záhlaví limitu rychlosti jsou zahrnuta ve všech odpovědích:

• RateLimit-LimitMaximální počet požadavků na okno
• RateLimit-RemainingZbývající požadavky v aktuálním okně
• RateLimit-ResetČas, kdy se limit rychlosti resetuje (časové razítko Unixu)

Webhooky vám umožňují dostávat upozornění v reálném čase, když na vašem účtu dojde k událostem. Místo dotazování API na aktualizace zadáte URL adresu a Eurodebt na ni odešle požadavky HTTP POST, když dojde k relevantním událostem.

Jak fungují webhooky

1. Konfigurace: Poskytněte a webhookUrl při odesílání požadavku (např. požadavek na ověření, generování PDF)
2. Událost nastanePo dokončení nebo neúspěchu operace odešle Eurodebt požadavek POST na vaši URL adresu.
3. ProcesVáš server přijme datovou část, ověří podpis a zpracuje data.
4. PotvrditDo 10 sekund vraťte stavový kód 2xx pro potvrzení přijetí

Zabezpečení webhooku (ověřování podpisu)

Všechny požadavky na webhook jsou podepsány pomocí HMAC-SHA256 s tajným kódem webhooku vašeho API klíče. Podpis je součástí X-Eurodebt-Signature záhlaví.

Formát záhlaví: sha256=<hex-encoded-signature>

Node.js / Express:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-eurodebt-signature'];
  
  const expected = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  res.status(200).send('OK');
});

Python / Baňka:

import hmac, hashlib

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Eurodebt-Signature', '')
    expected = 'sha256=' + hmac.new(WEBHOOK_SECRET.encode(), request.data, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return 'Invalid signature', 401

    return 'OK', 200

PHP:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EURODEBT_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $payload, WEBHOOK_SECRET);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

http_response_code(200);

Záhlaví webhooku

Každý požadavek webhooku obsahuje následující hlavičky:

Zásady opakování webhooku

Pokud se doručení webhooku nezdaří, systém implementuje mechanismus automatického opakování:

1. Okamžité opakované pokusyAž 3 pokusy se zpožděním 1 s, 5 s a 30 s
2. Plánované opakované pokusyPokud okamžité opakované pokusy selžou, webhook naplánuje opakované pokusy na pozadí v rostoucích intervalech:
   • 5 minut, 15 minut, 30 minut, 1 hodina, 2 hodiny, 4 hodiny, 8 hodin
3. Maximální počet opakováníPo celkem 10 pokusech je webhook označen jako neúspěšný.

Chyby, které lze opakovat:

• Časové limity sítě a chyby připojení
• Chyby serveru HTTP 5xx

Chyby, které nelze opakovat (žádné další pokusy):

• Chyby klienta HTTP 4xx (kromě 429)

Stav doručení webhooku

Stav doručení webhooku můžete zkontrolovat načtením požadavku na ověření:

Důležité poznámky

• Odpovězte rychleVrátit status 2xx do 10 sekund pro potvrzení přijetí
• Ověření podpisůVždy ověřte X-Eurodebt-Signature hlavička

1. Podat žádost → POST /verification/submit Vrací requestId
2. Zpracování → Ověření je zpracováno
3. Dokončení → Webhook se odesílá (pokud je nakonfigurován) s status: "completed" or status: "rejected"
4. Načíst zprávu → Použití verificationId z webhooku nebo ankety GET /verification/request/{id}

Několik koncových bodů podporuje language parametr pro přeložitelná pole.

Všechny chyby vracejí konzistentní strukturu JSON:

{
  "error": {
    "type": "ERROR_TYPE",
    "message": "Human-readable error description"
  }
}

Koncové body pro odesílání a načítání žádostí a zpráv o ověření

Koncové body pro monitorování využití účtu a kvót

Zpětná volání webhooku odeslaná Eurodebtem po dokončení operací. Každý typ webhooku má svou vlastní strukturu datové části popsanou níže.