Knowledgebase

Cerinte pentru a integra un api nou in BOCP CloudSales ERP

Integrare API cu BOCP CloudSales ERP — Cerințe pentru parteneri

Scopul documentului. Acesta este un document de referință pe care îl transmitem unui partener potențial (magazin online, marketplace, WMS, alt ERP, sistem de curierat etc.) la începutul unei integrări prin API. Descrie pe scurt ce face BOCP CloudSales ERP, cum se realizează sincronizarea și ce anume avem nevoie de la sistemul partenerului pentru a construi conexiunea.

   
Versiune 1.0
Ultima actualizare [dată]
Contact tehnic BOCP [nume] · [email] · [telefon]

1. Despre BOCP CloudSales ERP

CloudSales este un ERP în cloud dezvoltat de BOCP, dedicat companiilor de comerț și eCommerce din România. Platforma acoperă întregul flux comercial: vânzări, gestiune de stoc, facturare și fulfillment, într-un sistem unic, accesibil din browser.

În scenariile de integrare, CloudSales joacă de regulă rolul de sistem central de gestiune: preia produse și comenzi dintr-un canal extern, actualizează stocuri și prețuri, procesează comenzile și returnează înapoi statusul, documentele de transport (AWB) și facturile. Obiectivul integrării este ca datele să circule automat, în ambele sensuri, fără intervenție manuală.

2. Cum funcționează integrarea (pe scurt)

Integrarea se sprijină pe trei mecanisme complementare. Un partener poate implementa doar o parte dintre ele; cu cât acoperim mai multe, cu atât sincronizarea este mai rapidă și mai fiabilă.

  • Citire (pull). BOCP interoghează periodic API-ul partenerului pentru a prelua produse și comenzi noi sau modificate.
  • Scriere (push). BOCP trimite către API-ul partenerului actualizări: preț, stoc, status comandă, AWB, factură.
  • Notificări (webhook). Sistemul partenerului anunță BOCP imediat ce apare un eveniment (produs nou/editat, comandă nouă/modificată), astfel încât să nu depindem exclusiv de interogarea periodică.

Schematic:

[Sistem partener]  --(webhook: eveniment)-->  [BOCP CloudSales ERP]
[Sistem partener]  <--(pull: citire delta)--  [BOCP CloudSales ERP]
[Sistem partener]  <--(push: preț/stoc/status/AWB/factură)-- [BOCP]

Webhook-urile nu înlocuiesc citirea periodică — ele o accelerează. Citirea programată rămâne activă la un interval relaxat, cu rolul de a recupera eventualele evenimente pierdute (vezi §6).

3. De ce avem nevoie ca să începem

Pentru demararea integrării avem nevoie de următoarele. Ideal, toate elementele de mai jos ne sunt puse la dispoziție înainte de startul dezvoltării.

Element Detalii
Acces la API Metoda de autentificare acceptată (cheie API, OAuth 2.0, token etc.) și credențialele aferente.
Documentația API-ului Referință de endpoint-uri, modele de date, coduri de eroare, limite de rată.
Cont / mediu de test (sandbox) Un mediu separat de producție, ca să putem dezvolta și testa fără a afecta datele reale.
Persoană de contact tehnică Cineva care poate răspunde la întrebări pe parcursul integrării.
Limitele de rată (rate limits) Numărul maxim de cereri permise, ca să dimensionăm corect frecvența sincronizării.

4. Cerințe API detaliate

Cerințele de mai jos indică și drepturile (scope-urile) necesare pe credențialul furnizat. Recomandăm acordarea strict a permisiunilor de care avem nevoie, conform principiului privilegiului minim.

4.1 Autentificare

  • Acceptăm cheie API, token Bearer sau OAuth 2.0 — ne adaptăm la ce oferă sistemul dumneavoastră.
  • Toate cererile se fac exclusiv peste HTTPS/TLS.
  • Preferăm credențiale cu scope configurabil (citire/scriere separat) și posibilitate de revocare/rotire.

4.2 Produse

