GoGetSSL API Guide Version: 2.5 (stable)

Transcription

1 GoGetSSL API Guide Version: 2.5 (stable) Dear Partners/Re-sellers, this is second version of our API for re-selling SSL Certificates. We try to be flexible, that s why if you see any missing functionality in our API, than simply contact us and we will develop custom API methods quickly. Thank you for choosing us. Table of contents. 3 Using the API a. UI-BASED Domain Vetting Ordering Scenario b. UI-BASED Organization Vetted Product Ordering Scenario 4 c. Comodo UI-based Organization Vetter Product Ordering Scenario... 5 d. UI-Based Doman and Organization Vetted Product Ordering Scenario.. 6 Web Service Information.. 6 API Methods.. 7 Order Methods.. 8 a. addsslorder. 8 b. addsslreneworder 10 c. getorderstatus 12 d. getorderinvoice.. 12 e. getunpaidorders 13 f. activatesslorder.. 14 g. reissuesslorder.. 14 h. comodoclaimfreeev. 15 Account methods 16 a. getaccountbalance 16 b. getaccountdetails 16 c. gettotalorders 17 d. getallinvoices 17 e. getunpaidinvoices 18 Product methods 18 a. getallproducts 19 b. getallproductprices 19 c. getproductdetails 19 d. getproductprice 20 e. getuseragreement Page - 1

2 Other merhods a. getdomain s 21 b. decodecsr 21 c. getwebservers 22 d. generatecsr 22 e. getcsr 23 Page - 2

3 We offer a REST Request Format API with JavaScript Object Notation (JSON) response format for our partners to directly order and manage their certificate and website identity offerings. API clients can perform functions such as ordering the different products, canceling and fulfilling orders, and querying for order data, and querying for account details data. This API document contains all of the data necessary to integrate with GoGetSSL. Our REST API follows a easy-to-guess Naming convention which makes it a breeze to use it in your projects. Using the API Different API commands are used for initiating or placing an order for server products and client certificate products. Using the API offers additional workflow flexibility beyond the basic UI-based ordering flow. Utilized in conjunction with selectively enabling or disabling different automated communications to a customer, a partner can perform varying levels of the ordering workflow. This allows the integration with our API to be tailored to best suit the needs of the partner s overall provisioning process. Ordering state changes for SSL certificates and server web identity products are asynchronous - an API client initiates an order and then later checks the server for the completed order after the vetting process has been completed. The general approach is to specifically request the status of a specific order. In this case (Figure 2), the ordering flow consists of the following operations: (1) place an order, and then (2) periodically check the status of the specific order. Once the order has been completed, the fulfillment information is returned with the GetOrderStatus operation. This approach is generally less efficient, but might be more appropriate when there is a low volume of certificates being managed. How an order is processed by our support team is dictated by the vetting process employed for a given product. We employ a suite of advanced techniques to vet orders to ensure the authenticity of the requestor. This axiom applies to the API as well. While the same API commands are used to initiate orders for all server products, specific field usages for a given command are also dictated by the vetting requirements of the specified product. To best understand how the API is used to initiate an order, the following subsections provide an overview of the basic process flows for Domain Vetting, Organization Vetting and Domain and Organization Vetting, and how the API is used in conjunction with these vetting approaches. Page - 3

4 UI-BASED Domain Vetting Ordering Scenario We use GeoTrust and thawte s patented Domain Vetting process ensures that a registered contact for a domain approves a request for a server product for that domain. QuickSSL Premium, RapidSSL, RapidSSL Wildcard, thawte SSL123, FreeSSL, Comodo Essential SSL, Comodo PositiveSSL, Comodo Essential Wildcard SSL, Comodo Wildcard PositiveSSL and the GeoTrust Free Trial SSL are products that are Domain Vetted. The Web based ordering process for requesting, approving and issuing certificates is described below: 1. Requestor supplies the CSR, and order contact information. Requestor then chooses an Approver , accepts the subscriber agreement and submits the order. 2. An acknowledgement is sent to the requestor and other order contacts confirming placement of the order. 3. An is sent to the Approver requesting that the Approver review the submitted order. 4. The Approver follows the link in the , reviews the order information and either approves or rejects the order. 5. If the order is approved, the requestor receives the certificate via . UI-BASED Organization Vetted Product Ordering Scenario With Organization Vetting only, validation of the Organizational data submitted with the order is also performed before completing a product order. GeoTrust s True BusinessID, Verisign s Secure Site, Secure Site Pro, Secure Site with EV, Secure Site Pro with EV, Certified Seal, Trust Seal and Code Signing Certificates and thawte s SSL WebServer, SSL Web Server with EV, SSL Web Server Wildcard, SGC Supercert and Code Signing Certificates are Organization Vetted products where the organization and domain authentication are done manually using Symantec s authentication practices. Symantec Partner Authentication orders use the process flow below as well: Requestor supplies the CSR, organization information, and the order contact information. Requestor then accepts the subscriber agreement and submits the order. Page - 4

