Pro vývojáře

1. Registrace do rozhraní

Aby bylo možné nasadit na váš e-shop prvek Adulto je potřeba nejprve provést registraci do B2B sekce. Po registraci možnost získat pro doménu API klíče.

2. Nastavení služeb

Rozhraní pro e-shopy (B2B sekci) najdete na adrese partner.adulto.cz

Po přidání webu získáte API klíče pro integraci prvku Adulto a komunikaci s API.

Rozhraní pro e-shopy slouží pro:

• Přidávání a správu vašich webů
• Nastavení vzhledu ověřovacího prvku
• Nabíjení peněženky
• Ukládání daňových dokladů za provedené platby
• Přehledy ověření zákazníků, volání API a transakcí
• Nastavení požadované úrovně a metod ověření

3. Umístění widgetu na web

Základní způsob použití naší služby je vykreslení widgetu pro ověření věku v nákupním košíku.

Pro vykreslení widgetu (prvku) Adulto na vaší stránce je nutné zahrnout potřebného zdroje JavaScriptu a adulto-cz značky. Značka adulto-cz je prvek DIV s názvem třídy adulto-cz a veřejným API klíčem vašeho webu v data-sitekey atributu.

Na místo, kde chcete, aby byl umístěn ověřovací widget, vložte kód:

<div class="adulto-cz" data-sitekey="VEREJNY_KLIC"></div>

Na konec HTML kódu stránky, kde se bude zobrazovat widget, před </body> vložte:

<script async src="https://api.js.m2a.cz/api.js"></script>

Nyní se widget Adulto bude zobrazovat na vaší stránce.

Ve výchozím stavu Adulto ověřuje zda je zákazník starší 18 let. Pokud chcete nastavit jiný věkový limit pro ověření, můžete tak učinit přidáním pole input, takto:

<input type="hidden" data-adultocz="customer_age" value="15">

4. Individuální ověření pomocí mobilní aplikace

Novinka Pomocí API je možné vyvolat žádost o ověření a získat QR kód, který uživateli umožní jeho ověření v mobilní aplikací Adulto. Zavoláním API se v našem systému vytvoří nová session čekajícího ověření. Jakmile se uživatel ověří zavoláme vámi nastavenou URL a předáme na ní výsledek ověření. Pro spuštění ověření slouží QR kód nebo URL adresa, obojí získáte po zavolání API.

Pokud uživatel QR kód načte standardním způsobem, nabídne se mu instalace aplikace nebo spuštění ověření. Pokud uživatel QR kód načte přímo v mobilní aplikaci, spustí se ověření.

Povinné parametry pro volání API:

• URL pro volání API: https://api.result.adulto.cz/push/
• Povinný GET parametr secret: Privátní API klíč získaný pro některou doménu učtu
• Nepovinný GET parametr url: URL adresa pro předání výsledku - callback
• Nepovinný GET parametr age: Požadovaný věk (výchozí 18 let, min. 15, max. 65)

Ukázka odpovědi ve formátu JSON:

{
    "adultocz-uid":"fb9328f5b8e13d325782a67ebd916d9766f95ff4dd9d88a901...",
    "adultocz-image":"https:\/\/qr.m2a.cz\/image\/300\/........svg",
    "adultocz-link":"https:\/\/moje.adulto.cz\/overeni-veku\/?qr_verify=......."
}

Formát předání výsledku na vaší URL (pokud byla nastavena) POST JSON:

{
    "adultocz-verify-id":"2029010101",
    "adultocz-verify-uid":"fb9328f5b8e13d325782a67ebd916d9766f95ff4dd9d88a901...",
    "adultocz-verify-time":"2023-12-31 08:21:15",
    "adultocz-verify-method":"bankid",
    "adultocz-verify-status":"true",
    "adultocz-verify-age":"18",
    "adultocz-verify-adult":"true"
}

5. Komunikace API pro vývojáře

Pokud chcete pracovat s výsledky ověření automatizovaně, použijte následující API.

Povinné parametry pro volání API:

• URL pro volání API: https://api.result.adulto.cz
• Povinný GET parametr secret: Privátní API klíč získaný pro konkrétní doménu
• Povinný GET parametr response: Token uživatele adultocz-uid

Odpověď API je ve formátu JSON a při správném volání obsahuje:

• adultocz-verify-id string
  Unikátní číslo ověření v našem systému
• adultocz-verify-uid string
  Unikátní identifikátor ověření musí být shodný s adultocz-uid