Operațiune Drept necesar Observații
Preluare listă produse citire Cu toate detaliile relevante. Ideal cu parametru changed_since={timestamp} pentru citire incrementală.
Actualizare produse scriere Preț, stoc, detalii, imagini, caracteristici (mărime, culoare etc.).
Creare produse (etapă ulterioară) scriere + citire nomenclatoare Va necesita citire pe nomenclatoare: categorii, caracteristici, familii etc.

Câmpuri de interes la nivel de produs: identificator unic stabil, SKU, denumire, descriere, preț (cu monedă), stoc/disponibilitate, categorie, imagini, atribute/variante (mărime, culoare), și data ultimei modificări.

4.3 Comenzi

Operațiune Drept necesar Observații
Preluare comenzi noi și modificate citire Ideal printr-un singur endpoint care le include atât pe cele noi, cât și pe cele modificate, cu parametru changed_since={timestamp}.
Actualizare status scriere Modificăm doar statusul comenzii, nu și conținutul acesteia.
Actualizare tracking / AWB scriere Setarea AWB-urilor generate (unul sau mai multe). Putem atașa un link către AWB sau putem transmite AWB-ul complet în PDF.
Actualizare facturare scriere Detalii despre factura/facturile emise — link către factură sau PDF atașat.

Câmpuri de interes la nivel de comandă: identificator unic stabil, număr comandă, data, status, liniile comenzii (produs, cantitate, preț, monedă), date de livrare și facturare, total, și data ultimei modificări.

4.4 Nomenclatoare

Pentru crearea de produse (etapă ulterioară) avem nevoie de drept de citire pe nomenclatoare: categorii, caracteristici/atribute, familii de produse, unități de măsură, cote TVA — orice liste de referință de care depinde definirea unui produs.

4.5 Sincronizare incrementală și paginare

  • changed_since={timestamp} — pentru a citi doar ce s-a schimbat de la ultima sincronizare reușită. Reduce volumul de date și încărcarea pe ambele sisteme.
  • Paginare — pentru endpoint-urile de listă (produse, comenzi). changed_since ne dă delta, dar un delta mare tot are nevoie de paginare (ex. page/per_page sau cursor). Vă rugăm să indicați mecanismul suportat.
  • Timestamp-uri consistente — vezi §8 pentru formatul recomandat.

5. Notificări prin webhook (opțional, recomandat)

Dacă sistemul dumneavoastră permite apeluri webhook de ieșire, putem expune două URL-uri pe care sistemul dumneavoastră să le apeleze automat:

  • URL produse — apelat ori de câte ori apare un produs nou sau este editat unul existent.
  • URL comenzi — pentru un ping automat când apare o comandă nouă sau se modifică una existentă.

Recomandări pentru webhook-uri:

  • Payload-ul poate fi minimal (doar identificatorul și tipul evenimentului); BOCP va prelua ulterior detaliile complete prin citire. Acest lucru menține webhook-ul rapid și evită expunerea de date sensibile în notificare.
  • Necesită un mecanism de retry din partea dumneavoastră (vezi §6), deoarece o notificare poate eșua temporar.
  • Trebuie securizate — vezi §7.

6. Scenarii tipice de sincronizare

1. Import inițial (full sync). La prima conectare, BOCP preia întregul catalog de produse și comenzile existente, paginat. Se stabilește un timestamp de referință pentru sincronizările ulterioare.

2. Sincronizare incrementală periodică (delta). La un interval configurat, BOCP cere doar înregistrările modificate de la ultima sincronizare reușită (changed_since). Este mecanismul de bază.

3. Reacție la eveniment (webhook → citire). La primirea unui webhook, BOCP preia imediat detaliile înregistrării afectate. Reduce latența de la minute la secunde.

4. Actualizare dinspre BOCP. BOCP împinge către partener modificările de preț și stoc, precum și — pe partea de comenzi — statusul, AWB-ul și factura.

