Quickstart

Please read the entire Quickstart before connecting to the API.

This documentation is work in progress but should help you get started. If there are errors, issues or questions, please do not hesitate to contact our support team at: connectorapi@onderdelenlijn.nl

Glossary of terms used.

• SupplierId
  This is your unique customer Id, also known as DebiteurId or CustomerId.
• ActionSupplierId
  This is the SupplierId the operation result is for. This is usually you, but if you are a reseller or service provider this is the SuplierId the operation is done for.
• ExternalId
  This is a (temporary) unique Id (string) defined by you, used to identify new products or objects. This value is a reference you will need to map to the AutonetId we return when a create is completed.
• AutonetId
  This is our Id we use for products and objects. All Update/Delete/other operations done REQUIRE this Id.

ConnectorAPI uses OAuth 2.0 token based authentication.
For security and simplicity we do not use refresh tokens.
When your session expires you will receive a HttpStatusCode 401 (Unauthorized), and you can just re-authenticate again.

To authenticate, send a POST request to /token with the following payload as x-www-form-urlencoded data:

Username:[Email]
Password:[Password]
grant_type:password
                

This will result in the following JSON response:

{
  "access_token": "[tokendata]",
  "token_type": "bearer",
  "expires_in": 1799
}
                

If the authentication fails, you will receive a HttpStatusCode 400 (Bad Request) with the following JSON response:

{
  "error": "invalid_grant"
}
                

If you keep getting this response, please contact us so we can check what the problem is.

If authentication is successfull, you can use the access_token data to execute requests to the other operations.

In the Header of each request, add the following Key/Value pair:

Authorization:Bearer [tokendata]

Please note that Operations marked with the 'SupplierId' header value can also return a HttpStatusCode 401 (Unauthorized) when you are trying to execute commands on a Supplier that is not you, or yours. These 401 will be accompanied by an extra error message to tell you what went wrong.

We advise the use of a tool like Postman to help you set up and test the ConnectorAPI.

Some of our operations are processed in realtime, and some are (partly) put in the processing queue.

A good example of this is the Part operation. It will return instant feedback (Please see the SwaggerUI documentation) if the data you sent is correctly validated. If no issues where encountered, the actual mutation is put in the processing queue. When the data is done processing a callback is sent to the Webhook URL with the result. This data will contain important information about the mutation like your ExternalId, our interal Id and the status.

Please make sure the first thing you do is set the callback URL in the Webhook operations.

The JSON object that is sent:

{
  "SupplierId": Integer,
  "ActionSupplierId": Integer,
  "Action": String,
  "ExternalId": String or Null,
  "AutonetId": Long or Null,
  "PhotoId": Short or Null,
  "Message": String or Null,
  "ProcessingErrors": Null or [
    {
      "FieldName": "string",
      "ErrorMessage": "string"
    }
  ],
  "ProcessingWarnings": Null or [
    {
      "FieldName": "string",
      "WarningMessage": "string"
    }
}
    

• ActionSupplierId
  This is the SupplierId the operation result is for. See the glossary for more information.
• Action
  A string telling you what operation this result is for, for example: PartUpdate, PartDelete, OrderPaymentUpdate, OrderProcessUpdate, PhotoUpdate.
• ExternalId
  This is the ExternalId you gave the object to create. See the glossary for more information.
• AutonetId
  This is the new Id we assigned to your product/object if it is a create. See the glossary for more information.
• Message
  Optional message with the result of the operation.

You are required to respond with a HttpStatusCode 200 (OK) if the data was received. If you respond with anything else, the callback will be repeated (up until 10 retries) until you acknowledge this request.

This callback URL is per Supplier, it doesn't matter from what user account the request is sent.

Some of our operations support optional header values. The types of supported values are mentioned in the SwaggerUI documentation.

Please note we have not enabled running the operations directly from the UI (you will get 401 errors when you try to run them), but you can get all the information you need from the documentation there.

• SupplierId
  This value can be filled if you are a reseller or service provider and are doing operations on other/multiple Suppliers.
  If you are only doing operations for your own business, you can forget about this value and just not set it.
• Language
  Select a different language for the result sets.
  If you are writing software in another language then the default English, you can set this value to get localized values/names.
   
  The currently supported languages are:
  • NL (Dutch)
  • EN (English, default)
  • DE (German)
  • FR (French)
  • ES (Spanish)
  • PL (Polish)
  The number of languages may be expanded in the future.

A product can have a maximum of 35 photos.

To create or update a photo, fill the PhotoId (0-34) and either fill the PhotoUrl or PhotoBase64.
The display order is from 1 to 35.

To delete a photo, fill the PhotoId (0-34) and leave the fields PhotoUrl and PhotoBase64 empty. You can send multiple deletes in one call.

You can also (re)sort the photos by sending the order you want them in to the PhotoDisplayOrder endpoint.
Tip: If you want to keep the sorting but want to promote a photo to the main picture (sorting position 1), just send the single Id of the photo, and the autosorting will do the rest.

With these endpoints you can set your entire shipping cost structure.

You define ShippingCostGroups with costs, and then define what PartId/Country combination belongs to what group.

You can use ShippingCostPartCountryType per PartId to set fallbacks if a PartId/Country has no definition.

If there is no ShippingCostGroup bound to a product, either by not having a ShippingCostPartCountry defined, or not having a fallback from a ShippingCostPartCountryType, the product will still be visible on Onderdelenlijn.nl but it wil not be available for online sale. The customer can ofcourse still get in contact with the seller to negotiate a sale.

When creating a part, you are required to include the 'PartNameId' field.
This is the type of part you are uploading. For a complete list, see the PartNames endpoint.

Each part name has a set of properties you can add for the part type.
You can get a complete list of all properties from the PartProperty endpoint.

Some part properties have the IsUniversal bit set to true, and you can add these to ALL parts. For example (at the time of writing), the following properties are universal:

• 15: Location
• 21: Part number
• 25: Brand of part
• 233: Classification code

Each part property has a validation Regex and a ValueCount describing the allowed format and number of elements it can have.

There are 2 types of documents you can upload to our system:

• Conditions
• Warranty

The Language header value (see header values) is not optional, and should be set for the language you are uploading documents for.

The document has to be Base64 string of a PDF document. You can check/download the documents from your public company information page.