Dokumentace k API SSLmarketu

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.
<?php
// 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 '</pre>';
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