Agent comenzi AI: cum conectez propriul bot de chat sau WhatsApp la BOCP (ghid și documentație API)

Introducere

Agentul comenzi AI permite botului de chat al magazinului — de exemplu un bot de WhatsApp sau asistentul de chat de pe site, găzduit de magazin sau de un partener — să răspundă clienților cu date reale din BOCP, în momentul conversației: unde este comanda, dacă s-a emis factura, ce produse sunt în stoc. Botul poate și să înregistreze comenzi noi, care intră în BOCP și așteaptă confirmarea unui operator. Agentul se creează din Conectori AI → Agenți chat, coloana Agenți comenzi.

Acest articol este documentul complet care se poate trimite clientului și dezvoltatorului lui: prima parte explică ce face agentul și ce este necesar, partea a doua este documentația tehnică pentru dezvoltator, iar partea a treia descrie configurarea în BOCP.

Pe aceeași pagină există și agentul de tip OnChat, care doar informează clientul despre stadiul unei comenzi după numărul ei (vezi Integrare OnChat pe magazinul online). Agentul comenzi recunoaște clientul după numărul lui de telefon, vede toate comenzile lui recente, verifică stocul, retrimite factura și poate plasa comenzi. Ambele sunt diferite de Agenții AI (Claude, ChatGPT), care citesc datele firmei pentru analize și rapoarte interne — vezi Cum conectez un asistent AI la BOCP.

Ce poate face agentul

„Unde e comanda mea?” — botul trimite numărul de telefon al clientului și primește cele mai recente 5 comenzi ale lui din ultimele 90 de zile, de la cea mai nouă; comenzile anulate nu apar. Pentru fiecare comandă primește data, stadiul (înregistrată, în procesare, facturată, expediată, livrată sau anulată), dacă s-a emis factura, curierul, numărul AWB, linkul de urmărire a coletului, dacă coletul a fost preluat de curier sau livrat, și produsele comandate cu cantitățile lor. O comandă anume se poate cere și după număr, dar răspunsul vine doar dacă aparține telefonului clientului.
„Retrimiteți-mi factura” — BOCP trimite factura emisă pe adresa de email a clientului înregistrată în BOCP, niciodată pe o adresă comunicată în conversație. Aceeași factură poate fi retrimisă cel mult o dată la 24 de ore.
„Aveți produsul X în stoc?” — după codul produsului sau codul de bare, cu potrivire exactă, în gestiunea aleasă pe agent, doar pentru produsele publicate pe conectorul agentului: stocul, cantitatea rezervată, cantitatea disponibilă și momentul ultimei actualizări. Răspunsul despre stoc nu conține prețuri.
Catalogul — botul poate citi lista produselor publicate pe conectorul agentului, cu denumiri, descrieri, prețuri de vânzare și imagini, ca să recomande produse și să afle codurile de comandă.
„Vreau să comand 2 × X” — botul trimite comanda în BOCP, unde intră în Comenzi eCommerce pe conectorul agentului. Prețurile se iau întotdeauna din catalogul agentului, iar comanda așteaptă confirmarea unui operator înainte de orice procesare.
Notificări despre comenzi — dacă se completează o adresă de notificare pe conectorul agentului, BOCP anunță singur platforma de chat la fiecare eveniment al comenzilor (comandă înregistrată, factură emisă, AWB generat, colet preluat de curier, colet livrat etc.), astfel încât botul îi poate scrie clientului fără să fie întrebat.

Exemple de conversații

Clientul întreabă de comandă

Client (WhatsApp, de pe 0722 123 456): Bună, unde e comanda mea?
În spate: botul cere lista comenzilor clientului, trimițând numărul de telefon al expeditorului WhatsApp (GET …/orders/). BOCP întoarce o comandă din 2 octombrie, cu stadiul shipped, curierul, AWB-ul și linkul de urmărire.
Bot: Comanda 10234 din 2 octombrie a fost predată curierului FAN Courier, AWB 2345678901. O puteți urmări aici: (link). Factura a fost emisă.

Clientul cere factura

Client: Puteți să-mi retrimiteți factura? Nu o găsesc.
În spate: botul cere retrimiterea facturii pentru comanda 10234 (POST …/order/10234/resend_invoice/). BOCP confirmă că emailul a fost pus la trimis.
Bot: Am retrimis factura pe adresa de email din contul dumneavoastră. Dacă nu o vedeți în câteva minute, verificați și dosarul Spam.

Clientul întreabă de stoc și comandă

Client: Aveți cana termos neagră de 500 ml? Aș lua două.
În spate: botul caută produsul în catalog (GET …/products/), află codul CT-500-NEGRU și prețul, apoi verifică stocul (GET …/stock/CT-500-NEGRU/): 14 bucăți disponibile.
Bot: Da, avem în stoc. Două căni costă 179,80 lei. Pe ce adresă le livrăm?
Client: Str. Florilor 12, Cluj-Napoca, Ion Popescu.
În spate: botul plasează comanda (POST …/order/). BOCP răspunde cu numărul intern al comenzii și cu un rezumat: 2 linii primite, 2 linii importate.
Bot: Comanda a fost înregistrată. Un coleg o confirmă în cel mai scurt timp și veți primi un mesaj când pleacă coletul.
Mai târziu: BOCP trimite platformei de chat notificarea awb_issued, iar botul îi scrie clientului numărul AWB și linkul de urmărire.