5 An acknowledgement is sent to the requestor and other order contacts confirming placement of the order. Customer sends corporate documents and other information necessary to verify the organization to the GeoTrust, thawte or Symantec authentication team. This may be an iterative process with GeoTrust, thawte or Symantec sending out requests for additional information. Verify call is placed to the Organization Contact by Geotrust's authentication team (for Symantec and thawte branded products only). Once all the authentication steps have been successfully completed, the certificate is issued. Comodo UI-BASED Organization Vetted Product Ordering Scenario With Organization Vetting only, validation of the Organizational data submitted with the order is also performed before completing a product order Instant SSL, Instant SSL PRO, Instant SSL Premium, PremiumSSL Wildcard, Comodo EV SSL, Comodo EV MDC, Comodo Unified Communication, Comodo Multi Domain Certificates are Organization Vetted products where the organization and domain authentication are done manually using Comodo s authentication practices. Symantec Partner Authentication orders use the process flow below as well: Requestor supplies the CSR, organization information, and the order contact information. Requestor then accepts the subscriber agreement and submits the order. An acknowledgement is sent to the requestor and other order contacts confirming placement of the order. Customer sends corporate documents and other information necessary to verify the organization to the Comodo authentication team. This may be an iterative process with Comodo sending out requests for additional information. Verify call is placed to the Organization Contact by Comodo's authentication team (for EV SSL and EV SSL Multi Domain branded products only). Once all the authentication steps have been successfully completed, the certificate is issued. Page - 5

6 UI-BASED Domain and Organization Vetted Product Ordering Scenario With Domain and Organization Vetting, extensive validation of the requestor s Organizational information is also performed before completing a product order. Requestor supplies the CSR, organization information, and the order contact information. Requestor then chooses an Approver , accepts the subscriber agreement and submits the order. An acknowledgement is sent to the requestor and other order contacts confirming placement of the order. Customer sends corporate documents and other information necessary to verify the organization. This may be an iterative process with Symantec/Comodo sending out requests for additional information. An is sent to the Approver requesting that the Approver review the submitted order. The Approver follows the link in the , reviews the order information and either approves or rejects the order. Upon completion of the vetting and approval process, the organization and tech contact receive the certificate via . Web Service Information This section contains important information about how to establish a test account and perform testing. If you already have a test account in place, please notify support@gogetssl.com if you have any query. If you do not already have a test account set up, you should register for a test account to aid your API client development. To register as a GoGetSSL partner on our customer test system send an to support@gogetssl.com providing your account login which is used on live website: The ORDER Web Service is a set of operations for allowing a partner to place or initiate an order. Page - 6

