Partnerské API

Jak to funguje

API je pro všechny partnery stejné. V pěti krocích:

1. API vám pro firmu zapneme; ve své administraci si v záložce API vytvoříte API klíč.
2. Když se má klient proškolit, váš systém zavolá POST /v1/users s vaším identifikátorem klienta.
3. Založíme profil bez e-mailu a vrátíme vstupní odkaz (entryUrl); ten klientovi ukážete jako tlačítko.
4. Klient na něj klikne a je rovnou v kurzu.
5. Stav si kdykoli přečtete přes GET /v1/users/{identifier}, nebo ho vašemu serveru oznámíme webhookem.

Správcem identifikátoru jste vy, my zpracováváme jen pseudonymní data. Jako identifikátor nikdy neposílejte e-mail ani jméno - e-mailovou adresu API odmítne chybou 422.

Adresa a autentizace

Každé volání jde přes HTTPS na adresu níže a nese váš API klíč v hlavičce Authorization.

https://api.responsiblo.com
Authorization: Bearer rsb_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

• rsb_live_... otevírá váš produkční program, rsb_test_... váš testovací program (sandbox).
• Klíč se ukáže jen jednou, při vytvoření; ukládáme si jen jeho otisk. Mějte ho jako tajemství na svém serveru - nikdy v prohlížeči ani v aplikaci.
• Klíč má oprávnění: read (stav osob) a write (posílání osob). Může být omezený na vaše IP adresy a mít platnost.
• Výměna: vytvoříte nový klíč, starý platí ještě 7 dní, pak vyprší.
• Odpovědi se nikdy neukládají do mezipaměti (Cache-Control: no-store) a API nepřijímá volání z prohlížeče (bez CORS).

POST /v1/users

Pošle osobu do programu klíče (oprávnění write).

curl -X POST https://api.responsiblo.com/v1/users \
  -H "Authorization: Bearer $RSB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"client-48213","language":"cs","label":"campaign-2026-10"}'

201 Created pro novou osobu, 200 OK, když identifikátor už existuje - nic se nemění, volání lze bezpečně opakovat. Tělo je stav níže i s entryUrl. Vyčerpaný limit osob nebo licence programu vrací 403.

GET /v1/users/{identifier}

Stav osoby (oprávnění read): to, co compliance check potřebuje, nic navíc.

curl https://api.responsiblo.com/v1/users/client-48213 -H "Authorization: Bearer $RSB_KEY"

{
  "identifier": "client-48213",
  "program": "your-program",
  "status": "in_progress",
  "progress": 43,
  "lessonsCompleted": 3,
  "lessonsTotal": 7,
  "quizScore": null,
  "label": "campaign-2026-10",
  "createdAt": "2026-10-20T10:02:11Z",
  "startedAt": "2026-10-20T10:05:40Z",
  "completedAt": null,
  "lastActivityAt": "2026-10-20T10:31:40Z",
  "expiresAt": null,
  "certificate": null,
  "entryUrl": "https://your-academy.responsiblo.com/entry/..."
}

quizScore je výsledek závěrečného kvízu v %, jakmile je dokončený. Časy jsou v UTC na celé sekundy. Pole certificate je vyhrazené a ve verzi 1.1 má hodnotu null.

?include=detail

Přidá postup v každém kurzu a výsledek každého kvízu - nikdy jednotlivé odpovědi.

"courses": [{"id": "733db340-...", "name": "Introduction", "progress": 40, "lessonsCompleted": 2, "lessonsTotal": 5, "completed": false}],
"quizzes": [{"id": "d2e72fd7-...", "name": "Quiz of the introduction", "score": 85, "completedAt": "2026-10-20T10:31:40Z"}]

Vstupní odkaz

entryUrl ukažte osobě (tlačítko Spustit kurz ve vašem systému). Přihlásí ji do kurzu - bez e-mailu a bez hesla.

