Child pages
  • UAPI Functions - Market::request_ssl_certificates
Skip to end of metadata
Go to start of metadata

Description

This function submits a request for a certificate order to the cPanel Market provider.

Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/Market/request_ssl_certificates?access_token=725431a1-d5bc-11e5-a28b-8b0e09a93f05&certificate%3D%7B%22product_id%22%3A143%2C%22subject_names%22%3A%5B%5B%22dNSName%22%2C%22example.com%22%5D%2C%5B%22dNSName%22%2C%22example.org%22%5D%5D%2C%22vhost_names%22%3A%5B%22example.com%22%5D%2C%22price%22%3A6%2C%22validity_period%22%3A%5B1%2C%22year%22%5D%7D%26certificate%3D%7B%22product_id%22%3A%22176%22%2C%22subject_names%22%3A%5B%5B%22dNSName%22%2C%22test.example.com%22%5D%5D%2C%22vhost_names%22%3A%5B%22test.example.com%22%5D%2C%22price%22%3A3%2C%22validity_period%22%3A%5B1%2C%22year%22%5D%7D%26provider%3DcPStore


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Submit certificate orders to the cPanel Market provider.
$submit_order = $cpanel->uapi(
    'Market', 'request_ssl_certificates',
    array(
            'access_token' => '725431a1-d5bc-11e5-a28b-8b0e09a93f05',
            'certificate' => '{"product_id":143,"subject_names":[["dNSName","example.com"],["dNSName","example.org"]],"vhost_names":["example.com","sub.example.com"],"price":6, "validity_period":[1,"year"]}',
            'certificate-0' => '{"product_id":"176","subject_names":[["dNSName","test.example.com"]],"vhost_names":["test.example.com"],"price":3, "validity_period":[1,"year"]}',
            'provider' => 'cPStore'
    )
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
# Submit certificate orders to the cPanel Market provider.
my $submit_order = $cpliveapi->uapi(
    'Market', 'request_ssl_certificates',
    {
       'access_token' => '725431a1-d5bc-11e5-a28b-8b0e09a93f05',
       'certificate' => '{"product_id":143,"subject_names":[["dNSName","example.com"],["dNSName","example.org"]],"vhost_names":["example.com","sub.example.com"],"price":6, "validity_period":[1,"year"]}',
       'certificate-0' => '{"product_id":"176","subject_names":[["dNSName","test.example.com"]],"vhost_names":["test.example.com"],"price":3, "validity_period":[1,"year"]}' 
       'provider' => 'cPStore'
    }
);


Note:

For more information, read our Guide to the LiveAPI System.

 

 cPanel Template Toolkit
<!-- Submit certificate orders to the cPanel Market provider. -->
[% execute('Market', 'request_ssl_certificates', { access_token' => '725431a1-d5bc-11e5-a28b-8b0e09a93f05', certificate => '{product_id:143,price:6,subject_names:[[dNSName,"arp2wqdpts.test"]]}',provider => 'cPStore', validity_period:[1,"year"] } ) %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 

 Command Line
uapi --user=username Market request_ssl_certificates provider=cPStore access_token=725431a1-d5bc-11e5-a28b-8b0e09a93f05 certificate={"product_id":143,"subject_names":[["dNSName","example.com"],["dNSName","example.org"]],"vhost_names":["example.com"],"price":6,"validity_period":[1,"year"]} certificate={"product_id":"176","subject_names":[["dNSName","test.example.com"]],"vhost_names":["test.example.com"],"price":3.5,"validity_period":[1,"year"]}&provider=cPStore


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 
  • If you run CloudLinux™, you must use the full path of the uapi command:

    /usr/local/cpanel/bin/uapi


 Output (JSON)
{
   "data":{
      "checkout_url":"http://store.example.com/showmethemoney.cgi",
      "certificates":[
         {
            "key_id":"ac90f_639fd_6c236062f0d7a4579a30e01612c4cee0",
            "order_item_id":"12345"
         },
         {
            "key_id":"ac90f_639fd_6c236062f0d7a4579a30e01612c4cee1",
            "order_item_id":"67890"
         }   
        ],  
       "order_id":"8675309"
     },
  "errors":undef,
  "messages":undef,
  "metadata"{

  },
  "status":1
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
access_tokenstring

Required

The access token for the session to the cPanel Market provider.

A valid access token.

725431a1-d5bc-11e5-a28b-8b0e09a93f05
certificateJSON

Required

A JSON-encoded string that contains the details of the certificate.

Note:

To request multiple certificates, duplicate or increment the parameter name. For example, to request three certificates, use the certificate parameter multiple times or use the certificate-1, certificate-2, and certificate-3 parameters.

A JSON-encoded string that contains the product_id and price parameters, the subject_names and vhost_names and validity_period arrays. It may also contain the subject array.
 Click to view...
{
  "product_id":143,
  "subject_names":[
    [
      "dNSName",
      "example.com"
    ],
    [
      "dNSName",
      "example.org"
    ]
  ],
  "vhost_names":[
    "example.com"
  ],
  "price":6,
  "validity_period":[
    1,
    "year"
  ]
}

product_id

string

Required

The product's ID.

The certificate string contains this parameter.

A valid string.143

price

string

Required

The price of the certificate.

The certificate string contains this parameter.

A valid string that represents the price in US dollars.6

subject_names

array of arrays

or

array of hashes

Required

An array that contains arrays or hashes that indicate subject names in the certificate.

The certificate string contains this array.

An array of arrays or hashes of subject names.

Note:

We added support for the array of hashes in cPanel & WHM version 74.

HTTP-based DCV only :

 Click to view...
"subject_names":[
  [
    "dNSName",
    "example.com"
  ],
  [
    "dNSName",
    "example.org"
  ]
]

DNS-based DCV or HTTP-based DCV:

 Click to view...
"subject_names":[
  { 
    type:“dNSName”,
    name:“text.example.com”,
    dcv_method:“dns” 
  },
  { 
    type:“dNSName”,
    name:“text.example.com”,
    dcv_method:“http” 
  }
]

Where dcv_method equals dns or http for DNS-based or HTTP-based Domain Control Validation (DCV).

Note:

Custom provider modules that include DNS-based DCV requests must use the array of hashes format, not the array of arrays.

 array

Required

An unnamed array that contains a name type and a name.

The subject_names array contains this array or hash.

Notes:

  • As of cPanel & WHM version 60, this function no longer automatically includes the corresponding www. subdomain for each domain that you declare in this parameter.
  • If you wish to order the www. subdomain for a domain, you must explicitly declare it in an additional array or hash within the subject_names parameter.

Two elements that consist of dNSName and a string.

"dNSName","5wq5eymnv7.test"

validity_period

array

Required

For what period of time the certificate will remain valid.

The certificate string contains this parameter.

A two-element array that consists of a number and string which represents a unit of time.[1,"year"]

vhost_names

array

Required

A list of names of web virtual hosts (vhosts) for which the system will install the certificate.

The certificate string contains this parameter.

A comma-separated list of web vhosts.

Note:

An asterisk character (*) represents every web virtual host with which the certificate is compatible.

"example.com","sub.example.com"

"*"

providerstring

Required

The cPanel Market provider's name.

A valid string.cPStore
url_after_checkoutstringThe URL to send the browser after the user checks out.A valid URL that does not contain a query string.http://checkout.example.com
identity_verificationhash

A hash that contains the required information for an EV or OV certificate.

Notes:

  • We introduced this return in cPanel & WHM version 62.
  • The function returns this hash for OV or EV certificate requests.

This information depends on the provider of the certificate.

 Click to view...

This following example represents an OV certificate from cPanel Store. A different product may contain different information.

{
    "organizationName": "Company, Inc.",
    "organizationalUnitName": "Team Company",
    "duns_number": "12-345-6789",
    "streetAddress": "555 Street Name",
    "localityName": "City Name",
    "stateOrProvinceName": "ST",
    "postalCode": "55555",
    "countryName": "US",
    "rep_forename": "First Name",
    "rep_surname": "Last Name",
    "rep_email_address": "username@domain.com",
    "rep_telephone": "123-456-7891"
}

Returns

ReturnTypeDescriptionPossible valuesExample

order_id

integer

The order ID that the cPanel Market provider assigned.

A positive integer.123456
checkout_urlstringThe URL that the cPanel Market provider uses to process payment.A valid publicly-available URL.http://store.example.com/showmethemoney.cgi

certificates

hashInformation about each certificate in the order.This hash includes the key_id and order_item_id returns.

key_id

stringThe private key's ID. 

The function returns this value in the certificates hash.

A valid key ID.
 Click to view...
ac90f_639fd_6c236062f0d7a4579a30e01612c4cee0

order_item_id

integer

The ID of the ordered item.

The function returns this value in the certificates hash.

A positive integer.
12345