De ce este nevoie

Abonamentul „Agenți comenzi” pe contul BOCP. Fiecare agent comenzi activ se numără în limita contului. Limita se vede pe pagina Agenți chat, lângă titlul listei Agenți comenzi, și se mărește cu butonul Mărește limita. Agentul comenzi nu necesită abonamentul BOCP REST API.
Un agent comenzi activat, cu gestiunea de stoc aleasă și cu produsele publicate pe conectorul lui (vezi Configurare în BOCP).
Platforma de chat proprie și un dezvoltator. BOCP nu furnizează botul de WhatsApp sau de chat; acesta aparține magazinului sau unui partener, care îl leagă de BOCP folosind documentația de mai jos. Botul poate fi un agent AI (care citește singur adresa de descriere și decide ce să întrebe) sau un program scris clasic.
Opțional, o adresă https publică la care platforma de chat primește notificările despre comenzi.

Pentru dezvoltator: documentația API

Această secțiune este documentația publică a agentului comenzi. Valorile reale (adresa, utilizatorul, parola) se iau din fereastra agentului din BOCP; mai jos sunt înlocuite cu semne de forma {…}.

Autentificare și adresa de bază

Autentificare: HTTP Basic, cu utilizatorul și parola afișate în BOCP în fereastra agentului. Fiecare agent are propria cheie, care funcționează doar pentru acel agent; aceeași cheie se folosește pentru toate adresele de mai jos.
Adresa de bază: https://{adresa-bocp}/app/rest/v1/{id-cont}/aichat/{id-agent}/. Adresa exactă este afișată în fereastra agentului, la API Address, și în caseta Pentru agentul tău AI.
Format: toate răspunsurile sunt JSON, în codificarea UTF-8. Corpul cererilor POST se trimite ca JSON.

curl -u "{utilizator}:{parola}" \
  -H "X-Customer-Phone: 0722123456" \
  https://{adresa-bocp}/app/rest/v1/{id-cont}/aichat/{id-agent}/orders/

Adresa de descriere — se citește prima

GET {adresa-de-baza}describe/ (sau adresa de bază simplă) întoarce specificația exactă și curentă a agentului: modul de autentificare, toate adresele pe care agentul le poate apela, antetele cerute, valorile posibile ale stadiului comenzii, politica de date, un exemplu de comandă și exemple de notificări. Un agent AI trebuie să citească întâi acest document; un program clasic îl poate folosi pentru a verifica dacă s-a schimbat ceva. Fiecare răspuns al agentului poartă și antetul Link: <…/describe/>; rel="describedby", iar erorile de tip „adresă inexistentă” conțin câmpul describe_url.

{
  "is_error": false,
  "http_code": 200,
  "messages": ["Chat agent description"],
  "data_count": 9,
  "data": {
    "agent_id": 7,
    "agent_type": "ordering_agent",
    "authentication": "HTTP Basic, with the API user and password shown in BOCP on this chat agent. One key for every endpoint below.",
    "customer_identification": "Send the phone number of the person writing in header X-Customer-Phone. …",
    "rate_limit_per_minute": 60,
    "order_status_values": ["registered", "in_processing", "invoiced", "shipped", "delivered", "cancelled"],
    "data_policy": "…",
    "webhooks": { "description": "…", "packets": { "status": {…}, "invoice": {…}, "awb": {…} } },
    "endpoints": [ { "method": "GET", "url": "…/describe/", "description": "…" }, … ]
  }
}

Notă: documentul de descriere este în limba engleză, pentru că este citit în primul rând de agenți AI.

Antetul X-Customer-Phone

Clientul este identificat după numărul de telefon trimis în antetul X-Customer-Phone. Numărul trebuie să fie cel al expeditorului verificat, garantat de platforma de chat (de exemplu numărul WhatsApp de pe care scrie clientul), niciodată un număr tastat în conversație. Răspunderea pentru acest lucru aparține platformei de chat. Sunt acceptate formatele uzuale: 0722123456, +40722123456, 0040722123456, 40722123456, cu sau fără spații și liniuțe. Numărul se compară cu telefonul de pe comandă.

Antetul este obligatoriu pentru lista comenzilor, pentru o comandă anume, pentru retrimiterea facturii și pentru plasarea unei comenzi. Nu este necesar pentru stoc, catalog și descriere.

Forma răspunsurilor

Orice răspuns are aceeași formă. La succes: is_error (false), http_code, messages, data_count și data. La eroare: is_error (true), http_code, messages (motivele) și data. Ambele conțin și câmpurile tehnice request_route, your_ip, your_user și your_method, omise în exemplele de mai jos pentru claritate.

