Stidner Partner API

Setup

To start working with Stidner Partner API, you need to obtain partner credentials. If your partner account is authorised to work with API, you will be able to get the credentials on settings page at partner dashboard partner.stidner.com.

If you are not authorised to work with API, please, contact us, and we will figure out the best way, that meets your needs.

Environment

Stidner Partner API has one environment and two modes - live and sandbox. The mode the request is being performed in depends on the key (live/sandbox) you are using to authenticate request.

Url: https://shipping-api.stidner.com

Authentication

All endpoints in Stidner Partner API require authentication. Credentials consist of partner handle and API Key: sandbox key starts with sp_sandbox_ prefix, live key starts with sp_live_ prefix.

The above credentials should be used to sign requests to every endpoint, provided as Basic HTTP-auth login and password.

Example of authenticated request:

curl -X POST \
https://shipping-api.stidner.com/api/v1/order \
-H 'authorization: Basic MTo4YWI4MmM1MC01ZDdiLTExZTctYjJlNS0zNzhhODI1MWUxMzg=' \
-d '{ … }'

Sandbox mode

To make Sandbox mode requests, you need to specify test API Key instead of live one when making requests.

As a result all the merchants, that you create in Sandbox mode will be the part of our Sandbox environment and will not be accessable in live mode (for the requests with live API key).

Endpoints

Merchant signup

POST /api/v1/partner/merchant

Signs up new Merchant in connection to authenticated Partner. Returned is Merchant object with credentials, that can be used in communicating with Stidner Shipping API.

Main JSON object

Attribute	Type		Description
identifier	string	R	Merchant's identity number - organisation number for business customer or social security number for individual customer. Should have the format of 10 or 12 digits with valid checksum.
contact_info	array	O	ContactInfo JSON object. This contact information will be used for shipment - displayed on the labels, included in EDIs and API requests to carriers. It is optional on signup, you will be able to add/update it any time using Partner API or Shipping API. This contact information will be applied to every Address object, that Merchant has. Currently we don't support having different contact information on different Addresses.
addresses	array	O	Array of Address JSON objects. You can provide sender and return addresses in case if they differ from the oficially registered address of Merchant. The addresses are optional, you will be able to add/update/remove them any time using Partner API or Shipping API.

ContactInfo object

Attribute	Type		Description
name	string	O	Name of contact person. Used for communications with carrier. We don't recommend to specify company legal name here - use person's name instead. It will make the pickup/return process for carrier a lot easier.
email	email	O	Email for notifications from carriers regarding shipments.
phone	string	O	Phone for notifications from carriers regarding shipments. Despite that it is optional on signup, a lot of carriers actually require it, and some of the carriers require, that the phone should be strictly mobile. We recommend to always set up the valid mobile phone number of contact person here.

Merchant address object

Attribute	Type
country_code	string	R
postal_code	string	R
city	string	R
address_line	string	R
address_line_2	string	O

Important notes:

The key field of Merchant signup request is identifier because we consider identifier as always unique in our system.
If you are making the signup request with the identifier, that is already present in our system, we will not signup new Merchant, but return the existing Merchant with the provided identifier instead.
In the above case the information of the existing Merchant will not be updated with the data from request. To avoid collisions we allow Merchant information update only on direct request to Merchant update endpoint.
Since response object is the same in both of the cases (new Merchant is created or existing Merchant is returned), you can distinguish, if it was created or returned by HTTP status-code in response: 201 - created, 200 - existing returned.

Example request

{
  "identifier": "333333333333",
  "contact_info": {
    "name": "Anton Vorozheev",
    "email": "anton@stidner.com",
    "phone": "+79119590589"
  },
  "addresses": [
    {
      "type": "sender",
      "country_code": "SE",
      "postal_code": "191023",
      "city": "St. Petersburg",
      "address_line": "Fontanka 77, 25",
      "address_line_2": null
    },
    {
      "type": "return",
      "country_code": "SE",
      "postal_code": "191023",
      "city": "St. Petersburg",
      "address_line": "Fontanka 77, 25",
      "address_line_2": null
    }
  ]
}

Example response

{
  "data": {
    "id": 1,
    "name": "Stidner Complete AB",
    "type": "AB",
    "organisation_number": "333333333333",
    "vat_number": "SE333333333333",
    "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
    "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
    "active": true,
    "addresses": [
      {
        "customer_type": "business",
        "type": "sender",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      },
      {
        "customer_type": "business",
        "type": "return",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      }
    ],
    "created_at": "2017-06-30 10:04:44"
  }
}

