AsistentiAIAsistentiAI
ShqipEnglishItaliano
← Indietro

Specifica del Connettore AsistentiAI v1

AsistentiAI risponde ai clienti della tua azienda 24/7. Per dare loro informazioni in tempo reale — lo stato dell'ordine, le giacenze — l'agente deve leggere dal tuo sistema. Invece di scrivere un'integrazione separata per ogni ERP, implementi tu (oppure lo facciamo noi, come servizio) un unico ponte HTTP/JSON leggero secondo questa specifica. Le piattaforme più diffuse (WooCommerce, WordPress) hanno connettori già pronti.

Principi

Autenticazione

Scegli uno dei due metodi (lo imposti quando richiedi il collegamento nel pannello):

1. Token Bearer

Authorization: Bearer <token>

2. Firma HMAC-SHA256 (consigliata)

X-AAI-Key:       <id della chiave>
X-AAI-Timestamp: <secondi unix>
X-AAI-Signature: hex( HMAC-SHA256( secret, timestamp + "." + METHOD + "." + pathWithQuery + "." + sha256hex(body) ) )

Esempio (GET /orders/1234?phone=0691234567, corpo vuoto):
  messaggio = "1727100000.GET./orders/1234?phone=0691234567." + sha256hex("")
Rifiuta le richieste con un timestamp più vecchio di 5 minuti.

Endpoint

Tutti relativi all'URL di base che ci fornisci (ad es. https://erp.azienda.it/asistentiai). Le risposte sono sempre in JSON.

GET /health

200  { "ok": true, "capabilities": ["orders.read", "stock.read"] }
     // "capabilities" (facoltativo): cosa implementa il tuo ponte

GET /orders/{numero}?phone=…&email=…

Restituisce l'ordine SOLO se il telefono (ultime 8 cifre) o l'email corrisponde all'ordine.

200  { "found": true, "verified": true,
       "order": {
         "number": "1234",
         "status": "processing",            // pending | processing | on-hold | completed | cancelled | refunded | failed | shipped | delivered | returned
         "statusLabel": "In preparazione",  // facoltativo, nella lingua del cliente — se manca, traduciamo noi il codice di stato
         "date": "2026-09-20",
         "total": "1700", "currency": "ALL",
         "items": [ { "name": "Soffiatore elettrico 48V", "qty": 1 } ],
         "shipping": "Corriere", "tracking": "AL123456789", "city": "Fier"
       } }
200  { "found": true, "verified": false }   // l'ordine esiste ma il contatto non corrisponde (oppure 403)
404  { "found": false }

GET /stock/{sku}

200  { "sku": "A2105", "name": "Fryrës elektrik 48V", "inStock": true, "quantity": 12, "price": "1400 L",
       "locations": [ { "name": "Tiranë", "qty": 7 }, { "name": "Durrës", "qty": 3 }, { "name": "Fier", "qty": 2 } ] }
     // "locations" (facoltativo): giacenza per negozio / magazzino
404  { "found": false }

POST /orders v1.1 — in arrivo

{ "customer": { "name": "…", "phone": "…", "email": "…", "address": "…", "city": "…" },
  "items": [ { "sku": "A2105", "qty": 1 } ],
  "note": "…", "source": "asistentiai", "conversationId": "…" }
→ 201  { "number": "1235", "status": "pending" }

Codici di errore

API di AsistentiAI — il tuo sistema ci invia i dati

La direzione opposta: invece di essere noi a interrogare il tuo sistema, è il tuo sistema (ERP, negozio) a inviarci i dati. L'Owner di AsistentiAI crea una chiave API per la tua azienda e te la consegna; la chiave appartiene solo a quell'azienda e ha solo le capacità che le sono state concesse. Può essere revocata in qualsiasi momento.

Authorization: Bearer aai_live_…

GET /api/v1/ping

Test del collegamento: a quale azienda appartiene la chiave e quali capacità ha.

GET https://asistentiai.com/api/v1/ping
200  { "ok": true, "api": "asistentiai/v1", "business": "Dyqani Elegance", "key": "ERP i dyqanit", "scopes": ["stock.write"] }

POST /api/v1/stock stock.write

Giacenze per SKU, anche per negozio/magazzino. Invia solo le modifiche oppure l'intero elenco tutte le volte che vuoi; viene conservato l'ultimo stato. Compare subito nel pannello delle conversazioni → Create order.

POST https://asistentiai.com/api/v1/stock
{ "items": [
    { "sku": "A4543", "quantity": 221,
      "locations": [ { "name": "Tiranë", "qty": 221 }, { "name": "Durrës", "qty": 45 } ] },
    { "sku": "A0099", "inStock": false }
] }
200  { "ok": true, "saved": 2, "rejected": [] }        // fino a 1000 elementi per richiesta
GET  https://asistentiai.com/api/v1/stock?sku=A4543   → ciò che abbiamo salvato

Errori: 401 chiave mancante o revocata · 403 la chiave non ha questa capacità · 429 più di 120 richieste al minuto.

Ambiente di prova (sandbox)

Un'implementazione di riferimento di questa specifica, con dati fittizi, per confrontare il tuo ponte e provare il collegamento nel pannello senza un sistema reale:

URL di base:    https://asistentiai.com/api/connector-demo
Token (Bearer): demo-asistentiai-2026
HMAC:           X-AAI-Key = demo · secret = demo-secret-asistentiai-2026

Ordini:  1234 (telefono 0691234567 / email demo@asistentiai.com) → spedito, tracking AL123456789
         1235 (telefono 0682223344 / email klienti@shembull.al) → in preparazione
Stock:   A2105 → disponibile (12 pezzi) · B2201 → esaurito

curl -H "Authorization: Bearer demo-asistentiai-2026" \
  "https://asistentiai.com/api/connector-demo/orders/1234?phone=0691234567"

Come si attiva

  1. Implementa /health, /orders/{numero} e (facoltativamente) /stock/{sku} nel tuo sistema, con uno dei metodi di autenticazione.
  2. L'Amministratore dell'azienda, nel pannello → Data connections → Internal system / ERP, inserisce l'URL di base e il token o la chiave HMAC. AsistentiAI esegue una chiamata /health per verificarlo.
  3. La piattaforma AsistentiAI approva il collegamento e attiva le capacità (stato degli ordini, giacenze). Da quel momento l'agente le usa automaticamente nelle conversazioni.

Domande o aiuto per l'implementazione: scrivi al team di AsistentiAI dal pannello. Possiamo costruire noi il ponte per te, come servizio.