API Documentatie

Quickstart

U kunt binnen 5 minuten live gaan. Vraag een API-sleutel aan via dierenarts.php en maak uw eerste request:

# Test de API — geen authenticatie nodig
curl https://chipreaders.nl/api/v1/status

# Chip opzoeken met uw sleutel
curl -H "Authorization: Bearer UW_API_SLEUTEL" \
     https://chipreaders.nl/api/v1/chip/528140000123456

Authenticatie

Alle endpoints behalve /status vereisen een API-sleutel via de Authorization header:

Authorization: Bearer uw_64_karakter_api_sleutel

Heeft u nog geen sleutel? Vraag er gratis een aan — voor dierenartsen, asielen en gemeenten is gebruik gratis.

Response formaat

Alle responses zijn JSON met de volgende vaste structuur:

{
  "ok":    true,          // true bij succes, false bij fout
  "data":  { ... },      // payload bij succes, null bij fout
  "error": null          // foutmelding bij fout, null bij succes
}

Rate limits

Elke API-sleutel mag 1.000 verzoeken per dag versturen. De teller wordt dagelijks om middernacht (CET) gereset.

Bij overschrijding ontvangt u HTTP 429:

{
  "ok":    false,
  "data":  null,
  "error": "Daglimiet van 1000 API-verzoeken bereikt."
}

Hogere limieten zijn beschikbaar op aanvraag. Neem contact op via info@chipreaders.nl.

Endpoints

GET /api/v1/status Geen auth vereist

Controleer of de API operationeel is. Geen authenticatie vereist.

VOORBEELD RESPONSE

{
  "ok": true,
  "data": {
    "api":       "ChipReaders B2B API",
    "version":  "v1",
    "status":   "operational",
    "timestamp":"2025-06-01T10:00:00+02:00",
    "docs":     "https://chipreaders.nl/api-docs.php"
  }
}

GET /api/v1/chip/{chipnummer}

Zoek een geregistreerd dier op via het chipnummer (15 hexadecimale tekens).

URL PARAMETERS

Parameter	Type	Omschrijving
`chipnummer` verplicht	string	15-karakter chip-ID (hexadecimaal of numeriek)

VOORBEELD REQUEST

curl -X GET \
  "https://chipreaders.nl/api/v1/chip/528140000123456" \
  -H "Authorization: Bearer uw_api_sleutel"

VOORBEELD RESPONSE (200)

{
  "ok": true,
  "data": {
    "chip":             "528140000123456",
    "naam":             "Bella",
    "soort":            "hond",
    "ras":              "Labrador",
    "geslacht":         "v",
    "kleur":            "geel",
    "geboortedatum":    "2019-03-15",
    "status":           "actief",
    "vermist":          false,
    "geregistreerd_op": "2020-01-10 14:32:00",
    "bijzonderheden":   null,
    "publiek_url":      "https://chipreaders.nl/p.php?t=abc123..."
  },
  "error": null
}

POST /api/v1/chip/registreer

Registreer een nieuw chipnummer inclusief eigenaar. Als het e-mailadres nog niet bestaat, wordt automatisch een gebruikersaccount aangemaakt.

REQUEST BODY (application/json)

Veld	Type	Omschrijving
`chipnummer` verplicht	string	15-karakter chip-ID
`eigenaar_email` verplicht	string	E-mailadres van de eigenaar
`naam` optioneel	string	Naam van het dier
`soort` optioneel	string	`hond` · `kat` · `konijn` · `vogel` · `paard` · `overig`
`ras` optioneel	string	Ras van het dier
`geslacht` optioneel	string	`m` · `v` · `onbekend`
`kleur` optioneel	string	Kleur van het dier
`geboortedatum` optioneel	string	Formaat: `JJJJ-MM-DD`
`eigenaar_naam` optioneel	string	Volledige naam van de eigenaar
`eigenaar_telefoon` optioneel	string	Telefoonnummer eigenaar

VOORBEELD REQUEST