5. Flux complet comandă. Partenerul creează comanda → BOCP o preia → o procesează → returnează status + AWB + factură. Conținutul comenzii nu este modificat de BOCP, doar statusul și documentele atașate.

6. Recuperare după downtime (catch-up). Dacă un sistem a fost indisponibil sau un webhook s-a pierdut, următoarea sincronizare incrementală cu changed_since (de la ultimul timestamp confirmat) recuperează automat înregistrările ratate. De aceea citirea periodică rămâne activă și când webhook-urile funcționează.

7. Securitate

Datele vehiculate includ informații comerciale și, în cazul comenzilor, date cu caracter personal (nume, adrese). Tratăm securitatea ca cerință de bază, nu ca opțiune.

  • Transport criptat. Exclusiv HTTPS/TLS pentru toate apelurile, în ambele sensuri.
  • Credențiale. Cheia/token-ul se transmite pe un canal sigur (nu în text clar prin email neprotejat), se stochează criptat și poate fi rotit/revocat. Se acordă doar drepturile necesare (privilegiu minim).
  • Autentificarea webhook-urilor. Recomandăm un secret partajat sau o semnătură HMAC pe fiecare notificare, ca BOCP să poată verifica faptul că apelul este autentic. Endpoint-urile expuse scriu date — nu pot fi lăsate deschise.
  • Idempotență și retry. Notificările și cererile de scriere ar trebui să fie idempotente (un eveniment livrat de două ori nu produce efecte duplicate), cu politică de retry cu backoff.
  • Identificatori opaci. Recomandăm expunerea unor identificatori externi opaci (nu ID-uri interne secvențiale), pentru a evita enumerarea și scurgerea de informații despre volume.
  • Fără date sensibile în URL. Datele personale sau secretele nu se transmit în parametri de query.
  • Restricționare acces (opțional). Dacă este posibil, allowlist de IP pentru originea apelurilor.
  • GDPR. Procesăm date personale doar în scopul îndeplinirii comenzilor, aplicând minimizarea datelor. Dacă este cazul, stabilim un acord de prelucrare a datelor (DPA) între părți.

8. Convenții de date recomandate

Pentru a evita ambiguitățile, recomandăm următoarele convenții. Ne putem adapta la formatele dumneavoastră, dar acestea reduc erorile de integrare.

  • Timestamp-uri: ISO 8601 cu fus orar (ex. 2026-07-13T10:30:00+03:00 sau UTC ...Z). Esențial pentru corectitudinea changed_since.
  • Monedă: cod ISO 4217 (RON, EUR) explicit pe fiecare valoare de preț. (CloudSales lucrează multi-monedă, deci moneda trebuie să fie clară per produs și per comandă.)
  • Sume: separator zecimal clar; ideal valori numerice, nu formatate.
  • Identificatori: stabili în timp (un produs/o comandă păstrează același identificator la fiecare citire).
  • Codificare: UTF-8.

9. Checklist pentru partener

Pentru a demara rapid, ne-ar ajuta să primim:

  • [ ] Metoda de autentificare + credențiale pentru mediul de test
  • [ ] Link către documentația API
  • [ ] Endpoint de listare produse (cu changed_since și paginare, dacă există)
  • [ ] Endpoint de listare comenzi noi + modificate (ideal unul singur, cu changed_since)
  • [ ] Endpoint(uri) de actualizare: preț/stoc produse; status/AWB/factură comenzi
  • [ ] Confirmare privind suportul pentru webhook-uri (produse și comenzi) + metoda de securizare
  • [ ] Limitele de rată (rate limits) și regulile de paginare
  • [ ] Formatul timestamp-urilor și al monedei
  • [ ] Persoană de contact tehnică

10. Contact

Pentru orice detaliu tehnic sau clarificare pe parcursul integrării:

office@reallife.solutions

[0365424438] BOCP · CloudSales ERP · bocp.eu

Document intern BOCP, reutilizabil pentru inițierea integrărilor prin API. Se poate transmite ca atare partenerilor.

Was this article helpful?

★ ★ ★ ★ ★