Atenție: când o listă nu are niciun rezultat (clientul nu are comenzi, codul nu are stoc), răspunsul are codul HTTP 404, dar is_error este false și data este o listă goală. Nu este o eroare, ci „nu am găsit nimic”.

Lista comenzilor clientului

GET {adresa-de-baza}orders/, cu antetul X-Customer-Phone. Întoarce cele mai recente 5 comenzi ale clientului din ultimele 90 de zile, fără cele anulate, de la cea mai nouă. Dacă se potrivesc mai multe comenzi, botul îl întreabă pe client despre care este vorba.

{
  "is_error": false,
  "http_code": 200,
  "messages": [],
  "data_count": 1,
  "data": [
    {
      "order_number": "10234",
      "order_date": "2026-10-02 14:31:08",
      "source": "magazin-exemplu.ro",
      "status": "shipped",
      "status_text": "Expediată",
      "invoice_issued": 1,
      "shipping": {
        "pickup_from_store": 0,
        "courier": "FAN Courier",
        "awb": "2345678901",
        "tracking_url": "https://www.fancourier.ro/awb-tracking/?awb=2345678901",
        "picked_up_by_courier": 1,
        "delivered": 0,
        "last_courier_status": "In tranzit"
      },
      "items": [
        { "code": "CT-500-NEGRU", "name": "Cană termos 500 ml neagră", "quantity": 2, "on_sale_document": 1 }
      ]
    }
  ]
}

Semnificația câmpurilor:

status — una dintre valorile registered (înregistrată), in_processing (în procesare: s-a emis documentul de vânzare), invoiced (facturată), shipped (preluată de curier), delivered (livrată), cancelled (anulată). status_text este denumirea stadiului folosită intern de magazin.
invoice_issued — 1 dacă factura a fost emisă.
shipping.pickup_from_store — 1 dacă clientul ridică personal comanda; în acest caz câmpurile de curier rămân goale.
items[].on_sale_document — 1 dacă produsul se află deja integral pe documentul de vânzare.
source — magazinul (site-ul) din care provine comanda.

Răspunsul nu conține niciodată valoarea comenzii, numele clientului, adresele sau identificatori interni.

O comandă anume

GET {adresa-de-baza}order/{numar-comanda}/, cu antetul X-Customer-Phone. Întoarce în data un singur obiect, cu aceleași câmpuri ca un element din lista de mai sus. Dacă numărul comenzii nu aparține telefonului trimis (sau antetul lipsește), răspunsul este 404 cu mesajul Order could not be loaded.

Retrimiterea facturii

POST {adresa-de-baza}order/{numar-comanda}/resend_invoice/, cu antetul X-Customer-Phone și fără corp. BOCP trimite ultima factură emisă pentru comandă pe adresa de email a clientului din BOCP.

{
  "is_error": false,
  "http_code": 200,
  "messages": ["Invoice email queued"],
  "data_count": 1,
  "data": { "invoice_email": "queued" }
}

Răspunsul înseamnă „pus la trimis”: dacă în setările contului emailurile cu facturi sunt programate pentru mai târziu (de exemplu ziua lucrătoare următoare), factura pleacă atunci.
Refuzurile au codul 409: No invoice issued for this order (nu există încă factură) sau The invoice was already resent in the last 24 hours.
Limita este de o retrimitere pe factură la 24 de ore. Se numără doar retrimiterile efectuate; o cerere refuzată nu prelungește așteptarea.

Stocul unui produs

GET {adresa-de-baza}stock/{cod-produs}/. Codul se compară exact cu codul produsului sau cu codul de bare și se codifică în adresă dacă are caractere speciale. Se caută doar în gestiunea aleasă pe agent și doar printre produsele publicate pe conectorul agentului.

{
  "is_error": false,
  "http_code": 200,
  "messages": [],
  "data_count": 1,
  "data": [
    {
      "code": "CT-500-NEGRU",
      "name": "Cană termos 500 ml neagră",
      "warehouse": "Depozit central",
      "stock": 16,
      "reserved": 2,
      "available": 14,
      "last_update": "2026-10-04 09:12:44"
    }
  ]
}

Dacă pe agent nu este aleasă gestiunea, răspunsul este 409 (The stock warehouse is not configured on this connector). Dacă produsul nu este găsit, răspunsul este 404 cu listă goală.

Catalogul

GET {adresa-de-baza}products/, cu filtre opționale adăugate în adresă ca segmente nume:valoare, de exemplu products/code:CT-500-NEGRU/ sau products/page:2/. Filtre utile: code (cod produs sau cod de bare), manufacturer, page (pagini de câte 500 de produse), modifiedafter (produse modificate după un moment, de forma 2026-10-01 00:00:00, codificat în adresă), include:images,properties (adaugă imaginile și caracteristicile) și format:xml sau format:csv. Lista conține doar produsele publicate pe conectorul agentului, cu prețurile din gestiunea aleasă pe agent.

