Dokumentace k API SSLmarketu. verze 1.3

Dokumentace k API SSLmarketu verze 1.3

ZONER Software a.s. 2015

Obsah Úvod ................................................................................................................................................................................... 3 Legenda .............................................................................................................................................................................. 3 Funkce API ......................................................................................................................................................................... 4 Návratové hodnoty.............................................................................................................................................................. 8 SWAPI - přihlašovací údaje ............................................................................................................................................... 8 SWAPI - nastavení výchozích údajů .................................................................................................................................. 8 SWAPI - testovací debug mód............................................................................................................................................ 9 Vzorová implementace v PHP ............................................................................................................................................ 9 Podpora ............................................................................................................................................................................. 11

2

Úvod SSLmarket API umožňuje zákazníkům automatizovat proces vytváření objednávek SSL certifikátů. Parametry objednávky jsou odesílány jako HTTP POST požadavek na server https://www.sslmarket.cz/api. Díky tomu může zákazník odesílat požadavky na objednávky ze svého systému. Provádět objednávky je možné pouze po přihlášení prostřednictvím přihlašovacích údajů do účtu SSLmarketu. V kapitole Vzorová implementace v PHP se nachází jednoduchá implementace, ze které je možné vycházet při nasazení do zákaznického systému. Další vzorová implementace se nachází na https://www.sslmarket.cz/download/SWAPI_1.1.zip. Výhodou této implementace je okamžitá možnost jejího nahrání na server a následného používání. Více informací je možné najít v README.txt souboru archivu.

API endpoint: https://www.sslmarket.cz/api

Legenda p a ra me t r – název klíče, který je nutné odeslat prostřednictvím HTTP POST na API endpoint SSLmarketu h o dn ot a – tímto stylem jsou v následujícím textu vyznačena povolené hodnoty jednotlivých parametrů

3

Funkce API V následujících odstavcích se dozvíte, jaké funkce jsou přiřazeny jednotlivým parametrům objednávky SSL certifikátů.

