RFID CUP API · v1Live-overzicht →

API-specificatie

Deze API registreert RFID-tags als uitgegeven (IN) of ingenomen (OUT). Elke scan blijft in de historie; de actuele status van een tag is altijd de laatste scan.

Basis

Het basisadres is https://cups.paytree-network.nl. Verzoeken en antwoorden gebruiken JSON. Voeg bij POST-verzoeken altijd deze header toe:

Content-Type: application/json

De API heeft in dit concept nog geen authenticatie. Voeg vóór productie een API-key of andere beveiliging toe.

Endpoints

POST/api/scans/inRegistreer één of meer bekers als uitgegeven.

POST/api/scans/outRegistreer één of meer bekers als ingenomen.

GET/api/cupsHaal alle momenteel uitgegeven bekers op.

GET/api/historyHaal alle gelezen tags en scanacties op.

GET/api/cups/{tag}Haal één beker plus de volledige scanhistorie op.

GET/healthEenvoudige beschikbaarheidscheck.

Bekers uitgeven of innemen

Gebruik exact hetzelfde JSON-formaat voor beide richtingen. Een batch mag bijvoorbeeld twaalf hardcups bevatten.

Verzoek

{
  "request_id": "invoerpoort-1-20260818-0001",
  "source": "invoerpoort-1",
  "tags": ["04:A1:B2:C3", "04:A1:B2:C4"]
}

Veld	Verplicht	Betekenis
`tags`	Ja	Niet-lege lijst met RFID-tagwaarden. Dubbele tags binnen één verzoek worden automatisch maar één keer verwerkt.
`source`	Nee	Naam of identificatie van de scanner, bijvoorbeeld `invoerpoort-1`.
`request_id`	Nee, aanbevolen	Unieke ID van dit scannerverzoek. Bij opnieuw verzenden geeft de API hetzelfde resultaat terug zonder dubbel te registreren.

Uitgeven

POST /api/scans/in

Innemen

POST /api/scans/out

Succesantwoord · HTTP 201

{
  "batch_id": 42,
  "direction": "in",
  "scanned_at": "2026-08-18T08:32:34+00:00",
  "processed_tags": 2,
  "tags": ["04:A1:B2:C3", "04:A1:B2:C4"]
}

Status opvragen

Alle bekers

GET /api/cups

{
  "count": 2,
  "cups": [{
    "tag": "04:A1:B2:C3",
    "status": "IN",
    "last_scanned_at": "2026-08-18T08:32:34+00:00",
    "last_source": "invoerpoort-1"
  }]
}

Eén beker en zijn historie

GET /api/cups/04%3AA1%3AB2%3AC3

Gebruik URL-encoding wanneer een tag speciale tekens bevat, zoals :. De respons bevat het object cup met de actuele status en een lijst events met alle scans, nieuwste eerst.

Fouten en gedrag

Status	Wanneer
`200`	GET-verzoek gelukt, of een eerder `request_id` opnieuw ontvangen.
`201`	Nieuwe scanbatch opgeslagen.
`404`	Onbekende route of tag niet gevonden.
`422`	Ongeldige invoer, bijvoorbeeld geen `tags`-lijst.
`500`	Onverwachte serverfout.

Een tag mag meerdere keren IN of OUT gescand worden. Dit wordt bewust bewaard als auditgeschiedenis; de laatste scan bepaalt de actuele status.