Verbinden

Wat je nodig hebt

• Het basisadres: https://pim.internetservicebureau.nl/api/v1. Gebruik altijd https.
• Een token van de PIM-beheerder. Je kunt het zelf niet aanmaken. Vraag het aan en vertel erbij voor welk systeem je het nodig hebt.
• Code op je eigen server. De API is bedoeld voor server naar server. Roep hem niet aan vanuit een browser of app.

Het token staat voor jouw bedrijf. De API weet daardoor welke gegevens bij jou horen. Je geeft nergens een klantnummer mee.

Je eerste verzoek

Elk verzoek stuurt het token mee in de header Authorization, na het woord Bearer en een spatie. Stuur ook altijd de header Accept: application/json. Dan zijn ook de foutmeldingen JSON.

1. Zet het token in de omgevingsvariabele PIM_API_TOKEN.
2. Voer een van de voorbeelden hieronder uit. Het vraagt de eerste twee producten op.
3. Controleer of de status 200 is en of data producten bevat.

# Zet je token in een omgevingsvariabele. Zet het nooit in een script dat je deelt.
export PIM_API_TOKEN='<jouw-token>'

# -g laat curl de blokhaken in filter[...] ongemoeid.
curl -sS -g "https://pim.internetservicebureau.nl/api/v1/products?per_page=2" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PIM_API_TOKEN"

// Alleen in code op je eigen server: zet het token nooit in browsercode.
// Top-level await werkt in een ES-module (een .mjs-bestand of "type": "module").
const token = process.env.PIM_API_TOKEN;

const response = await fetch('https://pim.internetservicebureau.nl/api/v1/products?per_page=2', {
  headers: {
    Accept: 'application/json',
    Authorization: `Bearer ${token}`,
  },
});

// Een fout is ook JSON: {"message": "..."}
console.log(response.status, await response.json());

<?php

// Het token komt uit de omgeving, niet uit de code.
$token = getenv('PIM_API_TOKEN');

$curl = curl_init('https://pim.internetservicebureau.nl/api/v1/products?per_page=2');
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        "Authorization: Bearer {$token}",
    ],
]);

$body = json_decode(curl_exec($curl), true);

// Een fout is ook JSON: {"message": "..."}
echo curl_getinfo($curl, CURLINFO_RESPONSE_CODE), PHP_EOL;
print_r($body);

import json
import os
import urllib.error
import urllib.request

# Het token komt uit de omgeving, niet uit de code.
token = os.environ["PIM_API_TOKEN"]

request = urllib.request.Request(
    "https://pim.internetservicebureau.nl/api/v1/products?per_page=2",
    headers={
        "Accept": "application/json",
        "Authorization": f"Bearer {token}",
    },
)

try:
    with urllib.request.urlopen(request) as response:
        print(response.status, json.load(response))
except urllib.error.HTTPError as error:
    # Een fout is ook JSON: {"message": "..."}
    print(error.code, json.load(error))

Het antwoord

Het antwoord heeft drie delen. data is de lijst met producten. links verwijst naar de volgende pagina. meta zegt waar je bent.

{
  "data": [
    {
      "ean13": "8710000000001",
      "name": "Voorbeeldmerk Voorbeeld Vitamine C - 90cp",
      "status": "active",
      "suppliers": [
        { "supplier": "Voorbeeldleverancier", "price": 8.5, "stock": 40 }
      ]
    }
  ],
  "links": {
    "first": "https://pim.internetservicebureau.nl/api/v1/products?per_page=2&page=1",
    "last": null,
    "prev": null,
    "next": "https://pim.internetservicebureau.nl/api/v1/products?per_page=2&page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "per_page": 2,
    "to": 2
  }
}

Dit antwoord is ingekort. Een product heeft meer velden, zie Producten. De waarden zijn verzonnen.

Het antwoord zegt niet hoeveel producten er in totaal zijn. Je weet dat je klaar bent als links.next null is.

Als het niet lukt

Krijg je een andere status dan 200, dan staat de reden in message, bijvoorbeeld {"message": "Invalid token"}. Bij Foutmeldingen staat per melding wat je doet.

Optioneel: alleen vanaf vaste IP-adressen

Standaard mag je met een geldig token vanaf elk IP-adres verbinden. Wil je een extra slot, vraag dan de PIM-beheerder om het IP-adres van je server te activeren.

• Zodra er minstens één IP-adres actief is voor jouw bedrijf, mogen alleen actieve IP-adressen verbinden.
• Verbind je vanaf een ander adres, dan krijg je 401 met de melding Ip Address is not allowed to connect.
• Het adres dat de PIM ziet, is het uitgaande adres van je server. Geef dat door.
• Verhuis je server of wisselt het adres, meld het dan vooraf, zodat de beheerder het nieuwe adres kan activeren.

De PIM onthoudt vanaf welke IP-adressen je verzoeken doet. Dat helpt de beheerder om het juiste adres te vinden.

Het token veilig bewaren

• Bewaar het token in een omgevingsvariabele of in de geheimenopslag van je hosting, niet in de code.
• Zet het niet in git, niet in browsercode, niet in een app en niet in een e-mail.
• Schrijf het niet naar logbestanden en laat debugoutput de Authorization-header niet tonen.