API Docs E-MatriX

Ghid complet pentru integrarea cu platforma E-MatriX. Conectează magazinul tău, automatizează apeluri AI, confirmări comenzi prin WhatsApp și call center cu agenți inteligenți.

Autentificare

Toate cererile către API-ul E-MatriX necesită un token criptat AES-256-GCM, generat din Confirmare Comenzi → Setări → Webhook Generator. Token-ul include user-ul, magazinul și o semnătură HMAC anti-tampering.

Header de autentificare

POST /webhook/universal.php
Host: e-matrix.ro
Content-Type: application/json
X-EMX-Token: eyJhbGciOiJBRVMtMjU2LUdDTSIsInR5cCI6IkpXRSJ9...

Rate limits

Pentru a proteja platforma, fiecare cont are limite per minut pe categorii diferite de endpoint-uri:

REST API — autentificare Bearer

Endpoint-urile REST (/dashboard/api_td/*) acceptă două forme de autentificare:

1. Sesiune dashboard — atunci când userul e logat în browser (cookie). Folosit de UI.
2. Bearer token — pentru integrări server-side. Format: emx_ + 64 hex characters.

Cum obții un token

Header de autentificare

GET /dashboard/api_td/agents.php HTTP/1.1
Host: e-matrix.ro
Authorization: Bearer emx_a1b2c3d4e5f6...

Revocare

POST către /dashboard/api_td/tokens_revoke.php cu {"id":<token_id>}. Token-ul devine instant invalid pe toate procesele.

Catalog endpoint-uri

Toate endpoint-urile rulează scoped la user_id-ul derivat din token / sesiune — un user nu poate accesa date altui user. Răspunsurile sunt application/json. Toate POST-urile acceptă Content-Type: application/json.

Agenți

Contacte & apeluri

Knowledge base

Calendar & statistici

Voci, integrări, profil

Tokens & webhooks management

Erori & status codes

Toate erorile au format consistent JSON:

{
  "ok": false,
  "error": "NOT_LOGGED_IN",
  "hint": "Autentifică-te în /dashboard/ sau trimite header Authorization: Bearer <token>."
}

Webhooks & Events — abonare la evenimente

E-MatriX poate notifica server-ul tău în timp real când se întâmplă lucruri în platformă: un apel finalizat, o comandă confirmată, un lead nou. Te abonezi la unul sau mai multe evenimente și primești POST JSON cu HMAC SHA-256 la URL-ul tău.

Cum configurezi

1. Mergi în API Playground → secțiunea Webhooks & Evenimente
2. Click + Webhook nou și completează: nume, URL țintă (HTTPS recomandat), evenimente
3. Copiază secret-ul whsec_… afișat o singură dată — îl folosești pentru a verifica semnătura
4. Click ▶ Test ca să confirmi că serverul tău primește payload-ul corect

Catalog evenimente

Lista completă a evenimentelor emise de platformă. Selectezi în Playground exact pe care vrei să le primești, sau bifezi „Toate" (*).

Verificare semnătură HMAC

Fiecare POST de la noi include un header X-EMatrix-Signature: sha256=<hex>. Semnătura se calculează ca HMAC_SHA256(secret, raw_request_body) și trebuie validată la primire pentru a confirma că request-ul vine de la E-MatriX.

Headers trimise de E-MatriX

POST /tu/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: e-matrix-webhook/1.0
X-EMatrix-Event: call.completed
X-EMatrix-Delivery: 9a3f7b2c5d8e1f04
X-EMatrix-Signature: sha256=4f5b8a2c...c1d9e7

Verificare în Node.js

import crypto from 'crypto';
import express from 'express';
const app = express();

app.post('/webhook', express.raw({type:'application/json'}), (req, res) => {
  const sig = req.headers['x-ematrix-signature'] || '';
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.WHSEC)
    .update(req.body)
    .digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body.toString('utf8'));
  console.log(event.event, event.data);
  res.sendStatus(200);
});

Verificare în PHP

<?php
$body = file_get_contents('php://input');
$sig  = $_SERVER['HTTP_X_EMATRIX_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $body, getenv('WHSEC'));
if (!hash_equals($expected, $sig)) {
    http_response_code(401);
    exit('Invalid signature');
}
$event = json_decode($body, true);
// $event['event'], $event['data'], $event['timestamp'], $event['user_id']
http_response_code(200);

Payload & retry policy

Toate event-urile au aceeași structură de wrapper:

{
  "event": "call.completed",
  "timestamp": "2026-06-01T18:42:11+00:00",
  "user_id": 53,
  "webhook_id": 7,
  "data": {
    "call_id": 18234,
    "contact_id": 901,
    "agent_id": "preset-12",
    "duration_sec": 47,
    "status_client": "interesat",
    "transcript_url": "/dashboard/api_td/conversation.php?convid=..."
  }
}

Retry

• Timeout per livrare: 6 secunde (connect 3s + read 3s).
• Răspuns OK: HTTP 2xx. Orice altceva = failure → contor total_failures incrementat.
• Retry automat: nu (la momentul actual). Folosește butonul ▶ Test + logul de livrări din Playground pentru debugging.
• Tu poți răspunde 200 imediat și procesa async — recomandăm enqueue rapid + 200, nu procesare sincronă.

Idempotency

Headerul X-EMatrix-Delivery e unic per livrare — folosește-l ca dedup key dacă vrei să fii safe în caz de redelivery manuală (via butonul Test).

Webhook Universal — Overview

E-MatriX folosește un Webhook Universal pentru a primi comenzi din orice magazin online. Indiferent dacă platforma ta e Shopify, WooCommerce, Gomag, OpenCart sau custom, payload-ul se normalizează automat și ajunge în pipeline-ul de confirmări comenzi (WhatsApp + apel AI).

Criptare AES-256-GCM

Toate token-urile trec printr-un strat de criptare autentică. Asta înseamnă că payload-ul nu doar e ascuns, ci și verificat — orice modificare invalidează token-ul automat.

Anatomy a token-ului

eyJhbGciOiJBRVMtMjU2LUdDTSIsInR5cCI6IkpXRSJ9...

Structura payload

După ce primește un webhook, E-MatriX normalizează payload-ul indiferent de platformă. Iată structura canonică:

{
  "order_id": "ORD-12345",
  "shop_name": "Magazinul Meu",
  "customer": {
    "first_name": "Ion",
    "last_name": "Popescu",
    "email": "[email protected]",
    "phone": "+40712345678"
  },
  "products": [
    { "sku": "TSHIRT-RED-M", "name": "Tricou Rosu", "qty": 2, "price": 89.99 }
  ],
  "totals": {
    "subtotal": 179.98,
    "shipping": 19.99,
    "total": 199.97,
    "currency": "RON"
  },
  "shipping_address": {
    "city": "Bucuresti",
    "county": "Bucuresti",
    "address": "Strada Exemplu 1",
    "postcode": "010101"
  },
  "metadata": { "source": "shopify", "received_at": "2026-04-07T12:00:00Z" }
}

Exemple per platformă

// Shopify Admin → Settings → Notifications → Webhooks
// Event: Order creation
// Format: JSON
// URL: https://e-matrix.ro/webhook/universal.php?token=YOUR_TOKEN

// WooCommerce → Settings → Advanced → Webhooks
// Topic: Order created
// Delivery URL:
https://e-matrix.ro/webhook/universal.php?token=YOUR_TOKEN

// Sau via WP filter:
add_action('woocommerce_thankyou', function($order_id){
    wp_remote_post('https://e-matrix.ro/webhook/universal.php', [
        'headers' => ['X-EMX-Token' => 'YOUR_TOKEN'],
        'body'    => json_encode(wc_get_order($order_id)->get_data()),
    ]);
});

// Gomag Admin → Marketplace → Caută "E-MatriX"
// Sau Setări → Integrări → Adaugă webhook:
//   URL: https://e-matrix.ro/webhook/universal.php?token=YOUR_TOKEN
//   Eveniment: comanda_noua
//   Format: JSON

curl -X POST https://e-matrix.ro/webhook/universal.php \
  -H "X-EMX-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TEST-001",
    "customer": { "first_name": "Test", "phone": "+40712345678" },
    "products": [{ "name": "Demo", "qty": 1, "price": 99 }],
    "totals": { "total": 99, "currency": "RON" }
  }'

Integrare META — WhatsApp Business

Conectează contul tău WhatsApp Business prin Meta OAuth. După conectare, poți trimite template-uri aprobate, gestiona conversații cu agenți AI și primi notificări webhook.

Setup rapid

• Mergi în Dashboard → WhatsApp → Conectare
• Click pe Connect with Meta și autorizează aplicația
• Selectează numărul WABA pe care vrei să-l conectezi
• Configurează webhook-ul de mesaje (automat) și salvează

WhatsApp Templates

Template-urile sunt mesaje pre-aprobate de Meta pe care le poți trimite oricărui contact. Endpoint-ul de trimitere:

{
  "to": "+40712345678",
  "template_name": "order_confirmation_v2",
  "language": "ro",
  "variables": {
    "1": "Ion Popescu",
    "2": "ORD-12345",
    "3": "199.97 RON"
  }
}

Webhook Meta (incoming messages)

E-MatriX expune un endpoint pentru a primi mesaje WhatsApp în timp real:

Acest URL trebuie configurat în Meta Business Manager → WABA → Configuration → Webhook URL.

Inițiere apel AI

Pornește un batch de apeluri către lead-uri. Apelurile sunt puse într-o coadă și trimise la ElevenLabs respectând intervalul orar al user-ului.

{
  "contact_ids": [1024, 1025, 1026],
  "agent_id": "agent_abc123",
  "max_duration": 180,
  "voice_id": "voice_xyz789"
}

Status apel

Returnează statusul curent al unui apel: in_asteptare, processing, apelat, ocupat, eroare.

Transcrieri

Returnează transcrierea completă a unei conversații, message-by-message, cu timestamps și clasificare client (interesat / callback / nu_e_interesat).

Flow Confirmare Comenzi

Când o comandă ajunge prin Webhook Universal:

1. Payload normalizat → salvat în orderconfirm_orders
2. Trimite WhatsApp template order_confirmation (dacă e configurat)
3. Așteaptă răspuns client X minute (config user)
4. Dacă nu răspunde → inițiere apel AI cu agentul OC
5. Agentul AI cheamă Standard_CallConfirm_Tool la final cu rezultatul
6. Status final → confirmat / anulat / reprogramat

Standard_CallConfirm_Tool

Acest tool este injectat automat în orice agent ElevenLabs creat pentru confirmare comenzi. Schema lui este fixă:

{
  "name": "Standard_CallConfirm_Tool",
  "description": "Apelat la finalul conversatiei cu rezultatul confirmarii.",
  "parameters": {
    "userid":  { "type": "integer", "description": "ID-ul user-ului E-MatriX" },
    "orderid": { "type": "string",  "description": "ID-ul comenzii" },
    "llmwrited":{ "type": "string", "enum": ["confirmat","anulat","reprogramat","nu_raspunde","ocupat"] },
    "note":     { "type": "string", "description": "Note libere de la agent" }
  }
}

SDK PHP

$ch = curl_init('https://e-matrix.ro/webhook/universal.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'X-EMX-Token: ' . getenv('EMX_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'order_id' => 'ORD-001',
        'customer' => ['phone' => '+40712345678'],
        'totals'   => ['total' => 199.99, 'currency' => 'RON'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$res = curl_exec($ch);

SDK Node.js

import fetch from 'node-fetch';

const r = await fetch('https://e-matrix.ro/webhook/universal.php', {
  method: 'POST',
  headers: {
    'X-EMX-Token': process.env.EMX_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    order_id: 'ORD-001',
    customer: { phone: '+40712345678' },
    totals: { total: 199.99, currency: 'RON' },
  }),
});
console.log(await r.json());

SDK Python

import os, requests

r = requests.post(
    'https://e-matrix.ro/webhook/universal.php',
    headers={'X-EMX-Token': os.environ['EMX_TOKEN']},
    json={
        'order_id': 'ORD-001',
        'customer': {'phone': '+40712345678'},
        'totals': {'total': 199.99, 'currency': 'RON'},
    },
    timeout=10,
)
print(r.json())