fbpx

1concepts-API

01 1concepts RESTful API

Our API allows you to update the current product-portfolio, place orders and receive tracking-information.

The URL of your API is https://api.1concepts.de/v2/. If you open the URL in your browser, you will be able to look at the swagger-documentation which included a basic description of all endpoints and their models.

02 TL;DR
  • All requests are authorized through JSON Web Token that can be generated by posting your personal credentials to the endpoint api/create-token
  • The Content-type for all requests/responses is application/ld+json
  • Responses will be paginated if the result is too long. The fields in the section hydra:view contain all information you may need for parsing
    paginated responses
  • Requests on the endpoint api/products will return all relevant information for each product, including:
    • Category-reference-links (so products can be sorted into their categories by doing a request on api/categories)
    • Prices
    • Boolean-Fields to restrict country-specific assortments:
      • isBulkCarrier items are only allowed for German clients
      • isEuPlug won’t work in UK/ROI
      • isSchukoPlug won’t work in UK/ROI & Switzerland
  • Translations
  • Shipping-Costs are country-specific and can be accessed through the endpoint api/shippings
  • Orders have to be posted with at least the following values:
    • Your personal partner-id in the field partner
    • Your order number in the field externalOrderNumber
    • The sku for each product
    • netCost for each product
    • Minimal address-information
  • Tracking will be available by either the endpoint api/trackings or by checking the linked list trackings in the order-model
03 POST Authentication

To authorize API-requests, a token needs to be provided in the header. The token can be created by a POST-request to the endpoint /api/create-token where the credentials need to be passed like so:

{
    "email": "henning.wilhelm@1concepts.de",
    "password": "XXXXX"
}

The response will look like this:

{
  "token": "eyJ0eXAiOiJKV1QiL...",
  "id": 17,
  "name": "1CH",
  "email": "henning.wilhelm@1concepts.de"
}

The value of token then needs to be inserted into a JSON-payload like this:

{
    "Authorization": "Bearer eyJ0eXAiOiJKV1QiL...",
    "Content-type": "application/ld+json"
}
04 GET Products

The response of the endpoint api/products will always list our latest portfolio. This means that old items (those who are in your database but not in the response anymore) have to be removed from your assortment while new ones (those who are in the response but not in your database yet) can and should be added.

Please keep in mind that sometimes texts, prices and other values may have changed. This means that you may want to check all items, even if there aren’t new ones.

Besides the “usual” information there will be the following fields:

  • isBulkCarrier items are only available in Germany because the items will be shipped by Bulk carrier
  • isEuPlug indicates products that are used with a standard “two pin plug” thus they can’t be used in UK/ROI
  • isSchukoPlug indicates products that are used with the EU “SCHUKO-Plug” thus they can’t be used in UK/ROI & Switzerland
05 GET Categories

To sort products into a “ready to go” category-tree the endpoint api/categories returns a category-tree.

06 GET Shipping-Costs

Shipping costs are country-specific. This means that each country will have its own unique shipping- & handling-costs.

A list of all costs can be retrieved through the endpoint api/shippings.

07 POST/GET Orders

To place an order, it needs to be linked to your account. This can be achieved by adding the field partner with the value api/partners/XX where XX represents the id of your API-account. The id will be included in the response of create-token.
Since the id is static and will never change, the field partner can be “hard-coded” to increase the performance the order-post.

Besides the partner-id and the usual address-material there are two additional values that are mandatory for the order:

  • The sku is necessary to identify the ordered item on our end
  • The netCost is important because we need to import the order the price, we calculated for you. If you do not include the net-costs that are
    provided by the endpoint api/products we will charge the default price that is always higher than your “custom price

The returned response will show the posted order with two newly created fields:

  • The list trackings will contain links to tracking-resources
  • The boolean-field isExported will indicate whether an order has been exported into our processing-system
    • New orders will be exported twice a day (9 a.m. and 3 p.m. German time) after which the value of isExported will change from false to true
08 GET Trackings

Tracking information will always be uploaded at 6 p.m. German time. You can access tracking-information in two ways:

  1. Doing a GET-request on the endpoint api/trackings allows you to query by params like createdAt or order.externalOrderNumber
    • The returned trackings-list will include tracking-resources (if available) as a list
  2. Doing a GET-request on the endpoint api/orders allows you to query by externalOrderNumber (please note the missing order.)
    • The returned order will include links to trackings (if available) as a list

If tracking isn’t available, an empty list will be returned.

Besides the tracking-id and the shipment-date the response will also include the courier the parcel is shipped with. This allows you to create “clickable” tracking-URLs.

If an item is shipped by Bulk carrier the courier will be Bulk carrier while the tracking-id will only contain a single underscore _.

09 Best-Practices

The following paragraphs will show some advises on how to handle different situations (this section may change/grow).

Portfolio-Update