{
  "is_error": false,
  "http_code": 200,
  "messages": [],
  "data_page": 1,
  "data_next_page_exists": 0,
  "data_count": 1,
  "data": [
    {
      "product_id": "8812",
      "cod_produs": "CT-500-NEGRU",
      "barcode": "5940000000017",
      "product_name": "Cană termos 500 ml neagră",
      "product_website_title": "Cană termos 500 ml",
      "product_short_description": "Păstrează băutura caldă 12 ore.",
      "category_name": "Căni și termosuri",
      "stoc_global": "16",
      "stock_reserved": "2",
      "stock_available": 14,
      "unitate_masura": "buc",
      "pret_vanzare": "74.30",
      "pret_vanzare_cu_tva": "89.90",
      "pret_vanzare_discounted": "0.00",
      "pret_vanzare_cu_tva_discounted": "0.00",
      "cota_tva_vanzare": "21",
      "selling_currency_txt": "RON",
      "producator": "Exemplu SRL",
      "images": ["Not included"],
      "caracteristici": ["Not included"]
    }
  ]
}

Prețul de vânzare cu TVA este pret_vanzare_cu_tva; dacă pret_vanzare_cu_tva_discounted este mai mare decât zero și mai mic decât acesta, produsul este în promoție și se aplică prețul promoțional.
Pentru disponibilitatea în gestiunea agentului se folosește adresa de stoc de mai sus: valorile de stoc din catalog (stoc_global, stock_reserved, stock_available) sunt stocul total al produsului, nu stocul gestiunii agentului.
Lista conține și alte câmpuri descriptive (categorii, dimensiuni, cuvinte cheie); prețurile de achiziție nu sunt transmise niciodată.

Plasarea unei comenzi

POST {adresa-de-baza}order/, cu antetul X-Customer-Phone și corpul JSON de mai jos. Formatul este cel al conectorului eCommerce BOCP (vezi Documentație conector eCommerce), cu regulile speciale ale agentului comenzi.

{
  "order_unique_id": "WA-20261004-0001",
  "order_date": "2026-10-04 10:15:00",
  "order_status": "new",
  "order_currency_code": "RON",
  "order_mentions": "Livrare după ora 17",
  "shipping_method": "courier",
  "client": {
    "name": "Ion Popescu",
    "email": "ion.popescu@example.com",
    "phone": "0722123456",
    "vat_id": "",
    "invoice_address": {
      "street": "Str. Florilor", "number": "12", "building": "", "stair": "", "floor": "", "apartment": "",
      "city": "Cluj-Napoca", "county": "Cluj", "country": "Romania", "zip": ""
    },
    "delivery_address": {
      "street": "Str. Florilor", "number": "12", "building": "", "stair": "", "floor": "", "apartment": "",
      "city": "Cluj-Napoca", "county": "Cluj", "country": "Romania", "zip": "",
      "shipping_contact_name": "Ion Popescu", "shipping_contact_phone": "0722123456"
    }
  },
  "items": [
    { "type": "product", "code": "CT-500-NEGRU", "item_name": "Cană termos 500 ml neagră", "item_quantity": 2 },
    { "type": "service", "code": "SHIPPING", "item_name": "Transport curier", "item_quantity": 1,
      "item_price": 19.83, "item_vat_percent": 21, "item_price_with_vat": 24, "line_value_with_vat": 24 }
  ]
}

Câmpuri obligatorii: order_unique_id, order_currency_code, shipping_method, client (cu name, invoice_address și delivery_address) și items (fiecare linie cu type, code, item_name și item_quantity). Valori pentru shipping_method: courier, locker, post, own_fleet, digital, personal_pickup; o valoare necunoscută este tratată ca livrare prin curier, cu o atenționare în notices. Opțional, payment_method (card, bank_transfer, paypal, credit) indică modul de plată ales de client.

Reguli speciale pentru comenzile trimise de agent:

Prețurile produselor vin din catalogul agentului. Pentru fiecare linie de tip product, BOCP înlocuiește prețul, cota de TVA și valoarea liniei cu cele din catalog (inclusiv prețul promoțional, dacă există); prețurile trimise de bot sunt ignorate. Produsul se poate identifica prin codul din câmpul cod_produs din catalog sau prin codul de bare; pe comandă, BOCP scrie codul produsului din catalog.
Un cod de produs care nu este în catalogul agentului refuză întreaga comandă, cu codul 400 și lista codurilor în unknown_product_codes.
Ce se ignoră: plățile (payments), anularea (order_cancelled), stadiul trimis (order_status devine întotdeauna new), identificatorul extern al clientului (client_unique_id) și liniile de tip discount.
Telefonul clientului de pe comandă devine întotdeauna numărul din antetul X-Customer-Phone, indiferent ce se trimite în client.phone.
Liniile de tip service (de exemplu transportul) se trimit cu toate câmpurile de preț, pentru că nu există în catalog.
order_unique_id trebuie să fie unic pentru agent; o a doua comandă cu același identificator este refuzată (Order with unique id … already exists). Astfel, o reîncercare după o întrerupere de rețea nu dublează comanda.
Confirmarea operatorului: comanda așteaptă confirmarea unui operator în Comenzi eCommerce înainte de orice procesare automată (rezervare de stoc, bon, factură, AWB).

