Specifikimi i Lidhësit AsistentiAI v1

AsistentiAI u përgjigjet klientëve të biznesit tuaj 24/7. Për t'u dhënë fakte live — statusin e porosisë, stokun — agjenti duhet të lexojë nga sistemi juaj. Në vend që të shkruhet një integrim i veçantë për çdo ERP, ju (ose ne, si shërbim) zbatoni një urë të hollë HTTP/JSON sipas këtij specifikimi. Platformat e njohura (WooCommerce, WordPress) kanë lidhës të gatshëm.

Parimet

Vetëm lexim në v1. AsistentiAI nuk ndryshon asgjë në sistemin tuaj. Krijimi i porosive (POST /orders) është i rezervuar për v1.1 dhe ndizet vetëm me miratimin tuaj të shprehur.
Privatësia e klientit. Statusi i një porosie kthehet vetëm kur numri i porosisë përputhet me telefonin ose email-in që jep klienti — ju e bëni verifikimin në anën tuaj.
Çdo thirrje vjen nga serverët e AsistentiAI, e autentikuar (token ose nënshkrim HMAC), me afat 12 s. Lidhja aktivizohet vetëm pasi platforma AsistentiAI e miraton.

Autentikimi

Zgjidhni një nga dy mënyrat (e caktoni kur kërkoni lidhjen te paneli):

1. Token (Bearer)

Authorization: Bearer <token>

2. Nënshkrim HMAC-SHA256 (i rekomanduar)

X-AAI-Key:       <id i çelësit>
X-AAI-Timestamp: <unix sekonda>
X-AAI-Signature: hex( HMAC-SHA256( secret, timestamp + "." + METHOD + "." + pathWithQuery + "." + sha256hex(body) ) )

Shembull (GET /orders/1234?phone=0691234567, trup bosh):
  mesazhi = "1727100000.GET./orders/1234?phone=0691234567." + sha256hex("")
Refuzoni kërkesa me vulë kohore më të vjetër se 5 minuta.

Pikat fundore (endpoints)

Të gjitha relative ndaj adresës bazë që na jepni (p.sh. https://erp.kompania.al/asistentiai). Përgjigjet gjithmonë JSON.

GET /health

200  { "ok": true }

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

Kthen porosinë VETËM nëse telefoni (8 shifrat e fundit) ose email-i përputhet me porosinë.

200  { "found": true, "verified": true,
       "order": {
         "number": "1234",
         "status": "processing",            // pending | processing | on-hold | completed | cancelled | refunded | failed | shipped | delivered | returned
         "statusLabel": "Po përgatitet",    // opsionale, shqip — nëse mungon, e përkthejmë ne
         "date": "2026-09-20",
         "total": "1700", "currency": "ALL",
         "items": [ { "name": "Fryres Elektrik 48V", "qty": 1 } ],
         "shipping": "Korrier", "tracking": "AL123456789", "city": "Fier"
       } }
200  { "found": true, "verified": false }   // porosia ekziston, kontakti s'përputhet (ose 403)
404  { "found": false }

GET /stock/{sku}

200  { "sku": "A2105", "name": "Fryrës elektrik 48V", "inStock": true, "quantity": 12, "price": "1400 L" }
404  { "found": false }

POST /orders v1.1 — së shpejti

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

Kodet e gabimit

401 — autentikim i pavlefshëm (agjenti i thotë klientit që ekipi e kontrollon).
404 — porosia/produkti nuk ekziston.
429 / 5xx — përkohësisht i padisponueshëm; AsistentiAI nuk e riprovon në të njëjtën bisedë dhe e shënon te ngjarjet e lidhjes.

Mjedisi i provës (sandbox)

Një zbatim referimi i këtij specifikimi, me të dhëna të trilluara, për ta krahasuar urën tuaj dhe për ta provuar lidhjen në panel pa një sistem real:

Adresa bazë:   https://asistentiai.com/api/connector-demo
Token (Bearer): demo-asistentiai-2026
HMAC:           X-AAI-Key = demo · sekreti = demo-secret-asistentiai-2026

Porosi:  1234 (telefoni 0691234567 / email demo@asistentiai.com) → e nisur, gjurmimi AL123456789
         1235 (telefoni 0682223344 / email klienti@shembull.al) → po përgatitet
Stok:    A2105 → në stok (12 copë) · B2201 → jashtë stoku

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

Si aktivizohet

Zbatoni /health, /orders/{numri} dhe (opsionale) /stock/{sku} në sistemin tuaj, me një nga mënyrat e autentikimit.
Administratori i biznesit, te paneli → Lidhjet e të dhënave → Sistem i brendshëm / ERP, jep adresën bazë dhe token-in ose çelësin HMAC. AsistentiAI bën një thirrje /health për ta provuar.
Platforma AsistentiAI e miraton lidhjen dhe ndez aftësitë (statusi i porosive, stoku). Që nga ai çast agjenti i përdor automatikisht në biseda.

Pyetje ose ndihmë për zbatimin: shkruani te ekipi i AsistentiAI nga paneli. Ne mund ta ndërtojmë urën për ju si shërbim.