Contacten

Adressen

De verzend-, factuur- en werkadressen van het geauthenticeerde contact opvragen, aanmaken, bijwerken en verwijderen.

Elk contact heeft een lijst met adressen, elk getypeerd als shipping, billing of work. Per type is hoogstens één adres het standaardadres, en de API dwingt dit transactioneel af: het zetten van is_default: true op een adres wist het vorige standaardadres van hetzelfde type in dezelfde operatie. Alle vier de endpoints zijn contact-geauthenticeerd (tenant-API-key plus X-Customer-Token); voor het opvragen is de contacts:read scope nodig, voor schrijfacties contacts:write (customers:read / customers:write geaccepteerd).

Het adresobject:

Veld	Type	Beschrijving
`id`	string (uuid)	Adres-id.
`type`	string	`shipping`, `billing` of `work`.
`label`	string of null	Contactgericht label, bijvoorbeeld `Home`.
`is_default`	boolean	Of dit het standaardadres van zijn type is.
`name`	string	Naam van de ontvanger.
`street`	string	Straat en huisnummer.
`postal_code`	string	Postcode.
`city`	string	Plaats.
`country`	string	ISO 3166-1 alpha-2-landcode, exact 2 tekens (bijvoorbeeld `NL`).
`phone`	string of null	Telefoonnummer.

Het adresobject:

Veld	Type	Beschrijving
`id`	string (uuid)	Adres-id.
`type`	string	`shipping`, `billing` of `work`.
`label`	string of null	Contactgericht label, bijvoorbeeld `Home`.
`is_default`	boolean	Of dit het standaardadres van zijn type is.
`name`	string	Naam van de ontvanger.
`street`	string	Straat en huisnummer.
`postal_code`	string	Postcode.
`city`	string	Plaats.
`country`	string	ISO 3166-1 alpha-2-landcode, exact 2 tekens (bijvoorbeeld `NL`).
`phone`	string of null	Telefoonnummer.

GET /v1/api/contacts/me/addresses

Ook aangeboden op /v1/api/customers/me/addresses voor bestaande integraties; identiek request en response.

Vraag de adressen van het geauthenticeerde contact op. Standaardadressen staan eerst. De lijst is niet gepagineerd; de respons is een gewone data-array.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Geen query-parameters.

Status: 200 OK.

Fouten

401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

Request

curl https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}

GET /v1/api/contacts/me/addresses

Ook aangeboden op /v1/api/customers/me/addresses voor bestaande integraties; identiek request en response.

Vraag de adressen van het geauthenticeerde contact op. Standaardadressen staan eerst. De lijst is niet gepagineerd; de respons is een gewone data-array.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Geen query-parameters.

Request

curl https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Status: 200 OK.

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}

Fouten

401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

POST /v1/api/contacts/me/addresses

Ook aangeboden op /v1/api/customers/me/addresses voor bestaande integraties; identiek request en response.

Maak een adres aan voor het geauthenticeerde contact. Als is_default true is, wordt het vorige standaardadres van hetzelfde type atomair gewist in dezelfde transactie.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Body-parameters

Naam	Type	Verplicht	Beschrijving
`type`	string	Nee	`shipping`, `billing` of `work`. Standaard `shipping`.
`label`	string of null	Nee	Label, maximaal 50 tekens.
`is_default`	boolean	Nee	Maak dit het standaardadres van zijn type.
`name`	string	Ja	Naam van de ontvanger, maximaal 150 tekens.
`street`	string	Ja	Straat en huisnummer, maximaal 255 tekens.
`postal_code`	string	Ja	Postcode, maximaal 20 tekens.
`city`	string	Ja	Plaats, maximaal 100 tekens.
`country`	string	Ja	ISO 3166-1 alpha-2-code, exact 2 tekens.
`phone`	string of null	Nee	Telefoonnummer, maximaal 50 tekens.

Status: 201 Created.

Fouten

422 bij veldvalidatiefouten, bijvoorbeeld errors.country ["The country field must be 2 characters."].
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

Request

curl -X POST https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

POST /v1/api/contacts/me/addresses

Ook aangeboden op /v1/api/customers/me/addresses voor bestaande integraties; identiek request en response.

Maak een adres aan voor het geauthenticeerde contact. Als is_default true is, wordt het vorige standaardadres van hetzelfde type atomair gewist in dezelfde transactie.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Body-parameters

Naam	Type	Verplicht	Beschrijving
`type`	string	Nee	`shipping`, `billing` of `work`. Standaard `shipping`.
`label`	string of null	Nee	Label, maximaal 50 tekens.
`is_default`	boolean	Nee	Maak dit het standaardadres van zijn type.
`name`	string	Ja	Naam van de ontvanger, maximaal 150 tekens.
`street`	string	Ja	Straat en huisnummer, maximaal 255 tekens.
`postal_code`	string	Ja	Postcode, maximaal 20 tekens.
`city`	string	Ja	Plaats, maximaal 100 tekens.
`country`	string	Ja	ISO 3166-1 alpha-2-code, exact 2 tekens.
`phone`	string of null	Nee	Telefoonnummer, maximaal 50 tekens.

Request

curl -X POST https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'

Status: 201 Created.

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

Fouten

422 bij veldvalidatiefouten, bijvoorbeeld errors.country ["The country field must be 2 characters."].
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

PATCH /v1/api/contacts/me/addresses/{id}

Ook aangeboden op /v1/api/customers/me/addresses/{id} voor bestaande integraties; identiek request en response.

Werk een van de adressen van het geauthenticeerde contact gedeeltelijk bij. Dezelfde velden als bij aanmaken, allemaal optioneel; alleen de velden die je stuurt worden gewijzigd. Als het resulterende adres standaard is (ofwel omdat je is_default: true hebt gezet, ofwel omdat het adres al standaard was en je zijn type hebt gewijzigd), wordt het vorige standaardadres van het resulterende type gewist in dezelfde transactie.