Parametry objednávky (povinné) = vaše zákaznické číslo SSLmarket účtu (lze nalézt na adrese: https://www.sslmarket.cz/customer/index/customer/)

c u st om e r_ id p a ss wo r d m e th od

(povinné)

(povinné)

= vaše heslo k SSLmarket účtu

= metoda, která bude zavolaná

ne w = vytvoření objednávky pro nový certifikát re ne w = obnovení objednávky pro obnovu expiračního certifikátu d o ma in y e ar s

(povinné)

(povinné)

= název domény, pro kterou má být certifikát vystaven

= délka platnosti certifikátu (v rocích)

1 - 3 pro certifikát THAWTE_SSL_123 1 - 3 pro certifikát THAWTE_WEB_SERVER 1 - 2 pro certifikát THAWTE_WEB_SERVER_EV 1 - 2 pro certifikát THAWTE_WEB_SERVER_WILDCARD 1 - 3 pro certifikát THAWTE_SGC_SUPERCERTS 1 - 2 pro certifikát THAWTE_CODE_SIGNING 1 - 3 pro certifikát SYMANTEC_SECURE_SITE 1 - 3 pro certifikát SYMANTEC_SECURE_SITE_PRO 1 - 2 pro certifikát SYMANTEC_SECURE_SITE_EV 1 - 2 pro certifikát SYMANTEC_SECURE_SITE_PRO_EV 1 - 3 pro certifikát SYMANTEC_SECURE_SITE_WILDCARD 1 - 3 pro certifikát SYMANTEC_CODE_SIGNING 1 - 3 pro certifikát GEOTRUST_QUICKSSL_PREMIUM 1 - 3 pro certifikát GEOTRUST_TRUE_BUSINESSID 1 - 2 pro certifikát GEOTRUST_TRUE_BUSINESSID_EV 1 - 3 pro certifikát GEOTRUST_TRUE_BUSINESSID_WILDCARD 1 - 3 pro certifikát RAPIDSSL_RAPIDSSL 1 - 3 pro certifikát RAPIDSSL_RAPIDSSL_WILDCARD 1 pro certifikát RAPIDSSL_FREESSL

4

c e rt if i ca te

(povinné) =

textový kód certifikátu

T HA WT E_ S SL _1 2 3 T HA WT E_ W EB _S E RV ER T HA WT E_ W EB _S E RV ER _ EV T HA WT E_ W EB _S E RV ER _ WI LD CA R D T HA WT E_ S GC _S U PE RC E RT S T HA WT E_ C OD E_ S IG NI N G S YM AN TE C _S EC U RE _S I TE S YM AN TE C _S EC U RE _S I TE _P RO S YM AN TE C _S EC U RE _S I TE _E V S YM AN TE C _S EC U RE _S I TE _P RO _ EV S YM AN TE C _C OD E _S IG N IN G G EO TR US T _Q UI C KS SL _ PR EM IU M G EO TR US T _T RU E _B US I NE SS ID G EO TR US T _T RU E _B US I NE SS ID _ EV G EO TR US T _T RU E _B US I NE SS ID _ WI LD C AR D R AP ID SS L _R AP I DS SL R AP ID SS L _R AP I DS SL _ WI LD CA R D S YM AN TE C _S EC U RE _S I TE _W IL D CA RD R AP ID SS L _F RE E SS L s a ns _c o un t

(povinné pouze pro certifikáty podporující SANy)

= počet SANů

0 - 24 pro certifikát THAWTE_WEB_SERVER 0 - 24 pro certifikát THAWTE_WEB_SERVER_EV 0 - 24 pro certifikát THAWTE_SGC_SUPERCERTS 0 - 24 pro certifikát SYMANTEC_SECURE_SITE 0 - 24 pro certifikát SYMANTEC_SECURE_SITE_PRO 0 - 24 pro certifikát SYMANTEC_SECURE_SITE_EV 0 - 24 pro certifikát SYMANTEC_SECURE_SITE_PRO_EV 0 , 4 pro certifikát GEOTRUST_QUICKSSL_PREMIUM 0 , 4 -1 0 0 pro certifikát GEOTRUST_TRUE_BUSINESSID 0 , 4 -1 0 0 pro certifikát GEOTRUST_TRUE_BUSINESSID_EV

5

s a ns

(povinné pouze pro certifikáty podporující SANy)

= seznam SANů oddělené čárkami

h a sh _a l go ri th m

(nepovinné)

= hashovací algoritmus certifikátu

SH A2 - 25 6 (výchozí, pokud není zadáno) SH A- 1 u s e_ zo n er _s er v er

(nepovinné)

= je server hostován u ZONERu (CZECHIA.COM, Zonercloud)?

0 (výchozí, server není hostován u ZONERu) 1 (server je hostován u ZONERu) csr

(nepovinné)

= CSR request pro certifikát

d v _a ut h _m et ho d

(povinné pouze pro certifikáty vyzařující DV ověření)

= způsob ověření, že vlastníte danou doménu

Em ai l (ověření prostřednictvím e-mailu odeslaného do mailboxu viz parametr verify_mailbox) DN S (ověření pomoci kódu vloženého do DNS) FI LE (ověření pomoci souboru na serveru nahraného přes FTP) Podporují následující certifikáty: THAWTE_SSL_123 RAPIDSSL_RAPIDSSL RAPIDSSL_RAPIDSSL_WILDCARD RAPIDSSL_FREESSL GEOTRUST_QUICKSSL_PREMIUM

v e ri fy _ ma il bo x

(nepovinné)

= výběr mailboxu, na který je zaslán ověřovací e-mail

WH OI S (výchozí, systém zkusí zjistit e-mail vlastníka domény z WHOIS) ad mi n@ (mailbox bude mít tvar: [email protected]) ad mi ni s tr at or @ (mailbox bude mít tvar: [email protected]) ho st ma s te r@ (mailbox bude mít tvar: [email protected]) we bm as t er @ (mailbox bude mít tvar: [email protected]) po st ma s te r@ (mailbox bude mít tvar: [email protected]) v o uc he r n o te

(nepovinné)

(nepovinné)

= slevový kód na certifikát

= poznámka k objednávce

Pokud je zadána, je objednávka zpracována ručně.

t e st

(nepovinné)

= spuštění testovacího režimu (jakákoliv hodnota)

Objednávka nebude vložena do systému. Vrátí se výsledek odeslaného dotazu.

6

Příklad vrácených parametrů:

a m ou nt - cena objednávky bez DPH v a t = DPH objednávky /100 např.:

1 = bez DPH 1.1 = 10 % 1.21 = 21 %

Údaje kontaktu o w ne r_ n am e

(povinné)

o w ne r_ s tr ee t o w ne r_ c it y o w ne r_ z ip

= jméno vlastníka certifikátu

(povinné)

(povinné)

(povinné)

o w ne r_ c ou nt ry

= ulice vlastníka certifikátu

= město vlastníka certifikátu

= PSČ vlastníka certifikátu

(povinné)

= dvoupísmenný kód země vlastníka certifikátu

(ISO 3166-1 alpha-2) (povinné)

= jméno vlastníka certifikátu

a u th _l a st na me

(povinné) =

příjmení vlastníka certifikátu

a u th _t e l

= telefon vlastníka certifikátu

a u th _f i rs tn am e

(povinné)

a u th _e m ai l

(povinné)

t e ch _f i rs tn am e

= e-mail vlastníka certifikátu

(povinné)

= jméno technické osoby certifikátu

= příjmení technické osoby certifikátu

t e ch _l a st na me

(povinné)

t e ch _t e l

= telefon technické osoby certifikátu

(povinné)

t e ch _e m ai l

(povinné)

i n vo ic e _n am e

(povinné)

i n vo ic e _s tr ee t i n vo ic e _c it y i n vo ic e _z ip

= e-mail technické osoby certifikátu = fakturační jméno subjektu certifikátu

(povinné)

(povinné)

(povinné)

i n vo ic e _c ou nt r y

= fakturační ulice subjektu certifikátu

= fakturační město subjektu certifikátu

= fakturační PSC subjektu certifikátu

(povinné)

= fakturační dvoupísmenný kód země subjektu certifikátu

(ISO 3166-1 alpha-2)

i n vo ic e _ b us in e ss _i d i n vo ic e _ v at _i d

(nepovinné)

(nepovinné)

= fakturační IČO subjektu certifikátu

= fakturační DIČ subjektu certifikátu

7

Návratové hodnoty Odpověď API je ve formátu JSON.

Parametry: a c k = výsledek volání dotazu Su cc es s (požadavek byl přijat) Er ro r (požadavek obsahoval chyby, viz errors) e r ro rs = pole chyb, vraceno pouze pokud je "ack" roven "Error" d a ta = pole dat, vráceno pouze pokud je nastaven parametr "test"

SWAPI - přihlašovací údaje Přihlašovací údaje jsou v souboru default_order_params.php.

'customer_id' => 'vase_zakaznicke_cislo', 'password' => 'vase_silne_heslo',

Uvádí se v něm zákaznické číslo a heslo pro identifikaci objednávky. Použijte stejné údaje, jako pro zákaznický účet SSLmarketu.

SWAPI - nastavení výchozích údajů Nastavení (výchozích) defaultních údajů je v souboru default_order_params.php. Můžete zde nastavit údaje kontaktů, které se budou ve formuláři nabízet jako výchozí.

U DV certifikátů s doménovým ověřením se tyto kontakty neověřují a v certifikátu nejsou uvedeny. Pokud budete objednávat více DV certifikátů, můžete používat tyto výchozí údaje.

'owner_name' => 'Jméno vlastníka', 'owner_street' => 'Ulice', 'owner_city' => 'Město', 'owner_zip' => '12345', 'owner_country' => 'CZ', 'owner_tel' => '+420.123456789', 'auth_firstname' => 'Jméno', 'auth_lastname' => 'Příjmení',

8

'auth_tel' => '+420.123456789', 'auth_email' => '[email protected]', 'tech_firstname' => 'Jméno', 'tech_lastname' => 'Příjmení', 'tech_tel' => '+420.123456789', 'tech_email' => '[email protected]', 'invoice_name' => 'Fakturační jméno subjektu', 'invoice_street' => 'Ulice', 'invoice_city' => 'Město', 'invoice_zip' => '12345', 'invoice_country' => 'CZ', 'invoice_email' => '[email protected]'

SWAPI - testovací debug mód Testování se zapíná nastavení parametru debug na true v souboru default_order_params.php.

Při aktivním debug módu se objednávka pošle serveru SSLmarketu a ten odpoví, zdali je OK či nikoliv. Objednávka se ve SSLmarketu neuloží a nevytvoří!

Druhou funkcí užitečnou pro testování je možnost pozastavení objednávky díky poznámce uvedené v objednávce. Při objednávání se připojí textová poznámka a v SSLmarketu se taková objednávka automaticky nezpracuje.

Vzorová implementace v PHP Pro funkčnost následujícího kódu je potřeba mít ve stejném adresáři jako je spouštěný PHP skript soubor cabundle.pem. Tento soubor si můžete stáhnout na adrese https://www.sslmarket.cz/download/ca-bundle.pem. Následující kód odešle požadavek na SSLmarket API endpoint a následně je vrácena odpověď. Objednávka nebude fyzicky vytvořena v systému SSLmarket, jelikož je aktivní testovací režim (je odeslán parametr test s jakoukoliv hodnotou). Po otestování je možné testovací režim zrušit odebráním parametru test z pole $params.


// Vložte Vaše zákaznické číslo a Vaše heslo $your_customer_id = 'vase_zakaznicke_cislo; $your_password = 'vase_silne_heslo';

$params = array( 'customer_id' => $your_customer_id, 'password' => $your_password, 'method' => 'new',

9

'domain' => 'www.nazev-domeny.cz', 'years' => 3, 'certificate' => 'RAPIDSSL_RAPIDSSL', 'use_zoner_server' => 0, 'owner_name' => 'Jméno vlastníka', 'owner_street' => 'Ulice', 'owner_city' => 'Město', 'owner_zip' => '12345', 'owner_country' => 'CZ', 'owner_tel' => '+420.123456789', 'hash_algorithm' => 'SHA2-256', 'auth_firstname' => 'Jméno', 'auth_lastname' => 'Příjmení', 'auth_tel' => '+420.123456789', 'auth_email' => '[email protected]', 'tech_firstname' => 'Jméno', 'tech_lastname' => 'Příjmení', 'tech_tel' => '+420.123456789', 'tech_email' => '[email protected]', 'invoice_name' => 'Fakturační jméno subjektu', 'invoice_street' => 'Ulice', 'invoice_city' => 'Město', 'invoice_zip' => '12345', 'invoice_country' => 'CZ', 'invoice_email' => '[email protected]', 'dv_auth_method' => 'Email', 'verify_mailbox' => 'admin@', 'test' => 'test', 'note' => 'Testovací objednávka' );

$post = http_build_query($params);

$curl = curl_init(); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true); curl_setopt($curl, CURLOPT_CAINFO, __DIR__ . "/ca-bundle.pem"); curl_setopt($curl, CURLOPT_URL, "https://www.sslmarket.cz/api"); curl_setopt($curl, CURLOPT_POST, true); curl_setopt($curl, CURLOPT_POSTFIELDS, $post); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

10

$result = curl_exec($curl); echo '<pre>'; print_r(json_decode($result)); echo '';

if (curl_error($curl)) { $result = curl_error($curl); var_dump($result); }

Podpora Pokud potřebujete pomoci s jakýmkoliv dotazem, obraťte se na podporu API ([email protected]) nebo na podporu SSLmarketu.

Přejeme vám hodně úspěchů při používání API.

Podpora SSLmarket ZONER software, a.s.

11