Borkol Docs startpagina

Contacten

Registratie en sessies

Een contactaccount registreren, inloggen voor een sessietoken, en uitloggen.

Bekijk als Markdown

Deze drie endpoints beheren contactaccounts en sessietokens. register en login retourneren een token naast het contact; stuur dit als X-Customer-Token mee op contact-geauthenticeerde endpoints. Alle drie vereisen ze de contacts:write scope op je API-key (customers:write geaccepteerd).

POST /v1/api/contacts/register

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

Registreer een storefront-contactaccount. Retourneert het aangemaakte contact plus een sessietoken. Als het e-mailadres al bij een gastrij hoort (aangemaakt door e-mailcapture in de winkelwagen in de Commerce-module), wordt de gast ter plekke geüpgraded: zelfde id, bestelgeschiedenis behouden, naam en wachtwoord gezet vanuit dit request. Alleen een e-mailadres dat bij een echt (niet-gast) account hoort, wordt geweigerd. Extra rate limit: 10 requests per minuut per IP.

Body-parameters

NaamTypeVerplichtBeschrijving
namestringJaVolledige naam. Maximaal 150 tekens.
emailstringJaGeldig e-mailadres, maximaal 255 tekens. Server-side naar lowercase omgezet. Mag niet bij een bestaand niet-gast account horen.
passwordstringJaMinimaal 8 tekens.
Request
curl -X POST https://api.borkol.com/v1/api/contacts/register \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Doe","email":"jane@example.com","password":"s3cret-pass"}'
Request (JS)
const res = await fetch("https://api.borkol.com/v1/api/contacts/register", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Jane Doe",
    email: "jane@example.com",
    password: "s3cret-pass",
  }),
});
const { data: contact, token } = await res.json();

Status: 201 Created.

Response
{
  "data": {
    "id": "9d4e2f1a-6b3c-4f8e-9a1d-2c5b7e8f0a3d",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": null,
    "kind": "person",
    "company_name": null,
    "registration_number": null,
    "vat_id": null,
    "external_id": null,
    "display_name": "Jane Doe",
    "created_at": "2026-08-14T10:32:11+00:00"
  },
  "token": "12|Fq8sT3vY6wZx9aBcDeFgHiJkLmNoPqRsTuVwXyZ0"
}

Fouten

  • 422 met errors.email ["Email already registered."] wanneer een niet-gast account het e-mailadres al gebruikt.
  • 422 bij veldvalidatiefouten (ontbrekende naam, ongeldig e-mailadres, wachtwoord korter dan 8 tekens).
  • 429 wanneer de limiet van 10 requests per minuut per IP is overschreden.

POST /v1/api/contacts/login

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

Authenticeer een contact met e-mailadres en wachtwoord. Retourneert het contact en een vers sessietoken, en werkt last_login_at van het account bij. De controle is timing-safe en onthult nooit of het e-mailadres bestaat: een verkeerd wachtwoord, een onbekend e-mailadres en een gastaccount (dat geen wachtwoord heeft) falen allemaal met dezelfde 422. Extra rate limit: 10 requests per minuut per IP.

Body-parameters

NaamTypeVerplichtBeschrijving
emailstringJaGeldig e-mailadres. Server-side naar lowercase omgezet vóór de lookup.
passwordstringJaHet accountwachtwoord.
Request
curl -X POST https://api.borkol.com/v1/api/contacts/login \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","password":"s3cret-pass"}'

Status: 200 OK.

Response
{
  "data": {
    "id": "9d4e2f1a-6b3c-4f8e-9a1d-2c5b7e8f0a3d",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+31612345678",
    "kind": "person",
    "company_name": null,
    "registration_number": null,
    "vat_id": null,
    "external_id": null,
    "display_name": "Jane Doe",
    "created_at": "2026-08-14T10:32:11+00:00"
  },
  "token": "13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"
}

Fouten

  • 422 met errors.email ["Invalid credentials."] voor een verkeerd e-mailadres of een verkeerd wachtwoord. De fout staat altijd op de email-key.
  • 429 wanneer de limiet van 10 requests per minuut per IP is overschreden.

POST /v1/api/contacts/logout

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

Trek het contactsessietoken in dat in X-Customer-Token is meegegeven. De header moet aanwezig en geldig zijn om de contactauthenticatie te passeren: een momenteel geldig token wordt ingetrokken en het request retourneert 204, terwijl een al ingetrokken of onbekend token de authenticatie laat falen met 401 {"message": "Invalid customer token."}.

Headers

NaamTypeVerplichtBeschrijving
X-Customer-TokenstringJaHet in te trekken sessietoken.

Geen body.

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

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

Fouten

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