# 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 {% tabs %} {% tab title="curl" %} Ett exempel hur access token kan hämtas med [curl](https://curl.se/). ```bash 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' ``` {% endtab %} {% tab title="Python" %} Ett exempel hur access token kan hämtas med *Python 3* och *Requests*. {% code title="get\_access\_token.py" %} ```python 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() ``` {% endcode %} För att köra koden: ```bash pip3 install requests python3 get_access_token.py ``` {% endtab %} {% tab title="JavaScript (Node.js)" %} Ett exempel hur access token kan hämtas med JavaScrpt (Node.Js): ```javascript 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: ```bash npm install axios qs node fetchAccessToken.js ``` {% endtab %} {% endtabs %} ## 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 ## POST /api/v1/customers > Creates a customer ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"security":[{"oauth2":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"password":{"tokenUrl":"https://id.simutek.se/connect/token","scopes":{"gks-public-api":""}}}}},"schemas":{"CustomerDto":{"required":["corporateIdentityNumber","invoiceEmail","name","number","postalAddress","tags"],"type":"object","properties":{"name":{"type":"string"},"number":{"type":"string","nullable":true},"invoiceEmail":{"type":"string","nullable":true},"postalAddress":{"$ref":"#/components/schemas/Address"},"corporateIdentityNumber":{"type":"string"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagDto"}}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false},"TagDto":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false},"ValidationProblemDetails":{"required":["detail","errors","instance","status","title","type"],"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}},"ProblemDetails":{"required":["$type","detail","instance","status","title","type"],"type":"object","properties":{"$type":{"type":"string"},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"discriminator":{"propertyName":"$type","mapping":{"Microsoft.AspNetCore.Mvc.ProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/ProblemDetails","Microsoft.AspNetCore.Http.HttpValidationProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/HttpValidationProblemDetails"}}},"HttpValidationProblemDetails":{"required":["errors"],"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/customers":{"post":{"tags":["Customers"],"summary":"Creates a customer","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDto"}}}},"responses":{"200":{"description":"Success. The customer was created."},"400":{"description":"Bad request. The request is not well-formed or there is a validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Server error. An internal server error occured. Please try again later."}}}}}} ``` ## GET /api/v1/customers/{customerNumber} > Gets a customer by customer number. ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"security":[{"oauth2":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"password":{"tokenUrl":"https://id.simutek.se/connect/token","scopes":{"gks-public-api":""}}}}},"schemas":{"CustomerDto":{"required":["corporateIdentityNumber","invoiceEmail","name","number","postalAddress","tags"],"type":"object","properties":{"name":{"type":"string"},"number":{"type":"string","nullable":true},"invoiceEmail":{"type":"string","nullable":true},"postalAddress":{"$ref":"#/components/schemas/Address"},"corporateIdentityNumber":{"type":"string"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagDto"}}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false},"TagDto":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false},"ValidationProblemDetails":{"required":["detail","errors","instance","status","title","type"],"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}},"ProblemDetails":{"required":["$type","detail","instance","status","title","type"],"type":"object","properties":{"$type":{"type":"string"},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"discriminator":{"propertyName":"$type","mapping":{"Microsoft.AspNetCore.Mvc.ProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/ProblemDetails","Microsoft.AspNetCore.Http.HttpValidationProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/HttpValidationProblemDetails"}}},"HttpValidationProblemDetails":{"required":["errors"],"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/customers/{customerNumber}":{"get":{"tags":["Customers"],"summary":"Gets a customer by customer number.","parameters":[{"name":"customerNumber","in":"path","description":"The customer number.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success. The company was found and returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDto"}}}},"400":{"description":"Bad request. The request is not well-formed or there is a validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblemDetails"}}}},"404":{"description":"Not found. The customer with provided customer number was not found.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Server error. An internal server error occured. Please try again later."}}}}}} ``` ## GET /api/v1/customers > Returns a paginated list of customers. ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"security":[{"oauth2":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"password":{"tokenUrl":"https://id.simutek.se/connect/token","scopes":{"gks-public-api":""}}}}},"schemas":{"PagedCustomersResponse":{"required":["customers","limit","page","totalCount"],"type":"object","properties":{"page":{"type":"integer","format":"int32"},"limit":{"type":"integer","format":"int32"},"totalCount":{"type":"integer","format":"int32"},"customers":{"type":"array","items":{"$ref":"#/components/schemas/CustomerSummary"}}},"additionalProperties":false},"CustomerSummary":{"required":["corporateIdentityNumber","name","number"],"type":"object","properties":{"number":{"type":"string"},"name":{"type":"string"},"corporateIdentityNumber":{"type":"string","nullable":true}},"additionalProperties":false},"ValidationProblemDetails":{"required":["detail","errors","instance","status","title","type"],"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/v1/customers":{"get":{"tags":["Customers"],"summary":"Returns a paginated list of customers.","parameters":[{"name":"number","in":"query","description":"Optional filter by exact customer number.","schema":{"type":"string"}},{"name":"name","in":"query","description":"Optional filter by name, matches anywhere in the name.","schema":{"type":"string"}},{"name":"corporateIdentityNumber","in":"query","description":"Optional filter by corporate identity number. Spaces and dashes are ignored when matching.","schema":{"type":"string"}},{"name":"page","in":"query","description":"Page number, starting from 1. Default is 1.","schema":{"type":"integer","format":"int32","default":1}},{"name":"limit","in":"query","description":"Page size, maximum 100. Default is 50.","schema":{"type":"integer","format":"int32","default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PagedCustomersResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblemDetails"}}}},"500":{"description":"Internal Server Error"}}}}}} ``` ## POST /api/v1/salesorders > Places a sales order. ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"security":[{"oauth2":[]}],"components":{"securitySchemes":{"oauth2":{"type":"oauth2","flows":{"password":{"tokenUrl":"https://id.simutek.se/connect/token","scopes":{"gks-public-api":""}}}}},"schemas":{"SalesOrder":{"required":["billingCompanyInfo","billingContact","billTo","currencyCode","customerNumber","hasAllotments","isExport","isExportWithinEu","languageCode","noteFromCustomer","ordered","orderTitle","promisedDeliveryDate","purchaseOrderNumber","salesOrderlines","shipTo"],"type":"object","properties":{"customerNumber":{"minLength":1,"type":"string","description":"The customer number in GKS of the buyer.\nA company with this customer number must exist in GKS."},"billingContact":{"$ref":"#/components/schemas/ContactInfo"},"billingCompanyInfo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/CompanyInfo"}],"nullable":true},"billTo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipTo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/Recipient"}],"nullable":true},"orderTitle":{"type":"string","description":"Optional name of the sales order that will be useful when searching for the order.\nDefault: \"Webshop order\".","nullable":true},"promisedDeliveryDate":{"type":"string","format":"date-time","nullable":true},"ordered":{"type":"string","description":"Obsolete. We do not see a business need to change the date of purchase.\nIt should always be the same date as the order request is received.","format":"date-time","nullable":true},"purchaseOrderNumber":{"type":"string","description":"An optional purchase order number from the buyer.\nIn PlaceSimpleOrder API, \"CustOrderNo\"."},"isExport":{"type":"boolean","description":"Indicates whether the order is an export outside the seller's country.\nAffects VAT calculation on the sales order.\nWhen `true`, all orderline VatPercent must be 0.\nDefault: `false`. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu\nand all orderline VatPercent, all three are fetched from the customer directory instead.","nullable":true},"isExportWithinEu":{"type":"boolean","description":"Indicates whether the order is an export to another country within the EU.\nAffects VAT calculation on the sales order.\nRequires Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport to be `true` when set to `true`.\nDefault: `false`. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport\nand all orderline VatPercent, all three are fetched from the customer directory instead.","nullable":true},"languageCode":{"type":"string","description":"The preferred language (ISO 639-1) of documents communicated with the buyer, i.e. order confirmation.\nAccepted values: sv, no, en","nullable":true},"currencyCode":{"type":"string","description":"The currency of the amounts in this sales order.\nISO 4217.","nullable":true},"noteFromCustomer":{"type":"string","description":"A comment added by the customer during placement of the order.\nCommonly with instructions to the seller.","nullable":true},"salesOrderlines":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderline"}},"hasAllotments":{"type":"boolean","readOnly":true}},"additionalProperties":false},"ContactInfo":{"required":["eInvoiceCode","email","firstName","lastName","phone","phoneMobile"],"type":"object","properties":{"firstName":{"type":"string","description":"FirstName and LastName must not exceed 39 characters."},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"phoneMobile":{"type":"string","nullable":true},"eInvoiceCode":{"type":"string","description":"An optional electronic identifier of the contact useful when\nsending electronic invoices.","nullable":true}},"additionalProperties":false},"CompanyInfo":{"required":["department","invoiceEmail","name"],"type":"object","properties":{"name":{"type":"string","description":"The company's name.\nOr `null` to keep the original name from the GKS company directory.\nObsolete in GKS4. Will be removed.","nullable":true},"department":{"type":"string","description":"An optional department from where this sales order where placed.\nOr `null` to keep the original department from the GKS company directory.\nThis is usually shown next to the invoice postal address.\nObsolete in GKS4. Will be removed. Use billing address address1, adress2 or address3 instead.","nullable":true},"invoiceEmail":{"type":"string","description":"The e-mail address where invoices to the company shall be sent.\nOr`null` to keep the original invoice email from the GKS company directory.","nullable":true}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false},"Recipient":{"required":["address","contactEmail","contactMobilePhone","contactName","recipientName"],"type":"object","properties":{"recipientName":{"minLength":1,"type":"string","description":"A company name. Will be placed as the first line of the delivery address."},"address":{"$ref":"#/components/schemas/Address"},"contactName":{"type":"string","description":"A contact person that will collect the delivery.","nullable":true},"contactMobilePhone":{"type":"string","description":"The contact person's mobile phone for SMS delivery notifications.","nullable":true},"contactEmail":{"type":"string","description":"The contact person's email for delivery notifications.","nullable":true}},"additionalProperties":false},"SalesOrderline":{"required":["allotments","articleNumber","costMaterial","costSubcontractWork","costWork","description","discountPercent","profitCenterCode","quantity","salesUnit","shipOrderline","unitPrice","vatPercent","weightPerUnit"],"type":"object","properties":{"articleNumber":{"type":"string","description":"An article number that exists in the article directory of GKS.\n\nGKS3 Compability: Must be 20 characters or fewer.","nullable":true},"description":{"type":"string","description":"The specification text for this sales orderline.\n\nGKS3 Compability: Must be 80 characters or fewer.","nullable":true},"quantity":{"type":"integer","description":"The quantity ordered.\nQuantity must be zero or greater.","format":"int32","nullable":true},"salesUnit":{"type":"string","nullable":true},"unitPrice":{"type":"number","description":"The regular unit price when not given any discount.\nA negative unit price is allowed.\n\nPrecision: Maximum 10 digits in total.\nScale: Maximum 3 decimals.","format":"double","nullable":true},"vatPercent":{"type":"integer","description":"The VAT percentage of the sales orderline.\nAccepted values: 0, 6, 25.\nMust be the same value for all order lines.\nMust be 0 when Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport is `true`.\nDefault: 25. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport\nand Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu, all three are fetched from the customer directory instead.","format":"int32","nullable":true},"discountPercent":{"type":"integer","description":"A discount in percent given for this order line.\nThe provided unit price will be deducted before calculating the total price (after discount) for the row.\nDefault: 0.\n \nGKS3 Compability: Must be the same value for all order lines.","format":"int32","nullable":true},"costWork":{"type":"number","description":"Total work cost for this order line.","format":"double","nullable":true},"costMaterial":{"type":"number","description":"Total material cost for this order line.","format":"double","nullable":true},"costSubcontractWork":{"type":"number","description":"Total subcontract work cost for this order line.","format":"double","nullable":true},"profitCenterCode":{"type":"string","description":"A profit center code.","nullable":true},"weightPerUnit":{"type":"integer","description":"Weight in grams (g) per unit.\nIgnored by GKS3.","format":"int32","nullable":true},"shipOrderline":{"type":"boolean","description":"Determines if this order line should be shipped.\nSet this to `false`, if this order line is just information text\nor a charged service that cannot be shipped.\nDefault: `true`."},"allotments":{"type":"array","items":{"$ref":"#/components/schemas/Allotment"},"description":"List of shipments.\nOmit if using a single shipment address on the sales order."}},"additionalProperties":false},"Allotment":{"required":["qtyToShip","shipTo"],"type":"object","properties":{"qtyToShip":{"type":"integer","format":"int32"},"shipTo":{"$ref":"#/components/schemas/Recipient"}},"additionalProperties":false},"SalesOrderResponse":{"required":["orderNumber"],"type":"object","properties":{"orderNumber":{"type":"integer","format":"int32"}},"additionalProperties":false},"ValidationProblemDetails":{"required":["detail","errors","instance","status","title","type"],"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}},"ProblemDetails":{"required":["$type","detail","instance","status","title","type"],"type":"object","properties":{"$type":{"type":"string"},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"discriminator":{"propertyName":"$type","mapping":{"Microsoft.AspNetCore.Mvc.ProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/ProblemDetails","Microsoft.AspNetCore.Http.HttpValidationProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/HttpValidationProblemDetails"}}},"HttpValidationProblemDetails":{"required":["errors"],"allOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}},"paths":{"/api/v1/salesorders":{"post":{"tags":["SalesOrders"],"summary":"Places a sales order.","requestBody":{"description":"The sales order to create.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrder"}}}},"responses":{"200":{"description":"Success. The sales order was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SalesOrderResponse"}}}},"400":{"description":"Bad request. The request is not well-formed or there is a validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationProblemDetails"}}}},"404":{"description":"Not found. The customer number was not found.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"500":{"description":"Server error. An internal server error occured. Please try again later."}}}}}} ``` ## The TagDto object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"TagDto":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}}}} ``` ## The ValidationProblemDetails object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"ValidationProblemDetails":{"required":["detail","errors","instance","status","title","type"],"type":"object","properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## The ProblemDetails object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"ProblemDetails":{"required":["$type","detail","instance","status","title","type"],"type":"object","properties":{"$type":{"type":"string"},"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{},"discriminator":{"propertyName":"$type","mapping":{"Microsoft.AspNetCore.Mvc.ProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/ProblemDetails","Microsoft.AspNetCore.Http.HttpValidationProblemDetails, Microsoft.AspNetCore.Http.Abstractions":"#/components/schemas/HttpValidationProblemDetails"}}}}}} ``` ## The SalesOrder object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"SalesOrder":{"required":["billingCompanyInfo","billingContact","billTo","currencyCode","customerNumber","hasAllotments","isExport","isExportWithinEu","languageCode","noteFromCustomer","ordered","orderTitle","promisedDeliveryDate","purchaseOrderNumber","salesOrderlines","shipTo"],"type":"object","properties":{"customerNumber":{"minLength":1,"type":"string","description":"The customer number in GKS of the buyer.\nA company with this customer number must exist in GKS."},"billingContact":{"$ref":"#/components/schemas/ContactInfo"},"billingCompanyInfo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/CompanyInfo"}],"nullable":true},"billTo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/Address"}],"nullable":true},"shipTo":{"anyOf":[{"type":"null"},{"$ref":"#/components/schemas/Recipient"}],"nullable":true},"orderTitle":{"type":"string","description":"Optional name of the sales order that will be useful when searching for the order.\nDefault: \"Webshop order\".","nullable":true},"promisedDeliveryDate":{"type":"string","format":"date-time","nullable":true},"ordered":{"type":"string","description":"Obsolete. We do not see a business need to change the date of purchase.\nIt should always be the same date as the order request is received.","format":"date-time","nullable":true},"purchaseOrderNumber":{"type":"string","description":"An optional purchase order number from the buyer.\nIn PlaceSimpleOrder API, \"CustOrderNo\"."},"isExport":{"type":"boolean","description":"Indicates whether the order is an export outside the seller's country.\nAffects VAT calculation on the sales order.\nWhen `true`, all orderline VatPercent must be 0.\nDefault: `false`. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu\nand all orderline VatPercent, all three are fetched from the customer directory instead.","nullable":true},"isExportWithinEu":{"type":"boolean","description":"Indicates whether the order is an export to another country within the EU.\nAffects VAT calculation on the sales order.\nRequires Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport to be `true` when set to `true`.\nDefault: `false`. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport\nand all orderline VatPercent, all three are fetched from the customer directory instead.","nullable":true},"languageCode":{"type":"string","description":"The preferred language (ISO 639-1) of documents communicated with the buyer, i.e. order confirmation.\nAccepted values: sv, no, en","nullable":true},"currencyCode":{"type":"string","description":"The currency of the amounts in this sales order.\nISO 4217.","nullable":true},"noteFromCustomer":{"type":"string","description":"A comment added by the customer during placement of the order.\nCommonly with instructions to the seller.","nullable":true},"salesOrderlines":{"type":"array","items":{"$ref":"#/components/schemas/SalesOrderline"}},"hasAllotments":{"type":"boolean","readOnly":true}},"additionalProperties":false},"ContactInfo":{"required":["eInvoiceCode","email","firstName","lastName","phone","phoneMobile"],"type":"object","properties":{"firstName":{"type":"string","description":"FirstName and LastName must not exceed 39 characters."},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"phoneMobile":{"type":"string","nullable":true},"eInvoiceCode":{"type":"string","description":"An optional electronic identifier of the contact useful when\nsending electronic invoices.","nullable":true}},"additionalProperties":false},"CompanyInfo":{"required":["department","invoiceEmail","name"],"type":"object","properties":{"name":{"type":"string","description":"The company's name.\nOr `null` to keep the original name from the GKS company directory.\nObsolete in GKS4. Will be removed.","nullable":true},"department":{"type":"string","description":"An optional department from where this sales order where placed.\nOr `null` to keep the original department from the GKS company directory.\nThis is usually shown next to the invoice postal address.\nObsolete in GKS4. Will be removed. Use billing address address1, adress2 or address3 instead.","nullable":true},"invoiceEmail":{"type":"string","description":"The e-mail address where invoices to the company shall be sent.\nOr`null` to keep the original invoice email from the GKS company directory.","nullable":true}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false},"Recipient":{"required":["address","contactEmail","contactMobilePhone","contactName","recipientName"],"type":"object","properties":{"recipientName":{"minLength":1,"type":"string","description":"A company name. Will be placed as the first line of the delivery address."},"address":{"$ref":"#/components/schemas/Address"},"contactName":{"type":"string","description":"A contact person that will collect the delivery.","nullable":true},"contactMobilePhone":{"type":"string","description":"The contact person's mobile phone for SMS delivery notifications.","nullable":true},"contactEmail":{"type":"string","description":"The contact person's email for delivery notifications.","nullable":true}},"additionalProperties":false},"SalesOrderline":{"required":["allotments","articleNumber","costMaterial","costSubcontractWork","costWork","description","discountPercent","profitCenterCode","quantity","salesUnit","shipOrderline","unitPrice","vatPercent","weightPerUnit"],"type":"object","properties":{"articleNumber":{"type":"string","description":"An article number that exists in the article directory of GKS.\n\nGKS3 Compability: Must be 20 characters or fewer.","nullable":true},"description":{"type":"string","description":"The specification text for this sales orderline.\n\nGKS3 Compability: Must be 80 characters or fewer.","nullable":true},"quantity":{"type":"integer","description":"The quantity ordered.\nQuantity must be zero or greater.","format":"int32","nullable":true},"salesUnit":{"type":"string","nullable":true},"unitPrice":{"type":"number","description":"The regular unit price when not given any discount.\nA negative unit price is allowed.\n\nPrecision: Maximum 10 digits in total.\nScale: Maximum 3 decimals.","format":"double","nullable":true},"vatPercent":{"type":"integer","description":"The VAT percentage of the sales orderline.\nAccepted values: 0, 6, 25.\nMust be the same value for all order lines.\nMust be 0 when Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport is `true`.\nDefault: 25. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport\nand Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu, all three are fetched from the customer directory instead.","format":"int32","nullable":true},"discountPercent":{"type":"integer","description":"A discount in percent given for this order line.\nThe provided unit price will be deducted before calculating the total price (after discount) for the row.\nDefault: 0.\n \nGKS3 Compability: Must be the same value for all order lines.","format":"int32","nullable":true},"costWork":{"type":"number","description":"Total work cost for this order line.","format":"double","nullable":true},"costMaterial":{"type":"number","description":"Total material cost for this order line.","format":"double","nullable":true},"costSubcontractWork":{"type":"number","description":"Total subcontract work cost for this order line.","format":"double","nullable":true},"profitCenterCode":{"type":"string","description":"A profit center code.","nullable":true},"weightPerUnit":{"type":"integer","description":"Weight in grams (g) per unit.\nIgnored by GKS3.","format":"int32","nullable":true},"shipOrderline":{"type":"boolean","description":"Determines if this order line should be shipped.\nSet this to `false`, if this order line is just information text\nor a charged service that cannot be shipped.\nDefault: `true`."},"allotments":{"type":"array","items":{"$ref":"#/components/schemas/Allotment"},"description":"List of shipments.\nOmit if using a single shipment address on the sales order."}},"additionalProperties":false},"Allotment":{"required":["qtyToShip","shipTo"],"type":"object","properties":{"qtyToShip":{"type":"integer","format":"int32"},"shipTo":{"$ref":"#/components/schemas/Recipient"}},"additionalProperties":false}}}} ``` ## The SalesOrderResponse object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"SalesOrderResponse":{"required":["orderNumber"],"type":"object","properties":{"orderNumber":{"type":"integer","format":"int32"}},"additionalProperties":false}}}} ``` ## The SalesOrderline object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"SalesOrderline":{"required":["allotments","articleNumber","costMaterial","costSubcontractWork","costWork","description","discountPercent","profitCenterCode","quantity","salesUnit","shipOrderline","unitPrice","vatPercent","weightPerUnit"],"type":"object","properties":{"articleNumber":{"type":"string","description":"An article number that exists in the article directory of GKS.\n\nGKS3 Compability: Must be 20 characters or fewer.","nullable":true},"description":{"type":"string","description":"The specification text for this sales orderline.\n\nGKS3 Compability: Must be 80 characters or fewer.","nullable":true},"quantity":{"type":"integer","description":"The quantity ordered.\nQuantity must be zero or greater.","format":"int32","nullable":true},"salesUnit":{"type":"string","nullable":true},"unitPrice":{"type":"number","description":"The regular unit price when not given any discount.\nA negative unit price is allowed.\n\nPrecision: Maximum 10 digits in total.\nScale: Maximum 3 decimals.","format":"double","nullable":true},"vatPercent":{"type":"integer","description":"The VAT percentage of the sales orderline.\nAccepted values: 0, 6, 25.\nMust be the same value for all order lines.\nMust be 0 when Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport is `true`.\nDefault: 25. When `null` together with Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExport\nand Simutek.GksPublic.ApplicationService.DTO.SalesOrder.IsExportWithinEu, all three are fetched from the customer directory instead.","format":"int32","nullable":true},"discountPercent":{"type":"integer","description":"A discount in percent given for this order line.\nThe provided unit price will be deducted before calculating the total price (after discount) for the row.\nDefault: 0.\n \nGKS3 Compability: Must be the same value for all order lines.","format":"int32","nullable":true},"costWork":{"type":"number","description":"Total work cost for this order line.","format":"double","nullable":true},"costMaterial":{"type":"number","description":"Total material cost for this order line.","format":"double","nullable":true},"costSubcontractWork":{"type":"number","description":"Total subcontract work cost for this order line.","format":"double","nullable":true},"profitCenterCode":{"type":"string","description":"A profit center code.","nullable":true},"weightPerUnit":{"type":"integer","description":"Weight in grams (g) per unit.\nIgnored by GKS3.","format":"int32","nullable":true},"shipOrderline":{"type":"boolean","description":"Determines if this order line should be shipped.\nSet this to `false`, if this order line is just information text\nor a charged service that cannot be shipped.\nDefault: `true`."},"allotments":{"type":"array","items":{"$ref":"#/components/schemas/Allotment"},"description":"List of shipments.\nOmit if using a single shipment address on the sales order."}},"additionalProperties":false},"Allotment":{"required":["qtyToShip","shipTo"],"type":"object","properties":{"qtyToShip":{"type":"integer","format":"int32"},"shipTo":{"$ref":"#/components/schemas/Recipient"}},"additionalProperties":false},"Recipient":{"required":["address","contactEmail","contactMobilePhone","contactName","recipientName"],"type":"object","properties":{"recipientName":{"minLength":1,"type":"string","description":"A company name. Will be placed as the first line of the delivery address."},"address":{"$ref":"#/components/schemas/Address"},"contactName":{"type":"string","description":"A contact person that will collect the delivery.","nullable":true},"contactMobilePhone":{"type":"string","description":"The contact person's mobile phone for SMS delivery notifications.","nullable":true},"contactEmail":{"type":"string","description":"The contact person's email for delivery notifications.","nullable":true}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false}}}} ``` ## The Recipient object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"Recipient":{"required":["address","contactEmail","contactMobilePhone","contactName","recipientName"],"type":"object","properties":{"recipientName":{"minLength":1,"type":"string","description":"A company name. Will be placed as the first line of the delivery address."},"address":{"$ref":"#/components/schemas/Address"},"contactName":{"type":"string","description":"A contact person that will collect the delivery.","nullable":true},"contactMobilePhone":{"type":"string","description":"The contact person's mobile phone for SMS delivery notifications.","nullable":true},"contactEmail":{"type":"string","description":"The contact person's email for delivery notifications.","nullable":true}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false}}}} ``` ## The CustomerDto object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"CustomerDto":{"required":["corporateIdentityNumber","invoiceEmail","name","number","postalAddress","tags"],"type":"object","properties":{"name":{"type":"string"},"number":{"type":"string","nullable":true},"invoiceEmail":{"type":"string","nullable":true},"postalAddress":{"$ref":"#/components/schemas/Address"},"corporateIdentityNumber":{"type":"string"},"tags":{"type":"array","items":{"$ref":"#/components/schemas/TagDto"}}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false},"TagDto":{"required":["key","value"],"type":"object","properties":{"key":{"type":"string"},"value":{"type":"string"}},"additionalProperties":false}}}} ``` ## The ContactInfo object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"ContactInfo":{"required":["eInvoiceCode","email","firstName","lastName","phone","phoneMobile"],"type":"object","properties":{"firstName":{"type":"string","description":"FirstName and LastName must not exceed 39 characters."},"lastName":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"phoneMobile":{"type":"string","nullable":true},"eInvoiceCode":{"type":"string","description":"An optional electronic identifier of the contact useful when\nsending electronic invoices.","nullable":true}},"additionalProperties":false}}}} ``` ## The CompanyInfo object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"CompanyInfo":{"required":["department","invoiceEmail","name"],"type":"object","properties":{"name":{"type":"string","description":"The company's name.\nOr `null` to keep the original name from the GKS company directory.\nObsolete in GKS4. Will be removed.","nullable":true},"department":{"type":"string","description":"An optional department from where this sales order where placed.\nOr `null` to keep the original department from the GKS company directory.\nThis is usually shown next to the invoice postal address.\nObsolete in GKS4. Will be removed. Use billing address address1, adress2 or address3 instead.","nullable":true},"invoiceEmail":{"type":"string","description":"The e-mail address where invoices to the company shall be sent.\nOr`null` to keep the original invoice email from the GKS company directory.","nullable":true}},"additionalProperties":false}}}} ``` ## The Address object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false}}}} ``` ## The Allotment object ```json {"openapi":"3.0.4","info":{"title":"GKS Public API","version":"1.0"},"components":{"schemas":{"Allotment":{"required":["qtyToShip","shipTo"],"type":"object","properties":{"qtyToShip":{"type":"integer","format":"int32"},"shipTo":{"$ref":"#/components/schemas/Recipient"}},"additionalProperties":false},"Recipient":{"required":["address","contactEmail","contactMobilePhone","contactName","recipientName"],"type":"object","properties":{"recipientName":{"minLength":1,"type":"string","description":"A company name. Will be placed as the first line of the delivery address."},"address":{"$ref":"#/components/schemas/Address"},"contactName":{"type":"string","description":"A contact person that will collect the delivery.","nullable":true},"contactMobilePhone":{"type":"string","description":"The contact person's mobile phone for SMS delivery notifications.","nullable":true},"contactEmail":{"type":"string","description":"The contact person's email for delivery notifications.","nullable":true}},"additionalProperties":false},"Address":{"required":["address1","address2","address3","city","countryCode","state","zipCode"],"type":"object","properties":{"address1":{"type":"string","description":"The first address line.\nTypically, a street name and house number.","nullable":true},"address2":{"type":"string","description":"The second address line.","nullable":true},"address3":{"type":"string","description":"The third address line.","nullable":true},"city":{"type":"string","description":"The city.","nullable":true},"zipCode":{"type":"string","description":"The postal code.","nullable":true},"state":{"type":"string","description":"The state. For international delivery addresses.","nullable":true},"countryCode":{"type":"string","description":"Country code. A two character ISO3166_1 code of the country.","nullable":true}},"additionalProperties":false}}}} ```