• adultocz-visit-cookie string
  Unikátní obsah cookie adultocz_local vytvořené uživateli, můžete použít pro analytiku
• adultocz-visit-time YYYY-MM-DD HH:MM:SS
  Datum a čas prvního načtení widgetu nebo vytvoření ověření endpointem /push/
• adultocz-verify-time YYYY-MM-DD HH:MM:SS
  Datum a čas doručení výsledku ověření
• adultocz-verify-method string
  Metoda ověření věku (bankid/mojeid/ocrid/seznam/datovka/nia/code/cookie/app nebo empty)
• adultocz-verify-method-level string
  Důvěryhodnost metody ověření věku (low/essential/high)
• adultocz-verify-status true/false
  Informace zda proběhlo ověření (bez ohledu na výsledek)
• adultocz-verify-age string
  Číslo vyjadřující minimální požadovaný věk zákazníka při ověření
• adultocz-verify-adult true/false
  Informace zda zákazník splňuje minimální požadovaný věk a udělil souhlas s ověřením

Ukázka odpovědi ve formátu JSON:

{
    "adultocz-verify-id":"2029010101",
    "adultocz-verify-uid":"95240b123f0aadf1c1e1d4ef1fga2f121f397325e342",
    "adultocz-visit-cookie":"a877e311-fc21-5500-8011-ab9a7b7f06566-1702076000000",
    "adultocz-visit-time":"2023-12-31 08:15:44",
    "adultocz-verify-time":"2023-12-31 08:21:15",
    "adultocz-verify-method":"bankid",
    "adultocz-verify-method-level":"essential",
    "adultocz-verify-status":"true",
    "adultocz-verify-age":"18",
    "adultocz-verify-adult":"true"
}

6. Příklad komunikace API při použití widgetu

Zkontrolujte, zda proběhlo ověření:

if(!empty($_POST['adultocz-uid'])) {
...
}

Odešlete požadavek na API:

$adultocz = json_decode(file_get_contents('https://api.result.adulto.cz/?secret=PRIVATNI_KLIC&response='.$_POST['adultocz-uid']));

Zpracujte odpověď API:

if($adultocz->{'adultocz-verify-adult'} == 'true'){
...
}

Celý příklad použití v PHP:

if (!empty($_POST['adultocz-uid'])) {

    $api_url = "https://api.result.adulto.cz";
    $klic = "PRIVATNI_KLIC"; // Nahraďte přiděleným privátním klíčem API
    $pozadovany_vek = 18; // Můžete nahradit požadovaným věkem

    // Sestavení celé API URL
    $api_url = $api_url . '/?secret=' . $klic . '&response=' . $_POST['adultocz-uid'];

    // Volání API
    $response = file_get_contents($api_url);

    // Ověření API komunikace
    if ($response === false) {
        echo 'Chyba při komunikaci s Adulto.';
        exit;
    }

    // JSON odpověď API
    $adultocz = json_decode($response);

    // Podmínka pro úspěšné ověření
    if (
        $adultocz // Existuje JSON odpověď
        && isset($adultocz->{'adultocz-verify-adult'})
        // Byl dosažen požadovaný věk?
        && $adultocz->{'adultocz-verify-adult'} === 'true'
        // Kontrola požadovaného věku
        && isset($adultocz->{'adultocz-verify-age'})
        && $adultocz->{'adultocz-verify-age'} == $pozadovany_vek
    ){
        
        echo 'Jste starší ' . $pozadovany_vek . ' let. Objednávka byla zpracována.';

        // Uložení identifikátorů ověření
        $adulto_id = $adultocz->{'adultocz-verify-id'} ?? null;
        $adulto_uid = $adultocz->{'adultocz-verify-uid'} ?? null;

        // Smazání cookie pro zapomenutí ověření
        setcookie('adultocz_local', '', time() - 3600, '/', '', true, true);

    } elseif ($adultocz
              && isset($adultocz->{'adultocz-verify-adult'})
              // Požadovaný věk nebyl dosažen
              && $adultocz->{'adultocz-verify-adult'} === 'false'
    ) {

        // Ověřený věk není dostatečný
        echo 'Nemůžeme prodávat osobám mladším ' . $pozadovany_vek . ' let.';

    } else {

        echo 'API odpověď je neplatná.';

    }

} else {
    echo 'Váš věk nebyl ověřen.';
}

7. API - Dotaz na stav kreditu

