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.

Principles

Read-only in v1. AsistentiAI changes nothing in your system. Order creation (POST /orders) is reserved for v1.1 and is enabled only with your explicit approval.
Customer privacy. An order's status is returned only when the order number matches the phone or email the customer gives — you perform the verification on your side.
Every call comes from AsistentiAI's servers, authenticated (token or HMAC signature), with a 12-second timeout. The connection is activated only after the AsistentiAI platform approves it.

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 }

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" }
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

401 — invalid authentication (the agent tells the customer the team will check).
404 — the order/product does not exist.
429 / 5xx — temporarily unavailable; AsistentiAI does not retry within the same conversation and records it in the connection's events.

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

Implement /health, /orders/{number} and (optionally) /stock/{sku} in your system, with one of the authentication methods.
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.
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.