Versions Compared

Old Version 5

changes.mady.by.user Katarzyna Antonsen

Saved on

compared with

New Version 6

changes.mady.by.user Katarzyna Antonsen

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The API provides endpoints which allow to programmatically create and edit shops.

[ Setup ] [ Authentication ] [ Create shop ] [ Update shop ] [ Error handling ]

Setup

Make sure you have the following information at hand before proceeding.

...

Info

  • User must be granted role which allows to use the Shop API

  • For creating a new shop, user must have access to the owner party a shop is being created for

  • For operations on the already existing shop, user must be authorized to access it

Environments / endpoints

Consider using the TEST-endpoint while developing your system. By doing this you ensure that your test-data will not pollute any potential external systems.

Create shop

TEST

Status
colourPurple
titlePOST

https://staging-ws.di.no/ws/json/shop/v-1

PRODUCTION

Status
colourPurple
titlePOST

https://ws.di.no/ws/json/shop/v-1

Authentication

This endpoint requires the user to be authenticated. Refer to the documentation here for more information on how to obtain a valid token to use in your request. 

Making a request

Info

Notes

  • Clients using this API should not fail if new optional fields are added to the API. If a new field is added to the request or response on a later stage, existing clients should handle this in a way such as they just ignore the field.

Request-Headers

key

value example

comment

Authorization

Bearer "SECRET_WS_TOKEN"

See authentication on how to obtain a token

Request Body

Name

Mandatory

Example

Description

ownerPartyKey

(tick)

owner-party-name

Unique owner party identifier in DI database

shop

(tick)

Shop object which will be persisted

customerSystem

(tick)

Data to create a new customer system connected to the new shop

transportSolutionIds

(tick)

[1, 2, 3]

Collection of already existing transport solutions to be connected to the new shop; can’t be empty

Shop

Name

Mandatory

Example

Description

id

⚠️

Must be empty when creating a new shop

organizationNumber

123 456 789

Applicable based on the regional regulations

email

(tick)

email@test.com

address

(tick)

Warehouse’s address

legalName

Company AS

Shop’s legal name

delivererEDI

EDI software used

vatLiable

true

Whether shop is vat liable; will be set to false if not sent

webShopPlatform

Egen

Ecommerce platform

ceo

John Doe

Shop’s CEO

customerManager

John Doe

Shop’s customer manager

contactPersonPhone

58692698

Phone number of a contact person

externalCustomerIds

[{“freightProductId”: 1, “customerNumber”: 1}]

Unique combination of customer number and freight product id

Address

Name

Mandatory

Example

Description

street

Normannsgata

Warehouse’s street name

streetNumber

5

Warehouse’s street number

entrance

A

Warehouse’s entrance name, up to 5 characters

zipCode

1265

Warehouse’s zip code; 4 digits in Norway, 5 digits in Sweden

city

Oslo

Warehouse’s city

countryCode

NO

Warehouse’s country code; valid values: NO, SE, DE, EN, FI, SV

Customer system

Name

Mandatory

Example

Description

name

(tick)

shortName

(tick)

Must be unique; max. 5 characters

customerFacingName

addressCollector

Curl request example
Code Block
curl --location 'https://staging-ws.di.no/ws/json/shop/v-1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data-raw '{
    "ownerPartyKey": "ownerPartyKey",
    "shop": {
        "organizationNumber": "543 123 345",
        "email": "email@email.com",
        "address": {
            "street": "Street gata",
            "streetNumber": 5,
            "zipCode": 55555,
            "city": "The City",
            "countryCode": "NO"
        },
        "legalName": "Legal Name2",
        "shortName": "sn1",
        "delivererEDI": "delivererEDI",
        "vatLiable": false,
        "webShopPlatform": "web shop platform",
        "ceo": "Ceo Ceo",
        "customerManager": "Kristine",
        "externalCustomerIds": [{
            "freightProductId": 1,
            "customerNumber": 3799475
        }]
    },
    "customerSystem": {
        "name": " customer system",
        "shortName": "abcd"
    },
    "transportSolutionsIds": [1]
}'

Response

Returns a newly created shop object. “requiredSetupComplete” field confirms that your shop is ready to be used.

Update shop

TEST

Status
colourYellow
titlePatch

https://staging-ws.di.no/ws/json/shop/v-1/{shopId}

PRODUCTION

Status
colourYellow
titlePatch

https://ws.di.no/ws/json/shop/v-1/{shopId}

Authentication

This endpoint requires the user to be authenticated. Refer to the documentation here for more information on how to obtain a valid token to use in your request. 

Making a request

Info

Notes

  • Clients using this API should not fail if new optional fields are added to the API. If a new field is added to the request or response on a later stage, existing clients should handle this in a way such as they just ignore the field.

Request-Headers

key

value example

comment

Authorization

Bearer "SECRET_WS_TOKEN"

See authentication on how to obtain a token

Request Body

Name

Mandatory

Example

Description

patch

(tick)

Code Block
[
    {
        "op":"replace",
        "path":"/customerHandler",
        "value":"New Customer Handler"
    },
    {
        "op":"add",
        "path":"/customerNumbers/3",
        "value":{
          "shopId":1,
          "customerNumber":"12345",
          "freightProductId":2}
    }
]

JsonPatch object describing changes which are supposed to be made to the shop. Please refer to JsonPatch documentation for further information.

Curl request example
Code Block
curl --location --request PATCH 'https://staging-ws.di.no/ws/json/shop/v-1/1957' \
--header 'OwnerParty-Id: 1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data '[
    {
        "op":"replace",
        "path":"/customerHandler",
        "value":"New Customer Handler"
    },
    {
        "op":"add",
        "path":"/customerNumbers/1",
        "value":{
            "shopId":1,
            "customerNumber":"12345",
            "freightProductId":2
        }
    }
]'

Response

Returns updated shop object.

Error handling

API requests that result in errors will return an appropriate HTTP status code to help you identify the type of error. You can use the table below to understand what each code means. og search online with the HTTP status code. The HTTP error keys used are based on the standard, and therefore available online (Tips to search “HTTP code XXX”)

...

HTTP Status code

Text

Description

400

Client or Validation Error

The request body/query string is not in the correct format.

401

Authentication Failure

Indicates that the Authorization header is either missing or incorrect. You can learn more about the Authorization header here.

403

Access denied

This indicates that the agent whose credentials were used in making this request was not authorized to perform this API call. It could be that you do not have access to the shop or owner party you provided in your request. If you believe this is a mistake, please reach out to your contact so it can be rectified.

404

Not found

The resource (i.e. shop) for provided {identifier} does not exist.

405

Method not allowed

This API request used the wrong HTTP verb/method. For example a PUT request will result in this error.

4xx

Client error

Generally receiving an error code that starts with 4 indicates that the client needs to change something.

500

Unexpected Server Error

Oops! This may indicates an error on our side. Please try again, if the error continues notify your contact person

Error response

In addition to the HTTP status code, most errors will also return a response body that contains more information to help you debug the error. A sample error response is shown below. The format of the error response body is explained after the example.

...