AsistentiAIAsistentiAI
ShqipEnglishItaliano
← Kthehuni

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. Për WordPress-in dhe WooCommerce-in, chat-i shtohet me plugin-in tonë zyrtar falas AsistentiAI Chat në WordPress.org.

Parimet

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, "capabilities": ["orders.read", "stock.read"] }
     // "capabilities" (optional / opsionale): what your bridge implements / çfarë zbaton ura juaj

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",
       "locations": [ { "name": "Tiranë", "qty": 7 }, { "name": "Durrës", "qty": 3 }, { "name": "Fier", "qty": 2 } ] }
     // "locations" (optional / opsionale): stock per store / warehouse — gjendja sipas dyqaneve / magazinave
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

API e AsistentiAI — sistemi juaj na dërgon të dhëna

Drejtimi i kundërt: në vend që ne të pyesim sistemin tuaj, sistemi juaj (ERP, dyqan) na dërgon vetë të dhënat. Owner-i i AsistentiAI krijon një çelës API për biznesin tuaj dhe jua jep; çelësi i përket vetëm atij biznesi dhe ka vetëm aftësitë që i janë dhënë. Mund të hiqet në çdo moment.

Authorization: Bearer aai_live_…

GET /api/v1/ping

Prova e lidhjes: cili biznes dhe cilat aftësi ka çelësi.

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

Stoku sipas SKU-së, edhe sipas dyqaneve/magazinave. Dërgoni vetëm ndryshimet ose gjithë listën sa herë të doni; ruhet gjendja e fundit. Del menjëherë te paneli i bisedave → Krijo porosi.

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": [] }        // up to / deri 1000 items per request
GET  https://asistentiai.com/api/v1/stock?sku=A4543   → what we stored / çfarë ruajtëm

Gabimet: 401 çelës i munguar ose i hequr · 403 çelësi s'e ka këtë aftësi · 429 më shumë se 120 kërkesa në minutë.

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

  1. Zbatoni /health, /orders/{numri} dhe (opsionale) /stock/{sku} në sistemin tuaj, me një nga mënyrat e autentikimit.
  2. 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.
  3. 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.