curl -X POST \
  "https://chipreaders.nl/api/v1/chip/registreer" \
  -H "Authorization: Bearer uw_api_sleutel" \
  -H "Content-Type: application/json" \
  -d '{
    "chipnummer":       "528140000123456",
    "eigenaar_email":  "jan.jansen@email.nl",
    "eigenaar_naam":   "Jan Jansen",
    "eigenaar_telefoon": "0612345678",
    "naam":            "Bella",
    "soort":           "hond",
    "ras":             "Labrador",
    "geslacht":        "v",
    "geboortedatum":   "2019-03-15",
    "kleur":           "geel"
  }'

VOORBEELD RESPONSE (201)

{
  "ok": true,
  "data": {
    "dier_id":    1042,
    "chip":       "528140000123456",
    "naam":       "Bella",
    "soort":      "hond",
    "eigenaar":   {
      "user_id": 87,
      "email":   "jan.jansen@email.nl",
      "naam":    "Jan Jansen"
    },
    "publiek_url": "https://chipreaders.nl/p.php?t=abc123...",
    "geregistreerd_via": "api"
  },
  "error": null
}

POST /api/v1/vermist/meld

Meld een geregistreerd dier als vermist. Het dier verschijnt direct op de vermist-pagina.

REQUEST BODY (application/json)

Veld	Type	Omschrijving
`chipnummer` verplicht	string	15-karakter chip-ID van het vermiste dier

VOORBEELD RESPONSE (200)

{
  "ok": true,
  "data": {
    "chip":    "528140000123456",
    "status":  "vermist",
    "bericht": "Dier is als vermist gemeld en verschijnt nu op de vermist-pagina."
  },
  "error": null
}

Foutcodes

HTTP Code	Betekenis	Oorzaak
200	OK	Verzoek succesvol verwerkt
201	Created	Resource succesvol aangemaakt (registreer)
400	Bad Request	Request body is geen geldige JSON
401	Unauthorized	Authorization header ontbreekt of sleutel ongeldig
403	Forbidden	Sleutel geblokkeerd of IP staat niet op whitelist
404	Not Found	Chipnummer of route bestaat niet
409	Conflict	Chipnummer al geregistreerd, of dier al als vermist gemeld
422	Unprocessable	Validatiefout (ongeldig chipnummer, ontbrekend veld etc.)
429	Too Many Requests	Daglimiet van 1.000 calls overschreden
500	Server Error	Interne fout — neem contact op als dit aanhoudt

Code-voorbeelden

PHP

// Chip opzoeken met PHP cURL
function chipreaders_lookup(string $chip, string $apiKey): array {
    $ch = curl_init('https://chipreaders.nl/api/v1/chip/' . urlencode($chip));
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
        CURLOPT_TIMEOUT        => 10,
    ]);
    $body = curl_exec($ch);
    curl_close($ch);
    return json_decode($body, true);
}

$result = chipreaders_lookup('528140000123456', 'uw_api_sleutel');
if ($result['ok']) {
    echo 'Naam: ' . $result['data']['naam'];
}

Python

import requests

API_KEY = "uw_api_sleutel"
BASE    = "https://chipreaders.nl/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

# Chip opzoeken
r = requests.get(f"{BASE}/chip/528140000123456", headers=HEADERS)
print(r.json()["data"]["naam"])

# Chip registreren
r = requests.post(f"{BASE}/chip/registreer", headers=HEADERS, json={
    "chipnummer":      "528140000999001",
    "eigenaar_email":  "klant@email.nl",
    "naam":            "Max",
    "soort":           "kat",
})
print(r.json())

JavaScript / Node.js (fetch)

const API_KEY = 'uw_api_sleutel';
const BASE    = 'https://chipreaders.nl/api/v1';

// Chip registreren
const res = await fetch(`${BASE}/chip/registreer`, {
  method:  'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type':  'application/json',
  },
  body: JSON.stringify({
    chipnummer:      '528140000888001',
    eigenaar_email:  'eigenaar@mail.nl',
    naam:            'Fleur',
    soort:           'kat',
  }),
});
const { ok, data, error } = await res.json();
console.log(ok ? data.publiek_url : error);

Changelog

v1.0

Eerste release

Endpoints: GET /chip/{nr}, POST /chip/registreer, GET /status, POST /vermist/meld. Bearer-tokenauth, rate limiting (1000/dag), IP-whitelist.