7 Test API Live API NOTE: fields marked with a ()? are optional for that command. All JSON API requests result in a success value or error value. The two basic variables are: success => 1 and error => 1. All described API methods below are implemented in example scripts using file class: GoGetSSLApi.php which can be downloaded in API Settings section in clients Control Panel ( If errors in a request the following information is provided in the response: error - incremental number message - error message code description - error description Page - 7

8 API Methods Authentication auth URL: /auth/ Request type: POST The auth method authenticate partner and returns unique key parameter, which can be used after for querying GoGetSSL API user Username pass API usage password If no errors in request following parameters will be returned: key - unique session key addsslorder URL: /orders/add_ssl_order/ Request type: POST Order methods AddSSLOrder allows a Partner to do everything a requestor would typically do using our web forms for placing an order via one API operation call. This includes submitting the full order information, such as Technical Contact, Administrative Contact, and CSR as well as, Approver Address (if applicable). Our system validates that the Approver address is checked against the set of Approver addresses that would have been presented to the requestor and can only be successful if there is a match. Upon successful submission of a addsslorder command, Our system automatically sends two Messages: 1. an acknowledging successful submission of the order is sent to the Partner address Page - 8

9 2. An requesting review and approval is sent to the specified approver for the order upon order submission (for domain vetted products and True BusinessID with EV only). From this point forward, the order is processed in the same manner as an order that was submitted via the standard web user interface : product_id - Required. product ID, can be taken from getallproducts methods period - Required. period in months csr - Required. CSR code for SSL certificate server_count - Required. amount of servers, for Unlimited pass -1 approver_ - Required. DCV approver for the primary domain, can be taken from the list provided by getdomain s* methods. This parameter must be used only if dcv_method prameter value is ' '. approver_ s - A comma separated list of domain control validation addresses. One and only one must be provided for each additional domain provided in dns_names parameter. DCV address for the primary domain must not be included to the list. This parameter must be used only if dcv_method prameter value is ' '. webserver_type - Required. webserver type, can be taken from getwebservers method dns_names Required for SAN/UCC/Multi-Domain SSL, for the rest of products this parameter must not be provided. A comma separated list of additional domain names. The list must not contain the primary domain. admin_firstname - Required. admin_lastname - Required. admin_organization - required for OV SSL certificates admin_addressline1 admin_phone - Required. admin_title - Required. admin_ - Required. admin_city - required for OV SSL certificates admin_country - required for OV SSL certificates admin_fax - required for OV SSL certificates admin_postalcode admin_region dcv_method Required. Value of this specifies DCV method to be used. Possible values: ' ', 'http', 'https', 'dns'. tech_firstname - Required. tech_lastname - Required. tech_organization - required for OV SSL certificates tech_addressline1 Page - 9

10 tech_phone - Required. tech_title - Required. tech_ - Required. tech_city- required for OV SSL certificates tech_country - required for OV SSL certificates tech_fax tech_postalcode tech_region org_name - required for OV SSL certificates org_division - required for OV SSL certificates org_duns org_addressline1 - required for OV SSL certificates org_city - required for OV SSL certificates org_country - required for OV SSL certificates org_fax org_phone - required for OV SSL certificates org_postalcode - required for OV SSL certificates org_region - required for OV SSL certificates Note: Quantity of items in the approver_ s list must be always equal to quantity of items in the dns_names list. If no errors in request following parameters will be returned: order_id - unique order ID invoice_id - unique invoice ID order_amount - order amount currency - order currency tax - order tax if applicable tax_rate - order tax rate if applicable success - success code (true) addsslreneworder URL: /orders/add_ssl_renew_order/ Request type: POST AddSSLRenewOrder allows a Partner to do everything a requestor would typically do using our web forms for placing an renew order via one API operation call. This includes submitting the full order Page - 10

11 information, such as Technical Contact, Administrative Contact, and CSR as well as, Approver Address (if applicable). Our system validates that the Approver address is checked against the set of Approver addresses that would have been presented to the requestor and can only be successful if there is a match. In case of an order renewal the system also adds 90 days on top of the validity period, in order to ensure time for the original certificate expiration. Upon successful submission of a addsslreneworder command, Our system automatically sends two messages: 1. an acknowledging successful submission of the order is sent to the Partner address 2. An requesting review and approval is sent to the specified approver for the order upon order submission (for domain vetted products and True BusinessID with EV only). From this point forward, the order is processed in the same manner as an order that was submitted via the standard web user interface The same as for the addsslorder method. The same as for the addsslorder method addsslsanorder URL: /orders/add_ssl_san_order/ Request type: POST Order additional SAN/s method. Use that method to add more SAN names to your Multi-Domain SSL certificates, once SAN is added to the order, you will need to reissue SSL. order_id - ORDER ID to which we will add new SAN count - Quantity of SAN names to add If no errors in request following parameters will be returned: order_id - unique order ID invoice_id Page - 11

12 getorderstatus URL: /orders/status/<order_id> The getorderstatus returns detailed information for the order matching order_id parameter. order_id is returned during addsslorder command. order_id If no errors in request following parameters will be returned: order_id - unique order ID partner_order_id - unique ID returned from partner (Comodo or Thawte) status - order status (active, pending, canceled, payment needed, processing, incomplete) status_description product_id - product ID domain - order submitted domains or FQDN from CSR approver_method domains total_domains - total domains count validity_period - order validity period in months valid_from valid_till csr_code - CSR code of certificate returned if status active ca_code - CA code of certificate id status active crt_code - Certificate code is status active server_count renew webserver_type upgrade approver_ s dcv_method admin_addressline1 admin_addressline2 org_addressline3 org_city org_country org_fax Page - 12

13 org_phone org_postalcode org_region tech_organization tech_addressline1 tech_addressline2 tech_addressline3 tech_city tech_country tech_fax tech_phone tech_postalcode tech_region tech_ tech_firstname tech_lastname tech_title ssl_price ssl_period partner_sslid free_ev_upgrade goget_website codesigning_inviteurl validation_description success - success code (true) getorderinvoice URL: /orders/invoice/<order_id> The getorderinvoice returns detailed information for the invoice matching invoice_id parameter. invoice_id is returned during addsslorder command. order_id Page - 13

14 If no errors in request following parameters will be returned: order_id - unique order ID number - invoice unique number date - invoice creation date subtotal - invoice subtotal amount tax - invoice tax amount tax_rate - invoice tax rate in % total - invoice total amount status - invoice status (paid, unpaid) currency - invoice currency payment_method - invoice payment method (paypal, interkassa, bank_transfer, balance) success - success code (true) getunpaidorders URL: /orders/list/unpaid/ The getunpaidorders method returns list of all unpaid orders. None. orders - array of unpaid orders o id - order ID o total_price - order total price o currency - order currency o date - order date reissuesslorder URL: /orders/ssl/reissue/<order_id> Request type: POST Page - 14

15 The reissuesslorder method process with SSL certificate reissue procedure if you have lost your private key, or you want to add more SAN names for Multi Domain or UCC orders. order_id - your order ID returned in addsslorder method csr - CSR code for SSL certificate approver_ - approver , can be taken from getdomain s* methods approver_ s - A comma separated list of domain control validation addresses. One and only one must be provided for each additional domain. DCV address for the primary domain must not be included to the list. webserver_type - webserver type, can be taken from getwebservers method. dns_names Required for SAN/UCC/Multi-Domain SSL. A comma separated list of additional domain names. The list must not contain the primary domain. dcv_method Domain Control Validation method ( , http, dns). If no errors in request following parameters will be returned: order_id - unique order ID order_status - order status (reissue) validation Contains validation invormation in case of http and dnc DCV methods success - success code (true) comodoclaimfreeev URL: /orders/ssl/comodo_claim_free_ev/<order_id> Request type: POST The comodoclaimfreeev method process with free EV upgrade for Comodo DV orders with default term of 1 year. for validation and further information of all required documents from company/organization will be sent to admin_ address, specified in order: <order_id>. order_id - your order ID returned in addsslorder method org_name - Organization name org_division - Organization division org_duns org_addressline1 - Organization address 1 org_city - Organization city org_country - Organization country ISO format Page - 15

16 org_fax org_phone - Organization phone org_postalcode - Organization postal code org_region - Organization region If no errors in request following parameters will be returned: order_id - unique order ID success - success code (true) resendvalidation URL: /orders/ssl/resend_validation_ /<order_id> The resendvalidation method re-sends validation for the order matching order_id parameter. order_id - Id of the order messge - error message or code success - result code cancelsslorder URL: /orders/cancel_ssl_order/ Request type: POST Use that option to request cancellation/refund of any order. Please note, we respond during hours to all requests. order_id - ID of the order to be cancelled reason Cancellation reason If no errors in request following parameters will be returned: - order_id - unique order ID Page - 16

17 Page - 17

18 Account methods getaccountbalance URL: /account/balance/ The getaccountbalance method returns available credits for partner account. None balance - account available credit currency - currency of available credit success - success value (true) getaccountdetails URL: /account/ The getaccountdetails returns partner account details information None first_name last_name company_name - company name company_vat - company VAT/SN/DUNS company_phone phone fax address city state Page - 18

19 postal_code country - partner address reseller_plan - current partner plan type currency - account default currency success - success value (true) gettotalorders URL: /account/total_orders/ The gettotalorders method returns total order count. None total_orders - total active orders count success - success value (true) getallinvoices URL: /account/invoices/ The getallinvoices method returns list of all partner invoices. None invoices - array of invoices o order_id - invoice order ID o number - invoice serial number o date - invoice creation date o subtotal - subtotal amount o tax - invoice tax amount o total - invoice total amount o status - invoice status (paid, unpaid) Page - 19

20 o tax_rate - invoice tax rate in % o currency - invoice currency o payment_method - invoice payment method (paypal, interkassa, balance, bank_transfer) success - success value (true) gettotaltransactions URL: /account/total_transactions/ The gettotaltransactions method returns list of partner unpaid invoices. None total_transactions count of payments performed by the customer success - success value (true) getunpaidinvoices URL: /account/invoices/unpaid/ The getunpaidinvoices method returns list of partner unpaid invoices. None invoices - array of invoices o order_id - invoice order ID o number - invoice serial number o date - invoice creation date o tax - invoice tax amount o tax_rate - invoice tax rate in % o subtotal - subtotal amount o total - invoice total amount o currency - invoice currency o payment_method - invoice payment method (paypal, interkassa, balance, bank_transfer) success - success value (true) Page - 20

21 Page - 21 EnVers Group SIA

22 Products methods getallproducts URL: /products/ The getallproducts method returns a detailed list of all available SSL certificate products. None products - array of available products o id - unique ID of product to be used with addsslorder method o name - product name o organization is organization validation reqiured (yes, no) o wildcard - is wildcard product (yes, no) o unlimited_servers - is product for unlimited servers (yes,no) o is_multidomain is product multidomain (yes, no) o multidomains_included included SAN o multidomains_maximum max allowed SAN quantity success - success value (true) getallproductprices URL: /products/all_prices/ The getallproductprices returns a detailed list of available product prices. None product_prices - array of product prices o id - product ID o period - product validity period in months (12,24,36,48,60) o price - partner price in USD success - success value (true) Page - 22

23 getproductdetails URL: /products/details/<product_id> The getproductdetails return single product details and price in USD product_id - unique product ID product_id - product ID product_name - product name product_description - product description product_agreement - product User Agreement product_organization is organization validation required product_wildcard are wildcard domains supported product_unlimited_servers product_is_multidomain are multiple domains supported product_multidomains_included count of SANs included product_multidomains_maximum max. allowed SAN count product_prices - array of product prices o period - product validity period in months (12,24,36,48,60) o price - product partner price in USD success - success value (true) getproductprice URL: /products/price/<product_id> The getproductprice returns product prices in USD for specified product_id parameter. Request type GET Page - 23

24 product_id - unique product ID product_price - array of product prices and period o period - product validity period in months (12,24,36,48,60) o price - product partner price success - success value (true) getuseragreement URL: /products/agreement/<product_id> The getuseragreement returns User Agreement for specified product_id parameter. product_id - unique product ID product_id - product ID product_agreement - product User Agreement success - success value (true) Others methods getdomain s URL: /tools/domain/ s/ Request type: POST The getdomain s method returns array of valid approver addresses for specified domain parameter from Comodo API. domain - valid FQDN Page - 24

25 If no errors: ComodoApproval s - array of valid addresses from Comodo API getdomain sforgeotrust URL: /tools/domain/ s/geotrust/ Request type: POST The getdomain s method returns array of valid approver addresses for specified domain parameter from Geotrust API. domain - valid FQDN If no errors: GeotrustApproval s - array of valid addresses from Comodo API decodecsr URL: /tools/csr/decode/ Request type: POST The decodecsr method validates submitted CSR code. Returns parsed data in array. csr - CSR code, length till 4000 simbols If no errors: csrresult - array of decoded CSR data o CN - FQDN csr is generated for o C - country ISO format o OU - department o O - organization o L - state o S - city Page - 25

26 o - address o dnsname(s) additional dns names o Key Size encryption key length o md5 md5 hash o sha1 sha1 hash success - success value (true) getwebservers URL: /tools/webservers/<supplier_id> The getwebservers method returns list of available web server types to be used with other API methods like addsslorder, reissueorder, etc. supplier_id - integer value; for Comodo: 1, for Geotrust/Symantec/Thawte: 2 webservers - array of available webservers o id - ID of webserver o software - Webserver or software name generatecsr URL: /tools/csr/generate/ Request type: POST The generatecsr method generates valid CSR code from the submitted values (2048bits). Returns CSR code, CSR private key and CSR unique ID in array. All your generated CSR codes and CSR private keys are saved in our system, you can request it (method getcsr ) or reuse it for SSL renew anytime. csr_commonname - FQDN csr is generated for, can also be IP or local-domain csr_organization - organization name csr_department - organization department csr_city - city csr_state - state Page - 26

27 csr_country - country in ISO format csr_ - address If no errors: csr_code - CSR code, needed for SSL generation csr_key - CSR private key, needed for SSL installation csr_commonname - FQDN csr is generated for csr_ csr_organization csr_date CSR creation date success - success value (true) getcsr URL: /tools/csr/get/ Request type: POST The getcsr method retrieves available CSR codes and CSR private keys for provided Common Name or CSR ID. Returns CSR code and CSR private key in array. csr_commonname - FQDN csr is generated for, can also be IP or local-domain csr_id - unique ID returned by generatecsr method If no errors: csr_code - CSR code, needed for SSL generation csr_key - CSR private key, needed for SSL installation csr_commonname - FQDN CSR was generated for csr_ - address in CSR csr_organization - organization in CSR csr_date - date of CSR generation success - success value (true) Page - 27

28 changevalidation URL: /orders/ssl/change_validation_ /<order_id> Request type: POST This method can be used for one of the following purposes: In case if DCV method is already used this method can change the current DCV address. Another usage option is changing of the current DCV method. auth_key - authentication key returned by auth method order_id - unique order ID approver_ in case if DCV method is supposed to be used, provide an approver address in this field. In case if DCV method is already used, you can change current approver address by providing another address in this field. In case of non- DCV method please specified a desired method in this field using one of the following values: 'http', 'https', 'dns'. If no errors in request following parameters will be returned for each of the DCV methods respectively: dcv_method ' ' approver_ Approver address HTTP: [validation] => Array ( [http] => Array ( [link] => [filename] => 851BF1CD669B199EB7C45666FF9784CA.txt [content] => C64D68CACBDFEBCB924B00D008820C0CA800627Acomodoca.com ) HTTPS: [validation] => Array ( [https] => Array ( [link] => [filename] => 851BF1CD669B199EB7C45666FF9784CA.txt [content] => C64D68CACBDFEBCB924B00D008820C0CA800627Acomodoca.com ) DNS: Page - 28

29 [validation] => Array ( [dns] => Array ( [record] => 851BF1CD669B199EB7C45666FF9784CA.example.com. CNAME C64D68CACBDFEBCB924B00D008820C0CA800627A.comodoca.com. ) ) getdomainalternative URL: /tools/domain/alternative/ Request type: POST This API method provides validation information for alternative DCV methods. csr CSR code for which the validation invormation must be provided. In case of successful execution the following information must be returned: [validation] => Array ( [http] => Array ( [link] => [filename] => 851BF1CD669B199EB7C45666FF9784CA.txt [content] => C64D68CACBDFEBCB924B00D008820C0CA800627Acomodoca.com ) [https] => Array ( [link] => [filename] => 851BF1CD669B199EB7C45666FF9784CA.txt [content] => C64D68CACBDFEBCB924B00D008820C0CA800627Acomodoca.com ) [dns] => Array ( [record] => 851BF1CD669B199EB7C45666FF9784CA.example.com. CNAME C64D68CACBDFEBCB924B00D008820C0CA800627A.comodoca.com. ) ) Page - 29