Raccomando Client API

Gebruik de Raccomando Client API om zoeken, autocomplete en aanbevelingen te voeden in je storefront.

Basis-URL

https://api.raccomando.ai

Authenticatie

Gebruik een actieve client API-sleutel via de header X-API-Key.
Gebruik X-Request-ID voor traceerbaarheid (optioneel).

X-API-Key: rck_live_<keyId>.<secret>
X-Request-ID: 99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2

Responseformaat

Alle responses gebruiken een vaste structuur met requestId en metadata.

{
  "apiVersion": "v1",
  "requestId": "99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2",
  "data": {},
  "meta": {}
}

Runtime endpoints

POST/client/v1/search

Zoekt producten op basis van klantquery met ranking.

GET/client/v1/suggest

Haalt autocomplete suggesties op voor een gedeeltelijke query.

POST/client/v1/recommend

Returneert aanbevelingen op basis van anchor, winkelwagen of query.

POST/client/v1/events

Verstuur interactiegebeurtenissen zoals impressies en klikken.

POST/client/v1/events/single

Verstuur een enkele interactiegebeurtenis.

Zoeken

`POST /client/v1/search`

Voer semantisch zoeken uit met optionele filters en pipeline-instellingen.

{
  "query": "dry red under 20 euro",
  "sessionId": "sess-123",
  "page": 0,
  "size": 20,
  "filter": {
    "clauses": [
      {
        "scope": "ATTRIBUTE",
        "field": "country",
        "operator": "EQ",
        "valueType": "STRING",
        "values": ["france"]
      },
      {
        "scope": "CORE",
        "field": "price",
        "operator": "RANGE",
        "valueType": "NUMBER",
        "min": 0,
        "max": 20
      }
    ]
  }
}

{
  "apiVersion": "v1",
  "requestId": "99f2d0bf-f3d8-4f28-9dcf-1af5aa7c4ca2",
  "data": {
    "hits": [
      {
        "id": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
        "externalId": "81",
        "title": "2024 Doisy-Daene Bordeaux Blanc",
        "imageUrl": "https://cdn.example.com/81.jpg",
        "status": true,
        "price": 24.50,
        "attributes": { "country": "france", "region": "bordeaux" },
        "score": 0.717
      }
    ],
    "pageInfo": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 },
    "queryFeedback": {
      "originalQuery": "wijn uit frankrijk",
      "parsedQuery": "wijn",
      "extractedFilter": {
        "clauses": [
          {
            "scope": "ATTRIBUTE",
            "field": "country",
            "operator": "EQ",
            "valueType": "STRING",
            "values": ["frankrijk"],
            "min": null,
            "max": null
          }
        ]
      }
    }
  },
  "meta": { "page": 0, "size": 20, "totalElements": 1, "totalPages": 1 }
}

Suggesties

`GET /client/v1/suggest?query=bor&sessionId=sess-123&size=8`

{
  "apiVersion": "v1",
  "requestId": "8f72556e-3f34-4e6e-93a8-f72e287a5fd4",
  "data": {
    "items": [
      {
        "query": "Bordeaux",
        "label": "Bordeaux",
        "kind": "PRODUCT_TITLE",
        "productId": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
        "attributeKey": null
      },
      {
        "query": "Bordeaux",
        "label": "Region: Bordeaux",
        "kind": "ATTRIBUTE_VALUE",
        "productId": null,
        "attributeKey": "region"
      }
    ]
  }
}

Aanbevelen

`POST /client/v1/recommend`

{
  "strategyId": "10f2e7c8-9d56-4277-9f3a-986af577d786",
  "anchorProductId": "f4546d03-f3a9-4c03-a97d-901f9ec7f6d4",
  "cartProductIds": [],
  "query": null,
  "context": { "slot": "pdp" },
  "filters": { "country": "france" },
  "limit": 12
}

{
  "apiVersion": "v1",
  "requestId": "9a8fab42-4f7f-49ce-97e4-a298a6e16db0",
  "data": {
    "items": [
      {
        "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
        "score": 1.283,
        "title": "Chateau Carbonnieux Rouge",
        "price": 19.95
      }
    ]
  }
}

Gebeurtenissen

`POST /client/v1/events`

{
  "events": [
    {
      "type": "IMPRESSION",
      "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
      "sessionId": "sess-123",
      "payload": { "strategyId": "10f2e7c8-9d56-4277-9f3a-986af577d786" },
      "timestamp": "2026-02-16T10:40:32"
    },
    {
      "type": "CLICK",
      "productId": "ec5c7f34-3ef4-4ab1-a5af-0baec9eef757",
      "sessionId": "sess-123",
      "payload": { "position": 1 },
      "timestamp": "2026-02-16T10:40:40"
    }
  ]
}

{
  "apiVersion": "v1",
  "requestId": "1e7c6b95-f548-4dd7-980f-41834516c290",
  "data": {
    "ingestedCount": 2
  }
}

Foutresponsen

Controleer HTTP-status en foutdetails voor diagnose.

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "X-API-Key header is required",
  "instance": "https://api.raccomando.ai/client/v1/search"
}