Page Comparison

...

About

KODE stands for Kommunalt Ordresystem for Distribusjon av Eiendomsdata.

Subscribe to our email list to receive updates about our API here.

Authentication

Before you start you need to obtain the following information:

CLIENT_ID="my client id"
CLIENT_SECRET="my client secret"
API_USERNAME="my Infoland API username"
API_PASSWORD="my Infoland API password"

To get this information, please contact support@ambita.com

In order to obtain a token, run the following:

curl -s -H  "Content-Type: application/json" https://beta-api.ambita.com:443/authentication/v2/token -d "
        {
                \"grant_type\": \"password\",
                \"client_id\": \"CLIENT_ID\",
                \"client_secret\": \"CLIENT_SECRET\",
                \"username\": \"API_USERNAME\",
                \"password\": \"API_PASSWORD\"
        }"

Example response:

{
  "access_token": "ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "aj274ajd-t1s8-48sk-v5m1-shf64j9bq25a",
  "scope": [
    "shopping.read",
    "shopping.write",
    "productcatalog.read"
  ]
}

The access_token is valid for 1 hour and should be reused until it expires. When the token expires, the API will return 401 UNAUTHORIZED.

To get a new access_token you can use the refresh token grant_type:

curl -s -H  "Content-Type: application/json" https://beta-api.ambita.com:443/authentication/v2/token -d "
        {
                \"grant_type\": \"refresh_token\",
                \"refresh_token\": \"aj274ajd-t1s8-48sk-v5m1-shf64j9bq25a\"
        }"

The refresh_token is valid for 30 days and should be stored securely and only be used to get new access_token. The refresh token grant_type will also return a new refresh_token, you should replace your existing refresh_token with the new one, the new refresh_token is valid for another 30 days. If the refresh_token expires, you need to authenticate with client, credentials and grant_type password again.

More information about OAuth can be found here: https://www.oauth.com/

How to integrate

...

How to integrate

You want to start with setting up the authentication, go to the Authentication page.

Then you want to find the product you want to order, this is done by looking up the product list for a given municipality, see Get productsProducts. You can also contact support if you are unsure about what product to order, support@ambita.com.Then make sure you are handling push notifications correctly, see Push messages

You also want to know the price of the product you want to order and in most cases the price will be available on the product, but in the case of ordering a product with custom order data like a map product the price can differ based on the order data, so you should get the price as described in Prices.

Next you want to create an order, this is described in Create an orderOrders.

Then make sure you are handling push notifications correctly, see Push Messages.

When you have created the order, you should then wait for push messages. We recommend to put push messages on a queue and process them sequentially. What to do with the different statuses is described in the Push messagesMessages, but for UPDATE and FINISHED, there is a small difference to what should be done.

...

1. Use the orderId and get the order from our API described in Get orderin Orders

2. Loop through assets and do necessary actionsFiles , files can occur on both order level and order line level.

   Example (provided in JavaScript):

   Code Block
   language js
   fetch('https://beta-api.ambita.com/infoland-hubkode/v1/orders/:orderId') .then(response => { response.orders.forEach(order => { if (order.assets.length > 0) { // loop through order assets and do necessary actions } order.orderLines.forEach(orderLine => { if (orderLine.assets.length > 0) { // loop through order line assets and do necessary actions } }); }); });

3. Delete or save the file

   Response from https://beta-api.ambita.com/infoland-hubkode/v1/orders/:orderId:

   Code Block
   language json
   { "id": 1234567, "status": "PROGRESS", ... "orders": [ { "id": 1234567, "supplierName": "Infoland Kommune - demo", "assets": [ ... ], ... "orderLines": [ { "id": 12345678, "assets": [ ... ]

   Take a look at the Get delivered files sectionDelivered Files section, the id of the asset will be unique and should be stored in your system. Use this id as a reference to check if you have downloaded the asset before, this way you won’t end up with duplicates. You should also check the status of the asset and delete the file if it has status DELETED.

Create an order

To create an order, you need to use the access_token that you previously obtained.

Take a look at our Swagger documentation for the API here: Swagger

Send a POST request to https://beta-api.ambita.com/infoland-hub/v1/orders/cadastre

Example request:

curl -s \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
      https://beta-api.ambita.com/infoland-hub/v1/orders/cadastre -d "
        {
                \"address\": \"Infoveien 1, 9999 Infoland\",
                \"cadastre\": \"9999-1-1-0-0\",
                \"products\": [
                  {
                    \"code\": \"WI99990033\"
                  }
                ],
                \"reference\": \"some-reference\",
                \"technicalReference\": \"some-technical-reference\"
        }"

JSON body:

• Optional

products:

Example response

Get products

To get products, you need to use the access_token that you previously obtained.

Send a GET request to https://beta-api.ambita.com/infoland-hub/v1/products?municipality={municipalityCode}

Take a look at our Swagger documentation for the API here: Swagger

Example request:

curl -s \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
      https://beta-api.ambita.com/infoland-hub/v1/products?municipality=9999

Example response

Get order

To get an order, you need to use the access_token that you previously obtained.

Send a GET request to https://beta-api.ambita.com/infoland-hub/v1/orders/1234567

Take a look at our Swagger documentation for the API here: Swagger

Example request:

curl -s \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer ej577asf-a5k6-42yq-a3a2-fh03hb8cb58c" \
      https://beta-api.ambita.com/infoland-hub/v1/orders/1234567

Example response

Push messages

In order for us to notify your system about events on an order, you need to provide a callback URL, send this to support@ambita.com

When there is an event on an order, a push message is sent to your callback URL.

These are the statuses that can be pushed to your system:

Example request body

Get delivered files

Here you can find information about assets in our API

Asset object:

{
  "name": "The-exact-name-of-the-file.pdf",
  "filename": "More-descriptive-name-of-the-file.pdf",
  "downloadUrl": "https://beta-api.ambita.com/shopping/v2/assets/d2f48dk9d267a86d2858244d0c2c1937",
  "assetStatus": "OK",
  "productCategory": "PRODUCT_UTEN_KATEGORI",
  "id": "d2f48dk9d267a86d2858244d0c2c1937"
}

Asset status

Product categories

Available product categories:

File types

Most of the files are PDFs, but we also deliver other file types, these are the most common types:

...

.pdf

...

.txt

...

.xlsx, .xls, .csv

...

.jpg, .png

...

.sos, .kof, .dxf, .dvg, .sketchup

...

Distributor Messages

You should implement handling of these messages, see Distributor Messages for more info.