Răspuns la succes:

{
  "is_error": false,
  "http_code": 200,
  "messages": [],
  "data_count": 5,
  "data": {
    "notices": [],
    "errors": [],
    "received_payload": { … comanda, după aplicarea regulilor de mai sus … },
    "BOCP_order_id": 4567,
    "import_summary": {
      "mode": "create",
      "bocp_order_id": 4567,
      "items_received": 2,
      "items_imported": 2,
      "payments_received": 0,
      "payments_registered": 0,
      "payments_skipped_pending": 0,
      "paid_amount_registered": 0,
      "payment_method_applied": "",
      "item_field_aliases_used": [],
      "unrecognised_code_warnings": [],
      "bocp_status": { "status_id": 1, "status_text": "Nouă", "external_status": "new", "order_cancelled": 0 }
    }
  }
}

Botul îi spune clientului că a înregistrat comanda doar dacă nu s-a primit nicio eroare și items_imported este egal cu items_received.

Răspuns la un cod de produs necunoscut:

{
  "is_error": true,
  "http_code": 400,
  "messages": ["Products not available on this agent's catalogue: CT-500-ROSU"],
  "data": { "unknown_product_codes": ["CT-500-ROSU"] }
}

Alte refuzuri (câmpuri lipsă, monedă necunoscută, identificator deja folosit) au tot codul 400, cu motivele în messages și în data.errors.

Coduri de răspuns

200 — succes.
400 — cerere greșită: antetul X-Customer-Phone lipsește sau nu conține un număr valid (la lista comenzilor și la plasarea comenzii), codul de produs lipsește din adresa de stoc, comanda este refuzată (vezi mai sus).
401 — datele de acces sunt greșite sau aparțin altui agent; la catalog, și atunci când conectorul agentului este inactiv.
402 — contul are mai mulți agenți comenzi activi decât permite abonamentul (de exemplu după expirarea unui abonament). Se rezolvă din BOCP, nu din bot.
404 — agentul nu există sau a fost șters; comanda nu aparține telefonului; adresa nu există (răspunsul conține describe_url); sau o listă fără rezultate (cu is_error false).
405 — agentul este inactiv (Connector is not active) sau metoda HTTP nu este permisă pentru adresa respectivă.
409 — cererea nu se poate executa în starea curentă: factura nu există sau a fost deja retrimisă în ultimele 24 de ore, gestiunea de stoc nu este aleasă pe agent, sau agentul nu are un conector de comenzi valid.
429 — limita de cereri a fost depășită.

Limite

60 de cereri pe minut pentru fiecare agent, numărate pe ultimele 60 de secunde. Cererile refuzate se numără și ele, deci după un răspuns 429 se așteaptă un minut întreg înainte de reîncercare.
O retrimitere de factură pe factură la 24 de ore (vezi mai sus).

Notificări de evenimente (webhook)

Dacă pe conectorul agentului se completează o Adresă notificare evenimente comenzi (vezi Configurare), BOCP trimite acolo prin POST, ca JSON, fiecare eveniment al comenzilor acelui conector. Adresa trebuie să fie https și să indice un server public; redirecționările nu sunt urmate.

Răspunsul serverului: orice cod 2xx confirmă primirea. Codurile 408, 429, 5xx și lipsa răspunsului se reîncearcă la rulările următoare. Orice alt cod 3xx sau 4xx oprește definitiv trimiterea evenimentului. Serverul trebuie să răspundă în cel mult 5 secunde.
Tipuri de pachete (câmpul notification_type): status pentru majoritatea evenimentelor, invoice la emiterea facturii (cu datele facturii) și awb la generarea AWB-ului (cu datele expediției). Aceeași adresă primește și notificări de produs (product_published, product_update, product_unpublished), cu alte câmpuri; botul le poate ignora.
Evenimente (câmpul event_type), printre care: order_imported (comanda a fost înregistrată), status_changed, order_cancelled, bv_issued (s-a emis documentul de vânzare), fa_issued (factură emisă), fa_cancelled, fa_stornoed, fa_proforma_issued, awb_issued, ready_for_pickup_by_courier, package_picked_up_by_courier, package_handed_to_client (colet livrat), package_picked_up_by_client_from_sediu (ridicat de client), ramburs_settled_by_courier, fully_paid.

Exemplu de pachet awb:

{
  "notification_type": "awb",
  "event_type": "awb_issued",
  "event_ts": "2026-10-04 11:02:10",
  "timestamp": "2026-10-04T11:02:15+03:00",
  "connector_id": 12,
  "connector_type": "BOCPRAPI",
  "connector_name": "Agent comenzi #7",
  "order_id": 4567,
  "order_unique_id": "WA-20261004-0001",
  "order_number": "WA-20261004-0001",
  "order_reference": "",
  "status_id": 3,
  "status_text": "Expediată",
  "external_status": "new",
  "order_cancelled": 0,
  "awb_number": "2345678901",
  "awb_packet_count": 1,
  "weight": 1.2,
  "awb_service_type": "Standard",
  "shipping_payer": "expeditor",
  "cash_on_delivery": 203.8,
  "cash_on_delivery_currency": "RON",
  "delivery_country": "Romania",
  "delivery_country_code": "RO",
  "declared_value": 203.8,
  "awb_type": "",
  "awb_subtype": "",
  "awb_url_pdf": "…",
  "tracking_url": "https://www.fancourier.ro/awb-tracking/?awb=2345678901"
}

Pachetul invoice are aceleași câmpuri comune, plus invoice_number, invoice_date, invoice_series, invoice_total, invoice_currency, invoice_total_RON, invoice_url_html și invoice_url_pdf. Pachetul status are doar câmpurile comune.

Notă: câmpurile invoice_url_html, invoice_url_pdf și awb_url_pdf nu conțin deocamdată adrese utilizabile. Pentru factură, botul folosește retrimiterea pe email.

Atenție: spre deosebire de răspunsurile la întrebări, notificările conțin sume (totalul facturii, suma ramburs, valoarea declarată).

Verificarea semnăturii

Fiecare notificare poartă două antete:

X-BOCP-Signature — sha256= urmat de HMAC-SHA256 în hexazecimal, calculat peste corpul brut al cererii, exact cum a fost primit, cu secretul de semnare al contului.
X-BOCP-Timestamp — momentul trimiterii, în format ISO 8601 (de exemplu 2026-10-04T11:02:15+03:00), identic cu câmpul timestamp din corp.

Serverul care primește notificarea verifică semnătura, respinge pachetele al căror timestamp este mai vechi de 5 minute și ignoră duplicatele după perechea order_id + event_ts + event_type (la o reîncercare, timestamp se schimbă, dar event_ts rămâne același). Secretul este unul singur pe cont, comun pentru toți conectorii.

Exemplu PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
$received = isset($_SERVER['HTTP_X_BOCP_SIGNATURE']) ? $_SERVER['HTTP_X_BOCP_SIGNATURE'] : '';
if (!hash_equals($expected, $received)) { http_response_code(401); exit; }
$packet = json_decode($body, true);
if (abs(time() - strtotime($packet['timestamp'])) > 300) { http_response_code(401); exit; }
http_response_code(200);

Exemplu Node.js (Express):

const crypto = require('crypto');
app.post('/bocp-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const received = req.get('X-BOCP-Signature') || '';
  const ok = received.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.sendStatus(401);
  const packet = JSON.parse(req.body.toString('utf8'));
  if (Math.abs(Date.now() - Date.parse(packet.timestamp)) > 5 * 60 * 1000) return res.sendStatus(401);
  res.sendStatus(200);
});

Atenție: semnătura se calculează peste corpul brut. Dacă serverul decodează JSON-ul și îl codifică din nou înainte de verificare, semnătura nu se mai potrivește.

Configurare în BOCP, pas cu pas

Agenții se creează și se configurează doar de administratorii contului.

Pagina Agenți chat

Pagina Conectori AI → Agenți chat are două coloane: Agenți chat (agenții OnChat) și Agenți comenzi. Fiecare coloană are o scurtă explicație, un link către documentația completă și propria listă de agenți. Lângă titlul fiecărei liste apare un mic indicator cu numărul de agenți activi și limita abonamentului (de exemplu 1/2), însoțit de o pictogramă prin care limita se poate mări. Fiecare listă are propriul buton Adaugă articol nou.

[Ecran: pagina Agenți chat cu cele două coloane, explicațiile, indicatorii de limită și butoanele Adaugă articol nou]

Abonamente și limite

Cele două tipuri de agenți au abonamente și limite separate: Agenți chat pentru OnChat și Agenți comenzi pentru agenții comenzi. Se numără doar agenții activi. Butonul Mărește limita (sau pictograma de lângă indicatorul de limită) deschide un ghid în patru pași, afișați în partea de sus a ferestrei: 1. Alege abonamentul (lista abonamentelor care măresc limita respectivă), 2. Confirmă comanda (se emite o factură proformă), 3. Plătește proforma și 4. Limita se mărește. Plata cu cardul se confirmă imediat, plata prin ordin de plată se confirmă manual. Dacă există deja o proformă neplătită pentru aceeași limită, ghidul o afișează primul, ca să nu se comande de două ori.

Dacă plata a fost făcută, dar limita afișată nu s-a schimbat, se apasă Reîncarcă licențele, aflat sub lista abonamentelor, sau se iese din cont și se intră din nou. Butonul recalculează limitele contului din abonamentele plătite și se poate folosi o dată pe minut. Dacă abonamentul activează și un modul nou, modulul apare după o nouă autentificare sau după apăsarea acestui buton.

