Ábyrg verslunFyrirtækiAldursskírteiniVefþjónustaAlgengar spurningar
Vefþjónusta

PIM integration

Let a linked device show product lists from your PIM system. Ábyrg verslun stores your tenant's PIM key and hands it to the devices you enable. The device then calls the PIM API itself.

The only supported PIM system is pim.is. Its API lives at https://api.pim.is and authenticates with an X-API-KEY header. Ábyrg verslun does not sync, cache or proxy your products; it only stores the key and each device's PIM settings.

Setup

  1. Store the key. A tenant admin opens Integrations → PIM in the dashboard, turns the integration on, enters the pim.is API key and tests it. The key is stored encrypted.
  2. Enable devices. In the device editor, turn on PIM for each device that should show products and choose which pim.is segments it shows.
  3. Fetch the key on the device. The device calls GET /api/devices/{id}/pim/key and then calls the pim.is API directly with the returned key and segments.

The dashboard's own PIM endpoints (key test and segment list) work only with a dashboard session and are not part of the public API.

Device endpoints

Both endpoints take a linked device's token only: Authorization: DPoP <token> with a DPoP proof header, and the devices:read scope, which devices get by default. See Device authentication. {id} is the calling device's own id, as returned by GET /api/v1/devices/me. Any other id gets 403 DEVICE_MISMATCH.

Unlike the /api/v1 endpoints, these return errors in the legacy { "error", "code" } shape, not Problem Details. See Errors.

GET/api/devices/{id}/pim

Whether PIM is on for this device, and which segments it shows. pimEnabled is true only when both the tenant's PIM integration and this device's PIM setting are on. Does not return the key.

Headers

AuthorizationstringRequired

DPoP <access_token>. Requires the devices:read scope

DPoPstringRequired

A DPoP proof for this request (htm GET, ath)

Examples

cURL

curl https://abyrgverslun.is/api/devices/khh2hxc6ghkzahz07azpb7qhn77m4w09/pim \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

Response

{
  "pimEnabled": true,
  "segmentIds": ["<pim.is segment id>", "<pim.is segment id>"]
}
GET/api/devices/{id}/pim/key

The tenant's decrypted pim.is API key, the device's segments and the PIM API base URL. Only answers when PIM is on for both the tenant and the device and a key is stored. Keep the key on the device; don't log it or send it anywhere but the PIM API.

Headers

AuthorizationstringRequired

DPoP <access_token>. Requires the devices:read scope

DPoPstringRequired

A DPoP proof for this request (htm GET, ath)

Examples

cURL

curl https://abyrgverslun.is/api/devices/khh2hxc6ghkzahz07azpb7qhn77m4w09/pim/key \
  -H "Authorization: DPoP $ACCESS_TOKEN" \
  -H "DPoP: $DPOP_PROOF"

Response

{
  "apiKey": "<your pim.is API key>",
  "segmentIds": ["<pim.is segment id>", "<pim.is segment id>"],
  "apiBaseUrl": "https://api.pim.is"
}

Errors

StatuscodeWhen
400PIM_NOT_ENABLED/pim/key only: PIM is off for the tenant or for this device
400NO_API_KEY/pim/key only: no pim.is key is stored for the tenant
401UNAUTHORIZEDMissing or invalid device token or DPoP proof, or a non-DPoP token
403FORBIDDENThe token lacks devices:read
403DEVICE_MISMATCH{id} is not the calling device
500SERVER_ERRORUnexpected server error
HTTP/1.1 403 Forbidden

{
  "error": "Device ID mismatch",
  "code": "DEVICE_MISMATCH"
}

Calling pim.is

With the key in hand, the device calls the pim.is API at apiBaseUrl and sends the key in the X-API-KEY header. Which pim.is endpoints to call, and how to filter by the returned segmentIds, is described in the pim.is API documentation.

const { apiKey, segmentIds, apiBaseUrl } = await pimKeyResponse.json();

const response = await fetch(`${apiBaseUrl}/segments/`, {
  headers: { 'X-API-KEY': apiKey },
});