Pomocí API můžete získat informaci o aktuálním stavu kreditu v kreditní peněžence vašeho uživatelského účtu s max. 5 minutovým zpožděním.

Povinné parametry pro volání API:

• URL pro volání API: https://api.result.adulto.cz/credit.status/
• Povinný GET parametr secret: Privátní API klíč získaný pro některou doménu učtu
• Povinný GET parametr response: Uživatelské jméno uživatele do rozhraní pro e-shopy

Ukázka odpovědi ve formátu JSON:

{
    "adultocz-credit-value":"1679.92"
}

8. API - Komunikace Adulto Point

Pomocí API můžete získat unikátní URL adresu pro realizaci ověření věku při fyzické přítomnosti zákazníka Adulto Point. Pro vytvoření Adulto Point a možnost provádět API komunikaci je nutné uzavřít Smlouvu o poskytování asistence při ověření věku.

Parametry pro volání API metodou POST:

• Povinný POST parametr secret: Privátní API klíč získaný pro doménu učtu
• Povinný POST parametr apikey: Veřejný API klíč získaný pro doménu učtu
• Nepovinný POST parametr point: Váš interní identifikátor ověřovacího místa, max. 12 znaků

Ukázka správné odpovědi ve formátu JSON:

{
    "verify_url":"https://..../"
}

Ukázka komunikace API PHP - Adulto Point:

<?php
// API URL
$url = "........."; // URL pro volání API - po uzavření smlouvy

// API AUTENTIFIKACE
$postData = [
    'apikey' => '...', // Veřejný API klíč
    'secret' => '......', // Privátní API klíč
    'point' => '0001' // Nepovinný interní identifikátor ověřovacího bodu
];

// Inicializace cURL
$ch = curl_init($url);

// Nastavení možností cURL
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($postData));

// Odeslání požadavku a uložení odpovědi
$response = curl_exec($ch);

// Zkontrolování chyb cURL
if ($response === false) {
    echo 'Chyba cURL: ' . curl_error($ch);
    curl_close($ch);
    exit;
}

// Zavření cURL
curl_close($ch);

// Převod JSON odpovědi na asociativní pole
$responseData = json_decode($response, true);

// Zpracování odpovědi
if (isset($responseData['error'])) {

    echo 'Chyba: ' . $responseData['error'];  // Výpis případné chyby

} elseif (isset($responseData['verify_url'])) {

    $verifyUrl = $responseData['verify_url'];  // Získání URL
    header('Location: ' . $verifyUrl);  // Přesměrování na získanou URL
    exit;

} else {
    echo 'Neznámá odpověď: ' . $response;
}
?>

Ukázka komunikace API JavaScript - Adulto Point:

// API URL
const url = '.........'; // URL pro volání API - po uzavření smlouvy

// API AUTENTIFIKACE
const postData = {
    apikey: '...', // Veřejný API klíč
    secret: '......', // Privátní API klíč
    point: '0001' // Nepovinný interní identifikátor ověřovacího bodu
};

// Funkce pro odeslání požadavku
async function sendApiRequest() {
    try {
        const response = await fetch(url, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: new URLSearchParams(postData)
        });

        // Kontrola, zda odpověď byla úspěšná
        if (!response.ok) {
            throw new Error(`Chyba: ${response.status} ${response.statusText}`);
        }

        // Zpracování odpovědi jako JSON
        const responseData = await response.json();

        // Zpracování odpovědi
        if (responseData.error) {
            console.error('Chyba:', responseData.error);  // Výpis případné chyby
        } else if (responseData.verify_url) {
            const verifyUrl = responseData.verify_url;  // Získání URL
            window.location.href = verifyUrl;  // Přesměrování na získanou URL
        } else {
            console.error('Neznámá odpověď:', responseData);
        }
    } catch (error) {
        console.error('Chyba při odesílání požadavku:', error.message);
    }
}

// Spuštění funkce
sendApiRequest();

10. Grafika pro umístění na web

Pokud chcete, můžete na svůj web umístit grafiku, která informuje zákazníky o použití ověření věku.

Různé varianty odznaků ve formátu PNG a SVG pro umístění na web si můžete stáhnout tady.

11. Cena a poplatky

Služba je poskytována bez aktivačních a měsíčních poplatků.

Platíte pouze za jednotlivá provedená ověření věku, dle platného ceníku.

Poplatky za ověření jsou odečítány z vaší kreditní peněženky, kterou si nabíjíte dle potřeby.