AsistentiAIAsistentiAI
ShqipEnglishItaliano
← Back

AsistentiAI Connector Specification v1

AsistentiAI answers your business's customers 24/7. To give them live facts — order status, stock — the agent needs to read from your system. Instead of writing a separate integration for every ERP, you (or we, as a service) implement one thin HTTP/JSON bridge following this specification. Well-known platforms (WooCommerce, WordPress) have ready-made connectors. On WordPress and WooCommerce, the chat is added with our free official plugin, AsistentiAI Chat on WordPress.org.

Principles

Authentication

Choose one of the two methods (you set it when requesting the connection in the dashboard):

1. Bearer token

Authorization: Bearer <token>

2. HMAC-SHA256 signature (recommended)

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

Example (GET /orders/1234?phone=0691234567, empty body):
  message = "1727100000.GET./orders/1234?phone=0691234567." + sha256hex("")
Reject requests whose timestamp is older than 5 minutes.

Endpoints

All relative to the base URL you give us (e.g. https://erp.company.com/asistentiai). Responses are always JSON.

GET /health

200  { "ok": true, "capabilities": ["orders.read", "stock.read"] }
     // "capabilities" (optional / opsionale): what your bridge implements / çfarë zbaton ura juaj

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

Returns the order ONLY if the phone (last 8 digits) or the email matches the order.

200  { "found": true, "verified": true,
       "order": {
         "number": "1234",
         "status": "processing",            // pending | processing | on-hold | completed | cancelled | refunded | failed | shipped | delivered | returned
         "statusLabel": "Being prepared",   // optional, in the customer's language — if missing, we translate the status code
         "date": "2026-09-20",
         "total": "1700", "currency": "ALL",
         "items": [ { "name": "Electric blower 48V", "qty": 1 } ],
         "shipping": "Courier", "tracking": "AL123456789", "city": "Fier"
       } }
200  { "found": true, "verified": false }   // the order exists but the contact doesn't match (or 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 — coming soon

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

Error codes

AsistentiAI API — your system sends us data

The reverse direction: instead of us querying your system, your system (ERP, shop) sends us the data itself. The AsistentiAI Owner creates an API key for your business and gives it to you; the key belongs to that business only and has only the capabilities granted to it. It can be revoked at any time.

Authorization: Bearer aai_live_…

GET /api/v1/ping

Connection test: which business and which capabilities the key has.

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

Stock per SKU, optionally per store/warehouse. Send only the changes or the whole list as often as you like; the latest state is kept. It shows up immediately in the conversations panel → 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": [] }        // up to / deri 1000 items per request
GET  https://asistentiai.com/api/v1/stock?sku=A4543   → what we stored / çfarë ruajtëm

Errors: 401 missing or revoked key · 403 the key lacks this capability · 429 more than 120 requests per minute.

Sandbox

A reference implementation of this specification, with fictional data, to compare your bridge against and to try the connection in the dashboard without a real system:

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

Orders:  1234 (phone 0691234567 / email demo@asistentiai.com) → shipped, tracking AL123456789
         1235 (phone 0682223344 / email klienti@shembull.al) → being prepared
Stock:   A2105 → in stock (12 units) · B2201 → out of stock

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

How it gets activated

  1. Implement /health, /orders/{number} and (optionally) /stock/{sku} in your system, with one of the authentication methods.
  2. The business Administrator, in the dashboard → Data connections → Internal system / ERP, enters the base URL and the token or HMAC key. AsistentiAI makes a /health call to test it.
  3. The AsistentiAI platform approves the connection and enables the capabilities (order status, stock). From that moment the agent uses them automatically in conversations.

Questions or help with the implementation: write to the AsistentiAI team from the dashboard. We can build the bridge for you as a service.