REST Context API

Questa API serve per recuperare in una singola chiamata il contesto utente (profilo + ordini + carrello), orchestrando internamente le chiamate MCP verso il tenant. Supporta l'identificazione del cliente tramite user_id (diretto) oppure tramite phone (lookup via telefono).

Endpoint

GET /getUserContext
GET /health
GET /stats

Auth

X-SalesMate-Key: <MCP_API_KEY>

Query params (GET /getUserContext)

parametro	tipo	obbligatorio	descrizione
tenant_id	string	sì	ID tenant configurato nel MCP (es. testwc)
user_id	int	XOR con phone	ID utente/cliente diretto nel tenant
phone	string	XOR con user_id	Numero di telefono (qualsiasi formato, viene normalizzato E.164 dal server)
session_id	string	sì	ID sessione applicativa lato client (per invalidazione cache)

Regola: specifica esattamente uno tra user_id e phone. Se specifichi phone, il server normalizza il numero, cerca il cliente tramite tool get_customer_by_phone e poi procede con il flusso standard.

Comportamento

- Esegue 3 tool call: get_customer_profile + list_customer_orders + get_cart
- Cache in-memory customer+orders per (tenant_id, user_id) finché session_id non cambia
- Lookup telefono: cache (tenant_id, phone_norm) → user_id con TTL 24h (configurabile PHONE_LOOKUP_CACHE_TTL)
- Stato risposta:
    • 400 INVALID_IDENTIFIER → entrambi o nessuno di user_id/phone
    • 400 INVALID_PHONE      → formato telefono non valido
    • 404 CUSTOMER_NOT_FOUND_BY_PHONE → telefono non associato a nessun cliente
    • 409 CUSTOMER_PHONE_AMBIGUOUS → telefono associato a più clienti sul tenant
    • 200 → successo

Schema response (200)

{
  "user_id": 3,
  "resolved_by": "user_id" | "phone",
  "customer": { "tool_name":"get_customer_profile","success":true,"data":{...} },
  "orders":   { "tool_name":"list_customer_orders","success":true,"data":[...] },
  "cart":     { "tool_name":"get_cart","success":true,"data":{...} }
}

Esempio 1 — ID diretto (back compat)

curl -sS "http://localhost:8002/getUserContext?tenant_id=testwc&user_id=3&session_id=sess_1" \
  -H "X-SalesMate-Key: <MCP_API_KEY>" | jq .

Esempio 2 — per telefono

curl -sS "http://localhost:8002/getUserContext?tenant_id=testwc&phone=3331234567&session_id=sess_1" \
  -H "X-SalesMate-Key: <MCP_API_KEY>" | jq .

curl -sS -G "http://localhost:8002/getUserContext" \
  --data-urlencode "tenant_id=testwc" \
  --data-urlencode "phone=+39 333 123 4567" \
  --data-urlencode "session_id=sess_1" \
  -H "X-SalesMate-Key: <MCP_API_KEY>" | jq .

Swagger/OpenAPI interattivo

GET  /openapi.json
GET  /docs           ← Swagger UI della REST

Nota: esempi usano la porta 8002 tipica del setup locale. In produzione la base URL dipende dal deployment.