One approach to update the current assortment could look like this:

  1. Check for old items by subtracting a list of all SKUs of the API from the current online SKUs
    1. Currently online SKUs: [123, 456, 789]
    2. API-SKUs: [123, 789]
      1. Subtraction: [123, 456, 789][123, 789] = [456]
      2. Therefore SKU 456 is EOL and needs to be taken offline
  2. Checking for new items is basically reversing the subtraction from point 1:
    1. API-SKUs: [987, 654, 321]
    2. Currently online SKUs: [654]
      1. Subtraction: [987, 654, 321][654] = [987, 321]
      2. Therefore SKUs 987 and 321 are new and should be taken online

Status

If your system allows you to display the status of an order, our API can be interpreted to show three status (the status-names are just examples):

  • After an order has been placed the status will be “pending” as long as isExported is set to false
  • If the order has been exported and the value of isExported changed from false to true the status changed from “pending” to “in process
  • After a tracking-id has been added to an order the status changes from “in process” to “shipped

Please note that from our point of view an order is “completed” after we posted a tracking-id. Thus there won’t be any status-changes after we created a tracking-resource for an order.

10 Python codesnippets

The following snippets will show a rudementary way to access the different endpoints. All code-sampels are rudemantary examples and neither optimized in terms of performance nor very Pythonic. In fact, the samples are meant to be as readable as possible which is why above properties may have been neglegted.

The external module requests will be used to do code against the API which is not part of the standard library. More information about the module can be found here: http://2.python-requests.org/en/master

Creating authorization-header

import requests

URL = "https://api.1concepts.de/v2"


def get_auth_token():
    """Creates an auth-token

    Returns:
        Auth-dict that can be used for the "headers"-parameter of requests-calls
    """

    payload = {
        "email": "your_email_address",
        "password": "your_password"
    }

    response = requests.post(f"{URL}/api/create-token", json=payload).json()

    token = response["token"]
    
    auth_payload = {
        "Authorization": f"Bearer {token}",
        "Content-type": "application/ld+json"
    }

    return auth_payload

Retrieve Products, Categories or Shipping

The script below shows how to retrieve the latest products. To get the category-tree or shipping-list, just change the parameter in the requests.get() function

import requests

URL = "https://api.1concepts.de/v2"

def get_products():
    """Retrieves a list of all available products
    
    Returns:
        (Paginated) list of dicts, containing the current portfolio
    """

    token = get_auth_token()
    
    response = requests.get(f"{URL}/api/products", headers=token).json()

    return response

Post Orders

The id for „partner“: „api/partners/XX“ can be looked up by checking the response from api/create-token

import requests

URL = "https://api.1concepts.de/v2"

def post_order():
    """Posts an order to the API

    Returns:
        Details of placed order
    """

    order = {
        "partner": "api/partners/17", # hard-coded it to link the order to API-account
        "externalOrderNumber": "ABC::123",
        "externalUserNumber": "TestUser_001",
        "externalProgrammeNumber": "TestProgramme",
        "externalCampaignCode": "Summer Sale '19",
        "externalCatalogueCode": "S_2019",
        "externalCatalogueName": "Summer 2019",
        "recipientCompany": "Example Ltd.",
        "recipientName": "Doe",
        "recipientFirstName": "Jane",
        "recipientStreet": "Some street 1",
        "recipientHouseNumber": "",
        "recipientAnnex": "3rd floor",
        "recipientZip": "12345",
        "recipientCity": "Hometown",
        "recipientCountry": "Germany",
        "recipientEmail": "jane.doe@example.de",
        "recipientPhone": "+49 1234 5678 90",
        "recipientMobilePhone": "+49 132 456 78 90",
        "items": [
            {
                "sku": 3543,
                "externalItemNumber": "3543_Multicutter",
                "quantity": 3,
                "itemName": "Multicutter",
                "netCost": 40.3
            },
            {
                "sku": 5367,
                "externalItemNumber": "5367_Adenogen",
                "quantity": 1,
                "itemName": "Adenogen",
                "netCost": 20.85
            }
        ]
    }

    token = get_auth_token()
    
    response = requests.post(f"{URL}/api/orders", headers=token, json=order).json()

    return reponse

Retrieve Order

import requests
from authentification import get_auth_token


URL = "https://api.1concepts.de/v2"

def get_order():
    """Retrieves an order-resource
    
    Returns:
        Order-resource (if available)
    """
    token = get_auth_token()

    response = requests.get(f"{URL}/api/orders", headers=token, params={"externalOrderNumber": "ABC::123"}).json()

    return response

Retrieve Tracking(s)

To query by externalOrderNumber instead of a specific date, use the parameter {„order.externalOrderNumber“: „ABC::123“}

import requests

URL = "https://api.1concepts.de/v2"

def get_trackings():
    """Retrieves a list of trackings, created after a specific date
    
    Returns:
        List of trackings
    """
    token = get_auth_token()

    response = requests.get(f"{URL}/api/trackings", headers=token, params={"createdAt[after]": "2019-08-06"}).json()

    return response

Diese Website verwendet Cookies. Durch die Nutzung der Website stimmen Sie der Verwendung von Cookies zu. Weitere Informationen.
Einverstanden