Notă: butoanele Mărește limita și Activează sunt afișate doar administratorilor contului.

Adăugarea agentului

În coloana Agenți comenzi se apasă Adaugă articol nou.
Se deschide fereastra Adaugă agent comenzi. Dacă limita nu este atinsă, fereastra conține explicația tipului de agent, caseta cu limita contului și câmpul Tip agent, deja completat cu Agent comenzi. Dacă limita este atinsă, fereastra explică de ce trebuie mărită limita și afișează direct primul pas al ghidului de abonamente (vezi Abonamente și limite); agentul se adaugă după mărirea limitei.
Se apasă Salvare.
BOCP creează agentul, inactiv, și creează automat conectorul de comenzi legat de el: un conector de tip BOCP REST API numit „Agent comenzi #” urmat de numărul agentului, cu confirmare manuală a comenzilor, vizibil și în setările Comenzi eCommerce. Apoi se deschide fereastra agentului.

[Ecran: fereastra Adaugă agent comenzi, cu explicația, caseta de limită, câmpul Tip agent și butonul Salvare]

Fereastra agentului

La Gestiunea din care se raportează stocul se alege gestiunea. Fără ea, agentul nu poate răspunde despre stoc, nu poate citi catalogul și nu poate plasa comenzi.
La eCommerce connector se alege site-ul în ale cărui comenzi caută agentul: un singur site sau Toate.
Rândul Conectorul de comenzi (BOCP REST API) prin care agentul plasează comenzi și citește catalogul afișează conectorul creat la adăugare; nu se modifică de aici.
Se bifează Activ. La activare BOCP verifică limita de agenți comenzi și, pentru conectorul de comenzi legat, limita de conectori eCommerce. Dacă una dintre limite este atinsă, se afișează un mesaj și butonul Mărește limita. Cât timp agentul este inactiv, fereastra afișează un avertisment, iar botul primește refuzuri.
Produsele care trebuie să apară în catalogul agentului se publică pe conectorul de comenzi al agentului, la fel ca pentru orice conector eCommerce.
Se transmit dezvoltatorului textul din caseta Pentru agentul tău AI, parola (separat) și linkul către acest articol.

[Ecran: fereastra agentului comenzi, cu datele de acces, caseta Pentru agentul tău AI, bifa Activ, gestiunea, conectorul de comenzi și site-ul]

Caseta „Pentru agentul tău AI”

În fereastra agentului, sub datele de acces (adresa, adresa descrierii, utilizatorul și parola), caseta Pentru agentul tău AI conține un text gata de copiat cu butonul Copiază instrucțiunile pentru AI. Textul cuprinde adresa agentului, numele de utilizator și indicația ca agentul AI să citească întâi adresa de descriere. Parola nu face parte din text: se ia din datele de acces și se transmite separat.

Adresa de notificare pe conector

Se deschid setările conectorului „Agent comenzi #…” din Comenzi eCommerce.
În secțiunea Notificări comenzi (webhook) se completează Adresă notificare evenimente comenzi cu adresa https primită de la dezvoltator și se salvează. Adresele care nu încep cu https:// sau care nu indică un server public sunt refuzate.
La prima salvare a unei adrese, dacă contul nu are încă un secret, BOCP generează Secretul semnătură notificări și îl afișează o singură dată. Secretul se copiază imediat și se transmite dezvoltatorului pe un canal sigur. Ulterior se afișează doar ultimele 4 caractere.
Dacă secretul s-a pierdut, se folosește Regenerează secretul. Atenție: secretul este comun pentru toți conectorii contului, deci după regenerare trebuie actualizate toate serverele care verifică semnătura.

[Ecran: secțiunea Notificări comenzi (webhook) din setările conectorului, cu adresa și secretul afișat o singură dată]

Dezactivare și ștergere

Prin debifarea Activ, agentul nu mai primește răspunsuri; conectorul de comenzi legat rămâne neschimbat.
Prin Șterge agentul, cheia lui nu mai funcționează, iar conectorul de comenzi creat pentru el se dezactivează și se șterge odată cu agentul.
Conectorul de comenzi al unui agent nu poate fi șters din setările Comenzi eCommerce; acolo apare mesajul că se șterge agentul din Conectori AI → Agenți chat.

Securitate și date personale

O cheie pentru fiecare agent. Datele de acces ale unui agent funcționează doar pentru acel agent și nu pot citi datele altui agent sau ale altui cont.
Telefonul trebuie să fie cel al expeditorului verificat. Platforma de chat trimite numărul persoanei care scrie, așa cum îl garantează platforma, niciodată un număr tastat în conversație. Răspunderea pentru acest lucru aparține platformei de chat.
Date care nu se transmit niciodată în răspunsurile la întrebări: valoarea comenzii, numele clientului, adresele de livrare și facturare și identificatorii interni ai clientului. Factura nu se transmite în conversație, ci doar prin email, la adresa clientului din BOCP.
Notificările conțin sume (totalul facturii, suma ramburs, valoarea declarată) și sunt semnate, ca serverul care le primește să poată verifica proveniența lor.
Cel mult 60 de cereri pe minut pentru fiecare agent.
Un agent inactiv, șters sau peste limita abonamentului nu mai primește niciun răspuns cu date.

