API & Developer Docs

Ragently is een AI-klantenserviceplatform voor webshops. De chatbot beantwoordt vragen, beheert bestellingen, verwerkt retouren en terugbetalingen en doet productaanbevelingen — getraind op jouw content en gekoppeld aan jouw commerce-platform.

Naast kant-en-klare koppelingen (Shopify, Lightspeed, WooCommerce, Wix) is er de Custom Commerce-integratie: draai je je eigen software — een zelfgebouwde backend, een ERP of een OMS — dan implementeer je een klein HTTP-contract en koppelt Ragently daaraan. De AI-agent roept jouw endpoints server-to-server aan om realtime order-, klant-, product- en checkoutgegevens op te halen en acties uit te voeren.

Belangrijk om te begrijpen: dit is het contract dat jóuw backend aanbiedt, niet een API die Ragently publiceert. Jij bouwt de endpoints; Ragently is de client. Je hoeft alleen te bouwen wat je nodig hebt — welke functies je aanzet bepaal je zelf via het manifest met capabilities.

De browser van je klant praat uitsluitend met Ragently. Ragently praat op zijn beurt server-to-server met jouw backend. Jouw backend is nooit rechtstreeks vanuit de browser bereikbaar en je auth-secrets komen nooit in de client terecht.

  ┌──────────────┐        ┌───────────────────────────────┐        ┌──────────────────┐
  │   Browser    │        │           Ragently            │        │   Jouw backend   │
  │  (widget)    │        │                               │        │                  │
  │              │  HTTPS  │  ┌────────┐   ┌────────────┐  │  HTTPS  │  ┌────────────┐  │
  │  chat-UI ────┼────────▶│  │  API   │──▶│  Commerce  │──┼────────▶│  │  endpoints │  │
  │              │◀────────┼──│        │◀──│  Connector │  │◀────────┼──│ (contract) │  │
  └──────────────┘        │  └────────┘   └────────────┘  │        │  └─────┬──────┘  │
     alleen naar          └───────────────────────────────┘        │        │         │
      Ragently                    server-to-server                 │        ▼         │
                                                                    │  ERP / DB / OMS  │
                                                                    └──────────────────┘

• De widget in de browser stuurt alleen berichten naar de Ragently API.
• De Commerce Connector van Ragently vertaalt AI-acties naar HTTP-aanroepen op jouw contract.
• Die aanroepen gaan server-to-server naar jouw backend, met de door jou gekozen auth.
• Jouw backend praat verder met je eigen ERP / database / OMS — dat deel blijft volledig privé.

Ragently authenticeert zichzelf bij jouw backend met precies één van vier methodes, die je kiest bij het koppelen. Bij elk verzoek stuurt Ragently de bijbehorende header mee — jouw backend controleert die.

Bij OAuth2 haalt Ragently zelf een access-token op via de client-credentials-grant bij jouw token_url, cachet dat token en ververst het op tijd (60 s marge vóór expiry).

• HTTPS verplicht — je base-URL en token_url moeten via TLS bereikbaar zijn.
• Secrets veilig opgeslagen — Ragently bewaart je auth-gegevens versleuteld en gebruikt ze uitsluitend server-side; ze komen nooit in de browser of in de chat terecht.
• Server-to-server — alle verzoeken komen van Ragently's backend, niet van de bezoeker; jouw backend hoeft niet publiek vanuit de browser bereikbaar te zijn.
• Juiste statuscodes — geef 2xx bij succes, 404 voor een ontbrekende resource en een andere 4xx/5xx bij fouten (zie Error Handling).
• Inputvalidatie — vertrouw geen enkele parameter blind; valideer identifiers, hoeveelheden en bedragen server-side.
• Least privilege — declareer alleen de capabilities die je écht nodig hebt. Niet-gedeclareerde endpoints worden nooit aangeroepen.
• 404-conventie — bestaat een resource niet, geef dan 404; de body wordt in dat geval genegeerd.

Het manifest is de response van GET /.well-known/ragently. Het veld capabilities bepaalt exact welke overige endpoints Ragently zal aanroepen. Onbekende capability-strings filtert Ragently stilzwijgend weg; de gedeclareerde set wordt nooit zelf verbreed.

{
  "version": "1.0.0",
  "capabilities": [
    "platform.info",
    "orders.read",
    "refunds.create",
    "products.read",
    "catalog.sync"
  ]
}

Afhankelijkheidsregels

Sommige capabilities resolven intern via een andere capability (ze roepen bijvoorbeeld eerst GET /orders/find aan). Die onderliggende afhankelijkheid hoef je niet apart te declareren, maar je moet het onderliggende endpoint wel implementeren:

Hieronder een overzicht per capability. De volledige, interactieve reference met alle parameters, requestbodies en responseschema's staat op een aparte pagina, aangedreven door de OpenAPI-spec.

