Dokumentace partnerského API

Autentizace

Každý request se ověřuje partnerským API klíčem. Klíč vložte do hlavičky Authorization: Bearer <klíč>, případně do X-API-Key: <klíč>. Klíč je vázaný na váš účet a plán (Silver / Gold / Platinum) a určuje denní limit i velkoobchodní cenu. Klíč nikdy nevkládejte do URL ani nesdílejte v klientském kódu.

curl https://unlocker.bytedev.cz/api/partner/unlocker/v1/services \
  -H "Authorization: Bearer sk_live_vas_partnersky_klic"

GET /api/partner/unlocker/v1/services

Vrátí katalog služeb s cenou přepočtenou na velkoobchodní sazbu vašeho plánu.

{
  "services": [
    {
      "id": "imei-basic-check",
      "slug": "zakladni-overeni-imei",
      "title": "Základní ověření IMEI",
      "shortTitle": "IMEI kontrola",
      "inputKind": "imei",
      "serviceKind": "check",
      "deviceFamilies": ["iphone", "android"],
      "priceCzk": 40,
      "publicPriceCzk": 49,
      "wholesaleDiscountPercent": 20,
      "expectedTurnaroundMinutesMin": 1,
      "expectedTurnaroundMinutesMax": 5,
      "requiresProofOfOwnership": false
    }
  ]
}

priceCzk je cena, kterou platíte vy (po velkoobchodní slevě), publicPriceCzk je doporučená maloobchodní cena pro koncového zákazníka.

POST /api/partner/unlocker/v1/checks

Spustí kontrolu jednoho zařízení. Zpracování je asynchronní — výsledek získáte přes GET podle id.

{
  "serviceId": "imei-basic-check",
  "identifier": "351234567890123",
  "reference": "objednavka-1042",
  "attestationAccepted": true
}

{
  "checkId": "chk_9f3a7b2c",
  "status": "processing",
  "identifierMasked": "3512••••••0123"
}

Služby bez okamžité API kontroly (odemčení, kompletní servisní historie) se zařadí do fronty a vrátí HTTP 202 se status ve stavu manuálního zpracování a polem fulfilment. Služby vyžadující doklad vlastnictví (requiresProofOfOwnership: true) vyžadují schválený proofCaseId a proofAccessToken.

GET /api/partner/unlocker/v1/checks/{id}

Vrátí aktuální výsledek kontroly. Přístup je omezen na kontroly patřící vašemu účtu.

{
  "checkId": "chk_9f3a7b2c",
  "status": "completed",
  "result": {
    "blacklist": { "status": "clean" },
    "simLock": { "status": "unlocked" },
    "findMy": { "status": "off" }
  }
}

POST /api/partner/unlocker/v1/batch

Hromadná kontrola více identifikátorů jedním requestem. Vyžaduje plán s hromadným přístupem (Gold a vyšší). Jedno chybující zařízení nepoloží celou dávku — neúspěšné položky se vrací jednotlivě.

{
  "serviceId": "imei-basic-check",
  "identifiers": ["351234567890123", "352234567890987"],
  "attestationAccepted": true
}

{
  "accepted": 1,
  "failed": 1,
  "checks": [
    { "ok": true, "checkId": "chk_1", "status": "processing", "identifierMasked": "3512••••••0123" },
    { "ok": false, "error": "provider_rejected", "message": "Neplatný identifikátor zařízení." }
  ]
}

Účtujeme pouze kontroly, které poskytovatel přijal (accepted).

GET /api/partner/unlocker/v1/balance

Vrátí zůstatek peněženky, aktuální plán a zbývající denní limit kontrol.

{
  "balanceCzk": 1240,
  "plan": "gold",
  "dailyRemaining": 47
}

Limity a kvóty

Denní limit kontrol určuje váš plán (Free 3, Silver 20, Gold 50, Platinum 100). Po vyčerpání limitu vrací API rate_limited (HTTP 429); zbývající limit sledujte přes /balance. Kontroly se hradí z předplaceného kreditu peněženky — udržujte dostatečný zůstatek, aby se dávka nezastavila.

Chybové kódy

Chyby vrací JSON s polem error (stabilní kód) a odpovídajícím HTTP stavem.

Vydání API klíče

Klíč si vydáte samoobslužně z partnerského účtu. Při integraci vám rádi poradíme — napište na support@tvojedata.cz. Přehled plánů a cen najdete na stránce API.