Verificarea clientului la agenții OnChat

La agenții de tip OnChat, opțiunea Cere telefonul sau emailul clientului pentru verificare este bifată implicit la agenții noi. Cu opțiunea bifată, platforma de chat trimite telefonul sau emailul clientului, iar comanda este afișată doar dacă acestea se potrivesc cu persoana de contact sau cu adresa de livrare ori de facturare a comenzii. Fără verificare, oricine poate afla stadiul unei comenzi ghicind numărul ei, de aceea se recomandă păstrarea bifei. Agentul comenzi verifică întotdeauna telefonul clientului, deci nu are această opțiune.

Probleme frecvente și soluții

Agentul nu găsește comenzile unui client — se verifică dacă telefonul de pe comandă este același cu numărul de pe care scrie clientul, dacă comanda este mai nouă de 90 de zile și neanulată și dacă site-ul ales la eCommerce connector este cel al comenzii (sau Toate). La deschiderea ferestrei agentului, BOCP pregătește în fundal căutarea după telefon pentru comenzile existente; până la finalizare, comenzile mai vechi pot lipsi.
Botul primește 404 la lista comenzilor, deși nu e nicio eroare — clientul nu are comenzi care să corespundă; răspunsul are is_error false și listă goală. Botul îi spune clientului că nu a găsit comenzi pe acest număr.
Agentul nu poate răspunde despre stoc — nu este aleasă gestiunea din care se raportează stocul, produsul nu este publicat pe conectorul de comenzi al agentului, produsul nu are fișă de stoc în gestiunea aleasă, sau codul trimis nu este identic cu codul produsului ori cu codul de bare.
Comanda este refuzată cu „Products not available on this agent's catalogue” — codul trimis nu aparține unui produs publicat pe conectorul agentului, în gestiunea agentului. Se publică produsul pe conector sau se corectează codul.
Comanda este refuzată cu „Order is missing required field(s)” — lipsește un câmp obligatoriu, de cele mai multe ori order_currency_code, shipping_method sau una dintre adrese.
Comanda plasată prin agent nu se procesează — comanda așteaptă confirmarea unui operator în Comenzi eCommerce. Se confirmă comanda, sau administratorul schimbă modul de confirmare pe conectorul agentului.
Retrimiterea facturii este refuzată — pentru comandă nu s-a emis încă factura, sau factura a fost deja retrimisă în ultimele 24 de ore.
Bifa Activ nu se salvează — este atinsă limita de agenți comenzi sau limita de conectori eCommerce; un administrator al contului folosește butonul Mărește limita afișat sub mesaj.
Fereastra Adaugă agent comenzi afișează abonamentele în loc de formular — limita de agenți comenzi este atinsă. Se alege un abonament și se plătește proforma; dacă după plată limita nu s-a actualizat, se apasă Reîncarcă licențele sau se iese din cont și se intră din nou.
Botul primește brusc 402 după ce a funcționat — numărul de agenți comenzi activi depășește limita abonamentului (de exemplu după expirarea unui abonament). Se mărește limita sau se dezactivează agenții în plus.
Catalogul sau plasarea comenzilor răspund cu 409 — agentul nu mai are un conector de comenzi valid legat sau nu are gestiunea aleasă.
Notificările nu ajung sau sunt respinse de server — se verifică dacă adresa este https publică, dacă serverul răspunde cu 2xx în cel mult 5 secunde și dacă verifică semnătura peste corpul brut, cu secretul curent (după o regenerare, secretul vechi nu mai este valabil).

De știut

Notă: agentul caută în comenzile din Comenzi eCommerce. Comenzile eMag și cele din magazinul BOCP WebShop nu sunt incluse deocamdată. La comenzile livrate în mai multe colete, agentul raportează ultimul document de vânzare și ultimul AWB.

Notă: comenzile plasate prin agent sunt comenzi obișnuite ale conectorului agentului: după confirmare urmează automatizările configurate pe acel conector (rezervare, bon, factură, AWB), iar notificările se trimit la adresa setată pe acel conector.

Atenție: obligația de a informa clientul că discută cu un agent automat aparține operatorului platformei de chat. Înainte de punerea în funcțiune se recomandă citirea articolului GDPR și asistenții AI conectați la BOCP: ce trebuie să știi înainte.

Atenție: parola agentului și secretul de semnare se comunică doar celui care administrează platforma de chat și nu se lipesc niciodată într-o conversație.

Vezi și

Was this article helpful?

★ ★ ★ ★ ★