Als representatief voorbeeld: GET /orders/find. Dit is doorgaans de eerste stap van vrijwel elke order-, refund- en return-tool — het resolvet een menselijke identifier (ordernummer, #naam, GID of vrije zoekterm) naar een interne order-id. Hieronder zie je exact hoe Ragently jouw endpoint aanroept, in vijf talen, plus de response die je backend hoort terug te geven.

curl -G "https://your-backend.example.com/orders/find" \
  --data-urlencode "identifier=#1001" \
  -H "Authorization: Bearer YOUR_TOKEN"

const res = await fetch(
  "https://your-backend.example.com/orders/find?" +
    new URLSearchParams({ identifier: "#1001" }),
  { headers: { Authorization: "Bearer YOUR_TOKEN" } }
);

if (res.status === 404) {
  // geen order gevonden
} else if (res.ok) {
  const order = await res.json();
  console.log(order.name, order.displayFulfillmentStatus);
}

import requests

res = requests.get(
    "https://your-backend.example.com/orders/find",
    params={"identifier": "#1001"},
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    timeout=10,
)

if res.status_code == 404:
    order = None            # niet gevonden
else:
    res.raise_for_status()
    order = res.json()
    print(order["name"], order["displayFulfillmentStatus"])

using System.Net;
using System.Net.Http.Json;

var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", "YOUR_TOKEN");

var url = "https://your-backend.example.com/orders/find" +
          "?identifier=" + Uri.EscapeDataString("#1001");

var res = await http.GetAsync(url);
if (res.StatusCode == HttpStatusCode.NotFound)
{
    // geen order gevonden
}
else
{
    res.EnsureSuccessStatusCode();
    var order = await res.Content.ReadFromJsonAsync<OrderInfo>();
}

<?php
$identifier = '#1001';
$url = 'https://your-backend.example.com/orders/find?identifier='
     . rawurlencode($identifier);

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer YOUR_TOKEN'],
]);
$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 404) {
    $order = null;              // niet gevonden
} else {
    $order = json_decode($body, true);
}

Response (200) die jouw backend teruggeeft

De canonieke OrderInfo-vorm. Dezelfde vorm geldt ongeacht welk order-endpoint hem teruggeeft. Bestaat de order niet, geef dan 404 met een lege body.

{
  "id": "ord_10482",
  "name": "#1001",
  "email": "klant@example.com",
  "phone": "+31612345678",
  "displayFinancialStatus": "PAID",
  "displayFulfillmentStatus": "UNFULFILLED",
  "createdAt": "2026-07-20T14:03:11+00:00",
  "customer": {
    "id": "cust_774",
    "email": "klant@example.com",
    "first_name": "Sanne",
    "last_name": "de Vries"
  },
  "shippingAddress": {
    "address1": "Damrak 1",
    "city": "Amsterdam",
    "zip": "1012 LG",
    "country": "Netherlands"
  },
  "fulfillments": [],
  "lineItems": [
    { "id": "li_1", "name": "Blauw T-shirt (M)", "quantity": 2 }
  ]
}

En de manier waarop je backend zo'n verzoek in code afhandelt (voorbeeld in Python / Flask) — let op de 404 bij een onbekende identifier:

from flask import Flask, request, jsonify, abort

app = Flask(__name__)

@app.get("/orders/find")
def find_order():
    # Ragently authenticeert zich met de door jou gekozen methode.
    require_auth(request)                      # valideer bv. de Bearer-token

    identifier = request.args.get("identifier", "").strip()
    order = lookup_order(identifier)           # jouw eigen ERP/DB-opzoeking
    if order is None:
        abort(404)                             # niet gevonden -> body genegeerd

    return jsonify({
        "id": order.id,
        "name": order.number,                 # bv. "#1001"
        "email": order.email,
        "displayFinancialStatus": order.financial_status,
        "displayFulfillmentStatus": order.fulfillment_status,
        "createdAt": order.created_at.isoformat(),
        "lineItems": [
            {"id": li.id, "name": li.name, "quantity": li.qty}
            for li in order.line_items
        ],
    })

• 404 — de resource is niet gevonden. De body wordt genegeerd; alleen de statuscode telt. Bij schrijf-endpoints zet de connector dit intern om naar { "success": false, "error": "not_found" }.
• Elke andere niet-2xx (4xx/5xx) wordt geïnterpreteerd als een fout.
• Alle 2xx-responses moeten application/json zijn.

Geef bij een fout bij voorkeur een JSON-body met een error-veld mee:

{
  "error": "order is already fully shipped"
}

De exacte inhoud van error wordt buiten logging/foutmeldingen om niet machinaal geparsed — een leesbare boodschap volstaat.

• Declareer alleen wat je implementeert — het manifest is je contract; ongebruikte capabilities weglaten voorkomt onnodige aanroepen en foutkansen.
• Retourneer de canonieke velden — houd je aan de responseschema's (bv. OrderInfo, RefundableLineItem) inclusief de exacte sleutelnamen; sommige tools lezen die keys direct.
• Altijd HTTPS — voor je base-URL én je token_url.
• Wees rate-limit-vriendelijk — paginerende endpoints (/catalog/products, /abandoned-checkouts) worden herhaald aangeroepen tot je een lege lijst teruggeeft; antwoord snel en consistent.
• Test met de dashboard-testknop — gebruik „verbinding testen” bij Integraties om je manifest en de leesprobe te valideren voordat je live gaat.