ProCarrier Returns Retailer API (1.1)

The following API is designed to provide a complete set of tools to integrate with the system.

Requests are using application/json format.

Responses are in JSON.

Request method should always be POST.

The maximum length of each text field is 255 symbols (except in a few places).

Should be UTF-8.

Timezone of our server is UTC

Each API request requires apiKey key in the POST request body. API key can be found on the profile page. To access a profile page, you must be logged in to your account panel.

{
    "error": {
        "code": "accessDenied",
        "message": [
            "Access denied"
        ]
    }
}

You can get full list of services available to you by get available services endpoint

Please note, that a carrier service availability is determined by geographical coverage and your account settings.

Tracking status codes

Create order method

<?php

$apiKey = 'demoApiKey';
$order = getOrder();

$apiBaseUrl = getApiEndpoint('PRODUCTION');
$apiMethod = 'orders/create';
$requestFormat = 'json';
$apiEndpoint = buildApiEndpoint($apiBaseUrl, $apiMethod, $requestFormat);

$requestData = [
    'ApiKey' => $apiKey,
    'Request' => json_encode(['Order' => $order]),
];
try {
    $apiResponse = makeCurlPostRequest($apiEndpoint, $requestData);
} catch (Exception $exception) {
    die('cURL exception occurred. Details: ' . $exception->getMessage() . ' Error code: ' . $exception->getCode());
}

handleCreateOrderResponse($apiResponse);

/* METHOD DEFINITIONS BELOW */

function handleCreateOrderResponse($apiResponse)
{
    $response = json_decode($apiResponse, true);
    if (null === $response || false === $response) {
        die('The response is not a JSON format. Original response: ' . $apiResponse);
    }

    if (!empty($response['success'])) {
        $orderId = $response['success']['orderId'];
        die('Order successfully created! Order ID: ' . $orderId);
    }

    if (!empty($response['error'])) {
        // Order was not created.
        $errorCode = $response['error']['code'];
        $messages = $response['error']['message'];
        die('Error code: ' . $errorCode . '. Messages: ' . implode("\r\n", $messages));
    }

    die('Unknown response format.');
}

function makeCurlPostRequest($apiEndpoint, $requestData)
{
    $payload = json_encode($requestData);
    $ch = curl_init($apiEndpoint);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $result = curl_exec($ch);
    if ($result === false) {
        // cURL error
        throw new \RuntimeException(curl_error($ch), curl_errno($ch));
    }
    curl_close($ch);

    return $result;
}

function buildApiEndpoint($apiBaseUrl, $apiMethod, $format)
{
    return $apiBaseUrl . '/' . $apiMethod . '/' . $format;
}

function getApiEndpoint($environment)
{
    if ($environment === 'SANDBOX') {
        return 'http://staging.returns-dg.xmlshop.dev/api';
    }

    return 'http://returns.dgapi.app/api';
}

function getOrder()
{
    return [
        'OrderReference' => 'REF10000000001',
        'OrderDate' => '10/20/2019',
        'Rma' => '12345',
        'Name' => 'John Smith',
        'Company' => '',
        'AddressLine1' => '6 Semaphore Close Mount Pleasant',
        'AddressLine2' => '',
        'AddressLine3' => 'Christchurch',
        'Zip' => '8081',
        'State' => 'qwe',
        'Country' => 'NZ',
        'Phone' => '+102030405060',
        'Email' => 'john.smith@googlemail.com',
        'Currency' => 'AUD',
        'ExportAwb' => '32153454GB',
        'ExportCarrierName' => 'USPS',
        'Products' => [
            [
                'Sku' => 'QWE123',
                'Description' => 'Black Sculpting & Smoothing Shapewear Body Suit-EUR 38 (M)',
                'Quantity' => '5',
                'Price' => '100',
                'Weight' => '1',
                'Length' => '2',
                'Width' => '3',
                'Height' => '4',
                'DimensionsUom' => 'mm',
                'HsCode' => '',
                'CountryCode' => 'GB',
                'ImgUrl' => '',
            ],
            [
                'Sku' => 'QWE456',
                'Description' => 'Black Halterneck Corset',
                'Quantity' => '10',
                'Price' => '200',
                'Weight' => '0.86',
                'Length' => '0',
                'Width' => '0',
                'Height' => '0',
                'DimensionsUom' => 'mm',
                'HsCode' => '',
                'CountryCode' => 'GB',
                'ImgUrl' => '',
            ],
        ],
    ];
}

Check availability

<?php

$apiKey = 'demoApiKey';

$apiBaseUrl = getApiEndpoint('PRODUCTION');
$apiMethod = 'check/available';
$requestFormat = 'json';
$apiEndpoint = buildApiEndpoint($apiBaseUrl, $apiMethod, $requestFormat);

try {
    $apiResponse = makeCurlPostRequest($apiEndpoint);
} catch (Exception $exception) {
    die('cURL exception occurred. Details: ' . $exception->getMessage() . ' Error code: ' . $exception->getCode());
}

handleCheckAvailableResponse($apiResponse);

function handleCheckAvailableResponse($apiResponse)
{
    $response = json_decode($apiResponse, true);

    if ($response === null) {
        die('The response is not a JSON format. Original response: ' . $apiResponse);
    }

    if (!empty($response['Success'])) {
        if (!empty($response['Success']['Date'])) {
            die('Ok. Service is available.');
        }

        // Check the online documentation here https://localhost/api/
        var_dump($response);
        die('Wrong response format.');
    }

    if (!empty($response['Error'])) {
        // API temporarily unavailable
        $errorCode = $response['Error']['Code'];
        $messages = $response['Error']['Message'];
        die('Error code: ' . $errorCode . '. Messages: ' . implode("\r\n", $messages));
    }

    // Check the online documentation here https://localhost/api/
    var_dump($response);
    die('Unknown response format.');
}

function makeCurlPostRequest($apiEndpoint)
{
    $ch = curl_init($apiEndpoint);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HEADER, true);

    $result = curl_exec($ch);

    if ($result === false) {
        // cURL error
        throw new \RuntimeException(curl_error($ch), curl_errno($ch));
    }

    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new \RuntimeException('API temporarily unavailable.', $httpCode);
    }

    return $result;
}

function buildApiEndpoint($apiBaseUrl, $apiMethod, $format)
{
    return $apiBaseUrl . '/' . $apiMethod . '/' . $format;
}

function getApiEndpoint($environment)
{
    if ($environment === 'SANDBOX') {
        return 'http://staging.returns-dg.xmlshop.dev/api';
    }

    return 'http://returns.dgapi.app/api';
}

This part of API describes requests that your server should accept and responses that your server should return to implement webhooks support. You can configure the urls for each type of webhook in admin panel.

Each request will contain header X-Hmac-Sha256-Signature with HMAC-SHA256 signature of the request body.

Your API key will be used as a secret.