⚠️

To use the address integration, you first need to create Client. More information can be found HERE

The address book is a convenience for users. User can define a list of addresses to which he orders products and then easily use these addresses in the shopping cart. ⚠️️ Delivery addresses are always returned on the order level, so the address book is not a mandatory part of the integration.

Table of contents:

Glossary GET address POST - create address GET address by ID DELETE address GET addresses for synchronization

Glossary

Name	Explanation
`context`	Specifies the location of the event. List of the event context: `APPLICATION`, `BACKOFFICE`, `INTERNAL`, `INTEGRATIONS`
`clientId`	Customer Id. For individual customers there is prefix `ind:`, for business customers there is prefix `org:`
~~`organizationId`~~	~~Means the same as~~ ~~`clientId`~~ ~~but is written without prefix (ind: or org:) -~~ ~~deprecated~~
`externalId`	Address identifier from external system (e.g ERP). ⚠️ externalId can be corelated only when address is added via API. If user adds address form store, then externalId is null.
`addressId` / `id`	Address identifier in internal system (ONe platform). Based on the `addressId` / `id` it is possible to get and delete address (recomended for integration communication)
`city`	City of address
`country`	Country of address
`name`	Name of address
`phone`	Phone of address
`street`	Street of address
`zipCode`	Zip code of address
`type`	Type means whether the address is a billing address. The billing address can be only one, the rest are treated as ADDITIONAL addresses.

GET address

In this endpoint you can use GET /api/v1/account/integrations/auth-required/addresses to receive information about specific whole address. The diagram below shows the dependence of communicating with the API:

Use the following parameter to find the address you are looking for:

rows - number of the result rows (query)

start - first index of the result rows (query)

Example request:

json
curl -X GET "https://onecommerce.shop/api/v1/account/integrations/auth-required/addresses?rows=1&start=1" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response, you will receive information about the address as along details.

Example response:

json
{
  "listElement": [
    {
      "id": "2fb4cce2-3ff4-4d24-9e82-ad2df4fef6b0",
      "externalId": null,
      "organizationId": "c2cc8513-dc95-4031-825d-73c339ac89b5",
      "clientId": "ind:c2cc8513-dc95-4031-825d-73c339ac89b5",
      "name": "Name Surname",
      "street": "Strzegomska 2-4",
      "zipCode": "53-611",
      "city": "Wroclaw",
      "country": "PL",
      "phone": "730031138",
      "type": "BILLING"
    }
  ],
  "totalElement": 45,
  "items": [
    {
      "id": "2fb4cce2-3ff4-4d24-9e82-ad2df4fef6b0",
      "externalId": null,
      "organizationId": "c2cc8513-dc95-4031-825d-73c339ac89b5",
      "clientId": "ind:c2cc8513-dc95-4031-825d-73c339ac89b5",
      "name": "Name Surname",
      "street": "Strzegomska 2-4",
      "zipCode": "53-611",
      "city": "Wroclaw",
      "country": "PL",
      "phone": "730031138",
      "type": "BILLING"
    }
  ],
  "totalItems": 45,
  "pageNumber": 2,
  "totalPages": 45,
  "pageSize": 1,
  "nextPage": 3
}

POST - create address

Address can be created in ONe by two ways - in address section in Backoffice or in order placing process.

In external system case use POST /api/v1/account/integrations/auth-required/addresses to create address using the API.

The sequence diagram below shows the dependence of communicating with the API:

In request you need to put the required following data:

clientID - (query)

externalID

city

country

pame

phone

street

zipCode

Example request:

json
curl -X POST "https://api-preprod.one.unity.pl/api/v1/account/integrations/auth-required/addresses?clientId=org%3Af1fb9b49-3363-42dd-ba7e-7ff992f8a311" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"
-H  "Content-Type: application/json" 
-d "
{                                                            -- required, address details
  "city": "Poznań",
  "country": "Polska",
  "externalId": "1233-12332-134",
  "name": "Company",
  "phone": "111111111",
  "street": "Pozańska",
  "zipCode": "55-231"
}

In response we will get address identifier and external address ID used in the request.

Example response:

json
{
  "addressId": "363acae5-78a2-48e0-8c3a-4f135b7f9aa4",       -- address identifier in internal system (ONe platform)
  "externalAddressId": "1233-12332-134"                      -- address identifier can be used to map to external systems (e.g. ERP)

GET address by ID

Next step as you have addressId you can use GET /api/v1/account/integrations/auth-required/addresses/{addressId} to receive information about specific address using its ID. The diagram below shows the dependence of communicating with the API:

Use the following parameter to find the address you are looking for:

AddressID - (query)

Example request:

json
curl -X GET 
"https://api-preprod.one.unity.pl/api/v1/account/integrations/auth-required/addresses/363acae5-78a2-48e0-8c3a-4f135b7f9aa4" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response, you will receive information about selected the address as along details.

Example response:

json
{
  "id": "363acae5-78a2-48e0-8c3a-4f135b7f9aa4",               -- address identifier
  "externalId": "1233-12332-134",
  "organizationId": "b4c8ce61-d434-4645-b338-f0e2d27e78a8",   -- client identifier (deprecated) 
  "clientId": "org:b4c8ce61-d434-4645-b338-f0e2d27e78a8",     -- client identifier (prefix - org:)
  "name": "Barszczex",                                        -- address details:
  "street": "Pozańska",
  "zipCode": "55-231",
  "city": "Poznań",
  "country": "Polska",
  "phone": "111111111",
  "type": "ADDITIONAL"                                        -- type of address - BILLING or ADDITIONAL
}

DELETE address

⚠️

Address of type BILLING cannot be deleted

At the end you have the option to delete address. Use DELETE /api/v1/account/integrations/auth-required/addresses/{addressId} to delete existing address. The diagram below shows the dependency of communicating with the API:

In request you need to put required the following data:

AddressId

Example request:

json
curl -X DELETE 
"https://api-preprod.one.unity.pl/api/v1/account/integrations/auth-required/addresses/363acae5-78a2-48e0-8c3a-4f135b7f9aa4" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

GET addresses for synchronization

As previously mentioned, an address can also be create in ONe. The diagram below shows the dependency of communicating with the API when address was created in ONe:

So, if address was created via ONe platform you must use GET /api/v1/account/integrations/auth-required/addresses/synchronization to find the specified address that was created (or edited) in ONe. Use the following parameters to find the events:

contexts - list of the event, to choose: APPLICATION, BACKOFFICE, INTERNAL , INTERGRATIONS - by default all events are returned

startId - first index of the result rows

Example request:

json
curl -X GET 
"https://api-preprod.one.unity.pl/api/v1/account/integrations/auth-required/addresses/synchronization?contexts=INTEGRATIONS&startId=49" 
-H  "accept: */*" 
-H  "one-tenant: {tenant}" 
-H  "ApiAuth: {apiKey}"

In response you will receive a information about address along details

Example response:

json
{
  "nextId": 50,                                                --  next step identifier
  "events": [
    {
      "addressId": "39a7e26c-db38-4f5a-98cd-9adb8a036656",     -- created address identifier
      "externalAddressId": "1233-12332-134",                   -- external address identifier. In the case of adding an address on the ONe side, this id is null
      "type": "CREATE"                                         -- kind of event (create or delete)
    }
  ]
}

When we see that the address has changed, we can use his ID to check the current data. Here's how to do it.