Pad-parameters

Naam	Type	Verplicht	Beschrijving
`id`	string (uuid)	Ja	Adres-id. Moet van het geauthenticeerde contact zijn.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Body-parameters

Naam	Type	Verplicht	Beschrijving
`type`	string	Nee	`shipping`, `billing` of `work`.
`label`	string of null	Nee	Label, maximaal 50 tekens.
`is_default`	boolean	Nee	Maak dit het standaardadres van zijn type.
`name`	string	Nee	Naam van de ontvanger, maximaal 150 tekens.
`street`	string	Nee	Straat, maximaal 255 tekens.
`postal_code`	string	Nee	Postcode, maximaal 20 tekens.
`city`	string	Nee	Plaats, maximaal 100 tekens.
`country`	string	Nee	ISO 3166-1 alpha-2-code, exact 2 tekens.
`phone`	string of null	Nee	Telefoonnummer, maximaal 50 tekens.

Status: 200 OK. Retourneert het bijgewerkte adres.

Fouten

404 wanneer het adres niet bestaat of van een ander contact is.
422 bij veldvalidatiefouten.
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

Request

curl -X PATCH https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

PATCH /v1/api/contacts/me/addresses/{id}

Ook aangeboden op /v1/api/customers/me/addresses/{id} voor bestaande integraties; identiek request en response.

Pad-parameters

Naam	Type	Verplicht	Beschrijving
`id`	string (uuid)	Ja	Adres-id. Moet van het geauthenticeerde contact zijn.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Body-parameters

Naam	Type	Verplicht	Beschrijving
`type`	string	Nee	`shipping`, `billing` of `work`.
`label`	string of null	Nee	Label, maximaal 50 tekens.
`is_default`	boolean	Nee	Maak dit het standaardadres van zijn type.
`name`	string	Nee	Naam van de ontvanger, maximaal 150 tekens.
`street`	string	Nee	Straat, maximaal 255 tekens.
`postal_code`	string	Nee	Postcode, maximaal 20 tekens.
`city`	string	Nee	Plaats, maximaal 100 tekens.
`country`	string	Nee	ISO 3166-1 alpha-2-code, exact 2 tekens.
`phone`	string of null	Nee	Telefoonnummer, maximaal 50 tekens.

Request

curl -X PATCH https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'

Status: 200 OK. Retourneert het bijgewerkte adres.

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

Fouten

404 wanneer het adres niet bestaat of van een ander contact is.
422 bij veldvalidatiefouten.
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

DELETE /v1/api/contacts/me/addresses/{id}

Ook aangeboden op /v1/api/customers/me/addresses/{id} voor bestaande integraties; identiek request en response.

Verwijder een van de adressen van het geauthenticeerde contact (soft delete: het verdwijnt uit de API maar wordt intern bewaard).

Pad-parameters

Naam	Type	Verplicht	Beschrijving
`id`	string (uuid)	Ja	Adres-id. Moet van het geauthenticeerde contact zijn.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Status: 204 No Content. De respons heeft geen body.

Fouten

404 wanneer het adres niet bestaat of van een ander contact is.
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

Request

curl -X DELETE https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

DELETE /v1/api/contacts/me/addresses/{id}

Ook aangeboden op /v1/api/customers/me/addresses/{id} voor bestaande integraties; identiek request en response.

Verwijder een van de adressen van het geauthenticeerde contact (soft delete: het verdwijnt uit de API maar wordt intern bewaard).

Pad-parameters

Naam	Type	Verplicht	Beschrijving
`id`	string (uuid)	Ja	Adres-id. Moet van het geauthenticeerde contact zijn.

Headers

Naam	Type	Verplicht	Beschrijving
`X-Customer-Token`	string	Ja	Contactsessietoken.

Request

curl -X DELETE https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Status: 204 No Content. De respons heeft geen body.

Fouten

404 wanneer het adres niet bestaat of van een ander contact is.
401 {"message":"Invalid customer token."} wanneer X-Customer-Token ontbreekt of ongeldig is.

GET /v1/api/contacts/me/addresses#

Headers#

Fouten#

GET /v1/api/contacts/me/addresses#

Headers#

Fouten#

POST /v1/api/contacts/me/addresses#

Headers#

Body-parameters#

Fouten#

POST /v1/api/contacts/me/addresses#

Headers#

Body-parameters#

Fouten#

PATCH /v1/api/contacts/me/addresses/{id}#

Pad-parameters#

Headers#

Body-parameters#

Fouten#

PATCH /v1/api/contacts/me/addresses/{id}#

Pad-parameters#

Headers#

Body-parameters#

Fouten#

DELETE /v1/api/contacts/me/addresses/{id}#

Pad-parameters#

Headers#

Fouten#

DELETE /v1/api/contacts/me/addresses/{id}#

Pad-parameters#

Headers#

Fouten#

GET /v1/api/contacts/me/addresses

Headers

Fouten

GET /v1/api/contacts/me/addresses

Headers

Fouten

POST /v1/api/contacts/me/addresses

Headers

Body-parameters

Fouten

POST /v1/api/contacts/me/addresses

Headers

Body-parameters

Fouten

PATCH /v1/api/contacts/me/addresses/{id}

Pad-parameters

Headers

Body-parameters

Fouten

PATCH /v1/api/contacts/me/addresses/{id}

Pad-parameters

Headers

Body-parameters

Fouten

DELETE /v1/api/contacts/me/addresses/{id}

Pad-parameters

Headers

Fouten

DELETE /v1/api/contacts/me/addresses/{id}

Pad-parameters

Headers

Fouten