API

Introduktion

Det här dokumentet beskriver hur du använder vårt REST API för att integrera med vårt system. API ger åtkomst till funktionalitet såsom att skapa försäljningsorder. API:et utvecklas kontinuerligt och fler resurser läggs in.

Autentisering och auktorisering

För att använda API behöver du autentisera dig med en giltig API-nyckel. Autentisering sker genom OAuth 2.0, och varje anrop kräver en Bearer Token i Authorization-huvudet.

Din klient behöver registreras i GKS4 vilket är något Simutek hjälper till med. Därefter får du ett client_id och en client_secret som används för att erhålla en åtkomsttoken.

Exempel på hämtning av åtkomsttoken

curl

Ett exempel hur access token kan hämtas med curl.

curl 'https://id.simutek.se/connect/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'client_id=your_client_id' \
  --data-urlencode 'client_secret=your_client_secret' \
  --data-urlencode 'grant_type=client_credentials'

Python

Ett exempel hur access token kan hämtas med Python 3 och Requests.

get_access_token.py

import requests

def fetch_access_token():
    url = "https://id.simutek.se/connect/token"
    headers = {
        "Content-Type": "application/x-www-form-urlencoded"
    }
    data = {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET",
        "grant_type": "client_credentials"
    }
    
    response = requests.post(url, headers=headers, data=data)

    if response.status_code == 200:
        access_token = response.json().get("access_token")
        print(f"Access Token: {access_token}")
    else:
        print(f"Failed to fetch access token. Status Code: {response.status_code}")
        print(response.text)

if __name__ == "__main__":
    fetch_access_token()

För att köra koden:

pip3 install requests
python3 get_access_token.py

JavaScript (Node.js)

Ett exempel hur access token kan hämtas med JavaScrpt (Node.Js):

const axios = require('axios');
const qs = require('qs'); // For URL-encoded data

async function fetchAccessToken() {
  const url = 'https://id.simutek.se/connect/token';
  const data = qs.stringify({
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
    grant_type: 'client_credentials'
  });

  try {
    const response = await axios.post(url, data, {
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
      },
    });

    console.log('Access Token:', response.data.access_token);
  } catch (error) {
    console.error('Failed to fetch access token:', error.response ? error.response.data : error.message);
  }
}

fetchAccessToken();

För att köra koden:

npm install axios qs
node fetchAccessToken.js

Headers

Om inte annat angivet kräver varje anrop åtminstone följande headers:

Key	Value	Description
Authorization	Bearer eyJ...	Byt ut värdet eyJ... med din access token.
Content-Type	application/json

Dokumentation

Creates a customer

post

Authorizations

Body

namestringRequired

numberstring | nullableRequired

invoiceEmailstring | nullableRequired

corporateIdentityNumberstringRequired

Responses

200

Success. The customer was created.

400

Bad request. The request is not well-formed or there is a validation error.

application/json

404

Not Found

application/json

500

Server error. An internal server error occured. Please try again later.

post

HTTPcURLJavaScriptPython

POST /api/v1/customers HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245

{
  "name": "text",
  "number": "text",
  "invoiceEmail": "text",
  "postalAddress": {
    "address1": "Storgatan 1",
    "address2": "Garageinfart 2",
    "address3": "text",
    "city": "Stockholm",
    "zipCode": "114 44",
    "state": "FL",
    "countryCode": "SE"
  },
  "corporateIdentityNumber": "text"
}

No content

Gets a customer by customer number.

get

Authorizations

Path parameters

customerNumberstringRequired

The customer number.

Responses

200

Success. The approval status was received.

application/json

400

Bad request. The request is not well-formed or there is a validation error.

application/json

404

Not found. The customer with provided customer number was not found.

application/json

500

Server error. An internal server error occured. Please try again later.

get

HTTPcURLJavaScriptPython

GET /api/v1/customers/{customerNumber} HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "name": "text",
  "number": "text",
  "invoiceEmail": "text",
  "postalAddress": {
    "address1": "Storgatan 1",
    "address2": "Garageinfart 2",
    "address3": "text",
    "city": "Stockholm",
    "zipCode": "114 44",
    "state": "FL",
    "countryCode": "SE"
  },
  "corporateIdentityNumber": "text"
}

Places a sales order.

post

Authorizations

Body

customerNumberstring · min: 1Required

The customer number in GKS of the buyer. A company with this customer number must exist in GKS.

Example: K100421

billingCompanyInfoany of | nullableRequired

nullOptional

or

billToany of | nullableRequired

nullOptional

or

shipToany of | nullableRequired

nullOptional

or

orderTitlestring | nullableRequired

Optional name of the sales order that will be useful when searching for the order.

promisedDeliveryDatestring · date-time | nullableRequired

orderedstring · date-time | nullableRequired

Obsolete. We do not see a business need to change the date of purchase. It should always be the same date as the order request is received.

purchaseOrderNumberstringRequired

An optional purchase order number from the buyer. In PlaceSimpleOrder API, "CustOrderNo".

isExportbooleanRequired

isExportWithinEubooleanRequired

languageCodestring | nullableRequired

The preferred language (ISO 639-1) of documents communicated with the buyer, i.e. order confirmation. Accepted values: sv, no, en

currencyCodestring | nullableRequired

The currency of the amounts in this sales order. ISO 4217.

Example: SEK

noteFromCustomerstring | nullableRequired

A comment added by the customer during placement of the order. Commonly with instructions to the seller.

hasAllotmentsbooleanRead-onlyRequired

Responses

200

Success. The sales order was created.

application/json

400

Bad request. The request is not well-formed or there is a validation error.

application/json

404

Not found. The customer number was not found.

application/json

500

Server error. An internal server error occured. Please try again later.

post

HTTPcURLJavaScriptPython

POST /api/v1/salesorders HTTP/1.1
Host: 
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1009

{
  "customerNumber": "K100421",
  "billingContact": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "phone": "text",
    "phoneMobile": "text",
    "eInvoiceCode": "text"
  },
  "billingCompanyInfo": null,
  "billTo": null,
  "shipTo": null,
  "orderTitle": "text",
  "promisedDeliveryDate": "2025-06-01T00:53:39.312Z",
  "ordered": "2025-06-01T00:53:39.312Z",
  "purchaseOrderNumber": "text",
  "isExport": true,
  "isExportWithinEu": true,
  "languageCode": "text",
  "currencyCode": "SEK",
  "noteFromCustomer": "text",
  "salesOrderlines": [
    {
      "articleNumber": "text",
      "description": "text",
      "quantity": 1,
      "salesUnit": "text",
      "unitPrice": 1,
      "vatPercent": 1,
      "discountPercent": 1,
      "costWork": 1,
      "costMaterial": 1,
      "costSubcontractWork": 1,
      "profitCenterCode": "14",
      "weightPerUnit": 1,
      "shipOrderline": true,
      "allotments": [
        {
          "qtyToShip": 1,
          "shipTo": {
            "recipientName": "text",
            "address": {
              "address1": "Storgatan 1",
              "address2": "Garageinfart 2",
              "address3": "text",
              "city": "Stockholm",
              "zipCode": "114 44",
              "state": "FL",
              "countryCode": "SE"
            },
            "contactName": "text",
            "contactMobilePhone": "text",
            "contactEmail": "text"
          }
        }
      ]
    }
  ]
}

{
  "orderNumber": 1
}