API Referentie

De complete documentatie voor de Producthandel AI Bridge. Integreer voorraad, orders en verrijkte data direct in uw systemen.

Documentatie

Beveiliging & Authenticatie

Welkom bij de Producthandel API. Om de veiligheid van B2B-transacties en persoonsgegevens te waarborgen, werken wij met strikte authenticatie-headers. Base URL voor alle requests: https://bridge.producthandel.nl

1. De X-API-Key (Verplicht)

Elke request (GET, POST, DELETE) moet uw unieke sleutel bevatten in de HTTP Headers. Onze API herkent aan de hand van deze sleutel direct uw bedrijfsaccount, past automatisch uw staffelkortingen toe op de datastromen, en autoriseert de request.

HTTP Header
X-API-Key: ph_live_8f92a4b1c3d5e...
2. Idempotency (Anti-Dubbel)

Voor alle POST requests (zoals het aanmaken van orders of RMA's) vereisen wij een Idempotency-Key. Dit is een unieke ID die u zelf genereert (bijv. uw eigen ordernummer). Valt uw internetverbinding weg tijdens een request en stuurt uw systeem de order per ongeluk nog een keer? Onze bridge herkent de sleutel en blokkeert de duplicaat-actie. Wel zo veilig.

HTTP Header
Idempotency-Key: ORD-2026-99182

Resellers & B2B Afnemers

Endpoints voor het ophalen van producten, live voorraad en het inschieten van orders.

Nieuwe Order Aanmaken

Schiet een verkooporder in. Het systeem voert direct een fail-fast validatie uit op bestaande SKU's om onvolledige zendingen (backorders) te voorkomen. Facturatie geschiedt standaard op rekening, mits uw kredietlimiet dit toelaat.

Headers vereist:
  • X-API-Key
  • Idempotency-Key
  • Content-Type: application/json
Request Payload (JSON)
{
  "customer": {
    "company_name": "Optioneel B.V.",
    "name": "Klant Naam",
    "email": "klant@bedrijf.nl",
    "phone": "+31612345678"
  },
  "shipping_address": {
    "street": "Hoofdstraat 1",
    "zip": "1000AA",
    "city": "Amsterdam"
  },
  "order_details": {
    "po_number": "WEB-ORD-2026"
  },
  "lines": [
    { "sku": "TEST-PRODUCT-001", "quantity": 4 }
  ]
}
Response (201 Created)
{
  "status": "success",
  "producthandel_order_id": "PH-4491",
  "expected_shipping_date": "2026-04-27"
}

Live Voorraad Check

Dit endpoint is extreem snel (lage latency). Gebruik dit tijdens uw eigen check-out proces om te valideren of wij nog voldoende voorraad hebben, zodat u geen 'nee' hoeft te verkopen.

Parameters:
sku
string (path)		 Het unieke artikelnummer van Producthandel.
Response (200 OK)
{
  "sku": "TEST-PRODUCT-001",
  "total_stock": 142,
  "stock_status": "in_stock",
  "lead_time_days": 1
}

Haal een volledige feed op van ons assortiment. Prijzen worden automatisch teruggerekend naar uw inkoopprijs op basis van uw API-sleutel.

Array Response (200 OK)
[
  {
    "sku": "TEST-001",
    "ean": "871234567890",
    "title_nl": "Zebra Labelprinter GK420d",
    "your_price_ex_vat": 210.50,
    "total_stock": 45,
    "category_path": "Hardware > Printers > Labelprinters"
  }
]

Tip: Gebruik /api/v1/catalog/export_changes om alleen producten op te halen die in het afgelopen uur zijn gewijzigd (bespaart bandbreedte).

Leverancier Endpoints

Laat onze lokale AI uw productdata automatisch inlezen en vertalen, zonder dat u maatwerk hoeft te verrichten in uw ERP.

Slimme Data Mapping

Stuur uw assortimentsupdates (prijzen, voorraad) als JSON of CSV. Onze intelligente mapping-engine leert uw veldnamen eenmalig aan en koppelt deze automatisch aan onze database.

Belangrijk: Zorg dat uw payload altijd een unieke identifier bevat (zoals SKU of EAN) en de actuele voorraad en inkoopprijs.
Request Payload (Voorbeeld JSON)
{
  "items": [
    {
      "artikelnummer": "UW-REF-99",
      "barcode": "8712345...",
      "beschikbaar": 45,
      "inkoop_prijs": 45.00
    }
  ]
}

Voor legacy ERP-systemen (zoals oudere versies van Exact of Navision) die moeite hebben met dynamische JSON. Upload simpelweg een ruwe CSV of XML string in de body. Wij parsen het aan onze kant.

Request Body (text/csv)
sku;barcode;voorraad;prijs;avd
ART-99;871234567890;45;45.00;JA
ART-100;87456123987;12;22.50;NEE

Automatisering & Enterprise

Geavanceerde endpoints voor push-notificaties (Webhooks) en geautomatiseerde administratie.

Webhook Registreren

Abonneer uw eigen URL op events uit ons systeem. U ontvangt direct een POST-request van ons zodra een event (zoals een verzending) plaatsvindt.

Beschikbare Events:
  • order.shipped (Bevat Track & Trace)
  • order.cancelled
  • inventory.low_stock
Request Payload
{
  "target_url": "https://uw-systeem.nl/webhooks/producthandel",
  "event": "order.shipped"
}

Haal de definitieve factuur op voor uw administratie. Geef middels de format parameter aan of u een visuele PDF wilt of een inleesbaar XML/UBL bestand voor uw boekhoudpakket.

format
query string		 Opties: pdf of ubl (Standaard is pdf).