Merchant get

GET /api/v1/partner/merchant/{merchant_id}

Gets information about Merchant with specified id. Error is returned when Merchant with specified id is not found or does not belong to the authenticated Partner.

Example response

{
  "data": {
    "id": 1,
    "name": "Stidner Complete AB",
    "type": "AB",
    "organisation_number": "333333333333",
    "vat_number": "SE333333333333",
    "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
    "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
    "active": true,
    "addresses": [
      {
        "customer_type": "business",
        "type": "sender",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      },
      {
        "customer_type": "business",
        "type": "return",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      }
    ],
    "created_at": "2017-06-30 10:04:44"
  }
}

Merchant update

PUT /api/v1/partner/merchant/{merchant_id}

Updates information about Merchant with specified id. Error is returned when Merchant with specified id is not found or does not belong to the authenticated Partner.

Example request

{
  "addresses": [
    {
      "customer_type": "business",
      "type": "sender",
      "name": "Stidner Complete AB",
      "country_code": "BY",
      "postal_code": "210001",
      "city": "Malmo",
      "address_line": "Fontanka 77, 25",
      "contact_name": "Anton Vorozheev",
      "contact_phone": "+79119590589",
      "contact_email": "mail@stidner.com"
    },
    {
      "customer_type": "business",
      "type": "return",
      "name": "Stidner Complete AB",
      "country_code": "PL",
      "postal_code": "191023",
      "city": "St. Petersburg",
      "address_line": "Fontanka 77, 25",
      "contact_name": "Anton Vorozheev",
      "contact_phone": "+79119590589",
      "contact_email": "mail@stidner.com"
    }
  ]
}

Example response

{
  "data": {
    "id": 1,
    "name": "Stidner Complete AB",
    "type": "AB",
    "organisation_number": "333333333333",
    "vat_number": "SE333333333333",
    "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
    "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
    "active": true,
    "addresses": [
      {
        "customer_type": "business",
        "type": "sender",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      },
      {
        "customer_type": "business",
        "type": "return",
        "name": "Stidner Complete AB",
        "country_code": "SE",
        "postal_code": "191023",
        "city": "St. Petersburg",
        "region": null,
        "address_line": "Fontanka 77, 25",
        "address_line_2": null,
        "contact_name": "Anton Vorozheev",
        "contact_phone": "+79119590589",
        "contact_email": "mail@stidner.com"
      }
    ],
    "created_at": "2017-06-30 10:04:44"
  }
}

Merchants collection

POST /api/v1/partner/merchant/get

Gets paginated list of all Merchants, that belong to authenticated Partner.

Example response

{
  "data": [
    {
      "id": 1,
      "name": "Stidner Complete AB",
      "type": "AB",
      "organisation_number": "333333333333",
      "vat_number": "SE333333333333",
      "api_key_live": "8ab82c50-5d7b-11e7-b2e5-378a8251e138",
      "api_key_sandbox": "ef0v4p1a-239k-29oz-9dbf-51d53ef62466",
      "active": true,
      "addresses": [
        {
          "customer_type": "business",
          "type": "sender",
          "name": "Stidner Complete AB",
          "country_code": "SE",
          "postal_code": "191023",
          "city": "St. Petersburg",
          "region": null,
          "address_line": "Fontanka 77, 25",
          "address_line_2": null,
          "contact_name": "Anton Vorozheev",
          "contact_phone": "+79119590589",
          "contact_email": "mail@stidner.com"
        },
        {
          "customer_type": "business",
          "type": "return",
          "name": "Stidner Complete AB",
          "country_code": "SE",
          "postal_code": "191023",
          "city": "St. Petersburg",
          "region": null,
          "address_line": "Fontanka 77, 25",
          "address_line_2": null,
          "contact_name": "Anton Vorozheev",
          "contact_phone": "+79119590589",
          "contact_email": "mail@stidner.com"
        }
      ],
      "created_at": "2017-06-30 10:04:44"
    }
  ],
  "meta": {
    "pagination": {
      "total": 2,
      "count": 1,
      "per_page": 1,
      "current_page": 1,
      "total_pages": 2,
      "links": {
        "next": "https://shipping-api.stidner.com/api/v1/partner/merchant/get?page=2"
      }
    }
  }
}