Address

⚠️
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

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:
Image without caption
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:
Image without caption
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:
Image without caption
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:
Image without caption
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:
Image without caption
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.

Powered by Notaku