Odkaz platí 30 dní a lze ho použít opakovaně; každé volání GET /v1/users/{identifier} vrátí nový. Nikdy ho neposílejte nikomu jinému: kdo odkaz má, vstoupí jako ta osoba.

Webhooky

V záložce API své administrace nastavíte jeden webhook pro každý program: veřejnou HTTPS adresu svého serveru a události. Pak vám posíláme POST s JSON - jen identifikátory a stavy, nikdy vstupní odkaz.

POST https://your-server.example/responsiblo/webhook
Content-Type: application/json
X-Responsiblo-Event: user.completed
X-Responsiblo-Delivery: 5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77
X-Responsiblo-Signature: t=1760954400,v1=3f1c...e9

{
  "id": "5b0c1f9e-2d1a-4a57-9a3e-0d6c9c1f2b77",
  "type": "user.completed",
  "createdAt": "2026-10-20T10:40:00Z",
  "apiVersion": "1.1.0",
  "program": "your-program",
  "data": {
    "identifier": "client-48213",
    "status": "completed",
    "progress": 100,
    "lessonsCompleted": 7,
    "lessonsTotal": 7,
    "quizScore": 85,
    "label": "campaign-2026-10",
    "startedAt": "2026-10-20T10:05:40Z",
    "completedAt": "2026-10-20T10:39:12Z",
    "expiresAt": null
  }
}

Podpis

Každá zpráva nese hlavičku X-Responsiblo-Signature: t=<unixový čas>,v1=<HMAC-SHA256 textu t.tělo s tajemstvím webhooku, hex>. Tajemství (whsec_...) se ukáže jednou při vytvoření webhooku. Než zprávě uvěříte, ověřte podpis i stáří t; jako klíč idempotence použijte X-Responsiblo-Delivery.

// PHP: $secret = "whsec_...", $header = X-Responsiblo-Signature, $body = the raw body
preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m);
$valid = $m
    && abs(time() - (int) $m[1]) <= 300
    && hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2]);

Doručení a opakování

Doručeno = odpověď 2xx do 10 sekund. Jinak to zkusíme znovu za 1 minutu, 5 minut, 30 minut, 2 hodiny a 12 hodin, pak to vzdáme. Přesměrování nesledujeme.

20 nedoručených zpráv po sobě webhook vypne, dokud ho znovu nezapnete; zprávy z té doby počkají. Tlačítko Otestovat pošle ping; log doručení najdete ve své administraci.

Chyby

Každá chyba má jeden tvar: status, code, reason a message; chyba 422 přidá errors (pole - co je špatně).

{ "status": "error", "code": 422, "reason": "invalidBody", "message": "The body is not valid.",
  "errors": { "identifier": "identifier must be a pseudonym of the partner, never an e-mail address" } }

Limity

120 volání za minutu na klíč. Po 30 odmítnutých klíčích z jedné adresy během deseti minut adresa 10 minut čeká.

Stav a kontrakt

• GET /v1/status - bez klíče, vrací {"status":"ok","version":"1.1.0"}
• GET /openapi - bez klíče, dokument OpenAPI 3 celého API

Sandbox

Testovací klíč rsb_test_... otevírá váš testovací program se stejným kurzem. Osoby v něm končí po 7 dnech; webhook testovacího programu je oddělený od produkčního.

Původní rozhraní

GET /v1/user/{identifier} (plný export s každou odpovědí kvízu) funguje dál s JWT vašeho partnerského klíče a nově i s API klíčem s oprávněním read.

Historie verzí

• 1.1.0 (2026-10) - API klíče, POST /v1/users, GET /v1/users/{identifier} s ?include=detail, vstupní odkaz, webhooky, jeden tvar chyb, veřejný stav a OpenAPI, limity.
• 1.0.0 (2024) - GET /v1/user/{identifier} s JWT partnerského klíče.

Chcete API pro svou firmu? Napište nám