Borkol Docs ana sayfası

Kişiler

Adresler

Kimliği doğrulanmış kişinin teslimat, fatura ve iş adreslerini listeleme, oluşturma, güncelleme ve silme.

Markdown olarak görüntüle

Her kişinin, her biri shipping, billing veya work türünde olan bir adres listesi vardır. Tür başına en fazla bir adres varsayılandır ve API bunu transaksiyonel olarak uygular: bir adreste is_default: true ayarlamak, aynı işlemde aynı türün önceki varsayılanını temizler. Dört endpoint de kişi kimliği doğrulanmış endpoint'lerdir (tenant API anahtarı artı X-Customer-Token); listeleme contacts:read, yazma işlemleri contacts:write scope'una ihtiyaç duyar (customers:read / customers:write kabul edilir).

Adres nesnesi:

AlanTürAçıklama
idstring (uuid)Adres id'si.
typestringshipping, billing veya work.
labelstring or nullKişiye dönük etiket, örneğin Home.
is_defaultbooleanBu adresin kendi türünün varsayılanı olup olmadığı.
namestringAlıcı adı.
streetstringSokak ve kapı numarası.
postal_codestringPosta kodu.
citystringŞehir.
countrystringISO 3166-1 alpha-2 ülke kodu, tam olarak 2 karakter (örneğin NL).
phonestring or nullTelefon numarası.

GET /v1/api/contacts/me/addresses

Mevcut entegrasyonlar için /v1/api/customers/me/addresses üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişinin adreslerini listeler. Varsayılan adresler önce sıralanır. Liste sayfalanmaz; response düz bir data dizisidir.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringEvetKişi oturum token'ı.

Query parametresi yoktur.

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

Durum: 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"
    }
  ]
}

Hatalar

  • X-Customer-Token eksik veya geçersiz olduğunda 401 {"message":"Invalid customer token."}.

POST /v1/api/contacts/me/addresses

Mevcut entegrasyonlar için /v1/api/customers/me/addresses üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişi için bir adres oluşturur. is_default true ise, aynı türün önceki varsayılanı aynı transaksiyonda atomik olarak temizlenir.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringEvetKişi oturum token'ı.

Body parametreleri

AdTürZorunluAçıklama
typestringHayırshipping, billing veya work. Varsayılan shipping.
labelstring or nullHayırEtiket, en fazla 50 karakter.
is_defaultbooleanHayırBu adresi kendi türünün varsayılanı yapar.
namestringEvetAlıcı adı, en fazla 150 karakter.
streetstringEvetSokak ve kapı numarası, en fazla 255 karakter.
postal_codestringEvetPosta kodu, en fazla 20 karakter.
citystringEvetŞehir, en fazla 100 karakter.
countrystringEvetISO 3166-1 alpha-2 kodu, tam olarak 2 karakter.
phonestring or nullHayırTelefon numarası, en fazla 50 karakter.
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"}'

Durum: 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"
  }
}

Hatalar

  • Alan doğrulama hataları için 422, örneğin errors.country ["The country field must be 2 characters."].
  • X-Customer-Token eksik veya geçersiz olduğunda 401 {"message":"Invalid customer token."}.

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

Mevcut entegrasyonlar için /v1/api/customers/me/addresses/{id} üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişinin adreslerinden birini kısmen günceller. Oluşturmayla aynı alanlar, tümü isteğe bağlı; yalnızca gönderdiğiniz alanlar değişir. Sonuçta oluşan adres varsayılansa (ya is_default: true ayarladığınız için ya da adres zaten varsayılanken type alanını değiştirdiğiniz için), sonuç türünün önceki varsayılanı aynı transaksiyonda temizlenir.

Path parametreleri

AdTürZorunluAçıklama
idstring (uuid)EvetAdres id'si. Kimliği doğrulanmış kişiye ait olmalıdır.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringEvetKişi oturum token'ı.

Body parametreleri

AdTürZorunluAçıklama
typestringHayırshipping, billing veya work.
labelstring or nullHayırEtiket, en fazla 50 karakter.
is_defaultbooleanHayırBu adresi kendi türünün varsayılanı yapar.
namestringHayırAlıcı adı, en fazla 150 karakter.
streetstringHayırSokak, en fazla 255 karakter.
postal_codestringHayırPosta kodu, en fazla 20 karakter.
citystringHayırŞehir, en fazla 100 karakter.
countrystringHayırISO 3166-1 alpha-2 kodu, tam olarak 2 karakter.
phonestring or nullHayırTelefon numarası, en fazla 50 karakter.
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}'

Durum: 200 OK. Güncellenmiş adresi döner.

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"
  }
}

Hatalar

  • Adres yoksa veya başka bir kişiye aitse 404.
  • Alan doğrulama hataları için 422.
  • X-Customer-Token eksik veya geçersiz olduğunda 401 {"message":"Invalid customer token."}.

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

Mevcut entegrasyonlar için /v1/api/customers/me/addresses/{id} üzerinde de sunulur; request ve response birebir aynıdır.

Kimliği doğrulanmış kişinin adreslerinden birini siler (soft delete: API'den kaybolur ancak dahili olarak saklanır).

Path parametreleri

AdTürZorunluAçıklama
idstring (uuid)EvetAdres id'si. Kimliği doğrulanmış kişiye ait olmalıdır.

Header'lar

AdTürZorunluAçıklama
X-Customer-TokenstringEvetKişi oturum token'ı.
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"

Durum: 204 No Content. Response'un gövdesi yoktur.

Hatalar

  • Adres yoksa veya başka bir kişiye aitse 404.
  • X-Customer-Token eksik veya geçersiz olduğunda 401 {"message":"Invalid customer token."}.