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

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'

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

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

OAuth2passwordRequired

Token URL:

Body

namestringRequired

numberstring · nullableRequired

invoiceEmailstring · nullableRequired

corporateIdentityNumberstringRequired

Responses

200

Success. The customer was created.

No content

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/api/v1/customers

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

{
  "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",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ]
}

No content

Gets a customer by customer number.

get

Authorizations

OAuth2passwordRequired

Token URL:

Path parameters

customerNumberstringRequired

The customer number.

Responses

200

Success. The company was found and returned.

application/json

namestringRequired

numberstring · nullableRequired

invoiceEmailstring · nullableRequired

corporateIdentityNumberstringRequired

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/api/v1/customers/{customerNumber}

GET /api/v1/customers/{customerNumber} HTTP/1.1
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",
  "tags": [
    {
      "key": "text",
      "value": "text"
    }
  ]
}

Returns a paginated list of customers.

get

Authorizations

OAuth2passwordRequired

Token URL:

Query parameters

numberstringOptional

Optional filter by exact customer number.

namestringOptional

Optional filter by name, matches anywhere in the name.

corporateIdentityNumberstringOptional

Optional filter by corporate identity number. Spaces and dashes are ignored when matching.

pageinteger · int32Optional

Page number, starting from 1. Default is 1.

Default: 1

limitinteger · int32Optional

Page size, maximum 100. Default is 50.

Default: 50

Responses

200

application/json

pageinteger · int32Required

limitinteger · int32Required

totalCountinteger · int32Required

400

Bad Request

application/json

500

Internal Server Error

get/api/v1/customers

GET /api/v1/customers HTTP/1.1
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "page": 1,
  "limit": 1,
  "totalCount": 1,
  "customers": [
    {
      "number": "text",
      "name": "text",
      "corporateIdentityNumber": "text"
    }
  ]
}

Places a sales order.

post

Authorizations

OAuth2passwordRequired

Token URL:

Body

customerNumberstring · min: 1Required

The customer number in GKS of the buyer. A company with this customer number must exist in GKS. Required. 1–10 characters.

Example: K100421

orderTitlestring · nullableRequired

Optional name of the sales order that will be useful when searching for the order. Default: "Webshop order". Setting to null restores the default. Max 80 characters.

promisedDeliveryDatestring · date-time · nullableRequired

The promised delivery date.

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". Optional. Max 25 characters.

isExportboolean · nullableRequired

Indicates whether the order is an export outside the seller's country. Affects VAT calculation on the sales order. When true, all orderline Simutek.GksPublic.ApplicationService.DTO.SalesOrderline.VatPercent must be 0. Required to be true when Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu is true. Default: false. When null together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu and all orderline VatPercent, all three are fetched from the customer directory instead.

isExportWithinEuboolean · nullableRequired

Indicates whether the order is an export to another country within the EU. Affects VAT calculation on the sales order. Requires Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport to be true when set to true. Default: false. When null together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport and all orderline VatPercent, all three are fetched from the customer directory instead.

languageCodestring · nullableRequired

The preferred language (ISO 639-1) of documents communicated with the buyer, e.g. order confirmation. Optional. When provided, must be exactly 2 characters and one of: sv (Swedish), en (English), nb (Norwegian Bokmål), no (Norwegian), nn (Norwegian Nynorsk).

currencyCodestring · nullableRequired

The currency shown on quotes, order confirmations and invoices for this sales order (ISO 4217). Optional. When provided, must be exactly 3 uppercase letters (e.g. SEK, EUR). When null, the currency from the customer directory is used. Note: the amounts in the request are always given in the print shop's local currency (e.g. SEK or NOK), independent of this field.

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

orderNumberinteger · int32Required

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/api/v1/salesorders

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

{
  "customerNumber": "K100421",
  "billingContact": {
    "firstName": "text",
    "lastName": "text",
    "email": "text",
    "phone": "text",
    "phoneMobile": "text",
    "eInvoiceCode": "text"
  },
  "billingCompanyInfo": null,
  "billTo": null,
  "shipTo": null,
  "orderTitle": "text",
  "promisedDeliveryDate": "2026-01-01T00:00:00.000Z",
  "ordered": "2026-01-01T00:00:00.000Z",
  "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"
          },
          "shipmentFavoriteCode": "text"
        }
      ]
    }
  ]
}

{
  "orderNumber": 1
}

PreviousSwitch

NextDatavalidering och format

Last updated 4 months ago