Cum conectezi un magazin pe platformă proprie la eficio prin Custom API

De ce să folosești Custom API

Dacă magazinul tău e făcut pe comandă, nu ai nevoie de un plugin: magazinul apelează direct endpoint-urile eficio. Primește același tratament ca un magazin conectat prin modul: comenzile lui intră în eficio, iar statusul comenzii se poate întoarce automat în magazin.

• comenzile noi sau actualizate intră în modulul Comenzi;
• produsele, categoriile și brandurile magazinului se pot trimite în eficio;
• eficio anunță magazinul, pe un URL de callback, când se schimbă comanda venită de la el.

Ce pregătești înainte

• un dezvoltator care poate face apeluri HTTP din magazin (POST cu JSON);
• un loc sigur în magazin unde se păstrează cheia permanentă primită de la eficio;
• opțional, o adresă publică în magazin care poate primi notificările eficio (callback).

Pasul 1 — Deschide pagina Custom API

În meniul din stânga deschizi Integrări, la Canale de vânzare alegi Magazine și apeși Conectează pe cardul Custom API. Pagina are pașii de conectare, lista endpoint-urilor (dai clic pe adresă ca s-o copiezi) și butonul Documentație API, cu toate câmpurile, exemple cURL și PHP și codurile de eroare.

Pasul 2 — Generează tokenul de conectare

Apeși Generează token și confirmi. Magazinul apare în listă cu starea Așteaptă plugin, iar tokenul se afișează dedesubt; îl revezi cu Vezi token. Tokenul e de unică folosință.

Pasul 3 — Handshake-ul: tokenul devine cheie permanentă

1. Magazinul trimite un POST /connect cu tokenul și adresa magazinului.
2. Primește înapoi un api_token permanent, pe care îl salvează.
3. La toate celelalte apeluri trimite antetul Authorization: Bearer <api_token> (sau X-Eficio-Token).

După handshake, magazinul trece în Conectat.

Pasul 4 — Trimite comenzile și produsele

Endpoint-urile sunt sub /api/integrations/custom-api:

• POST /heartbeat: semnal că magazinul e online; pagina recomandă un apel la 15 minute;
• POST /orders: o comandă nouă sau actualizarea uneia existente;
• POST /products: produsele magazinului, până la 200 pe apel;
• POST /taxonomies: categoriile și brandurile magazinului.

Pasul 5 — Callback-ul și ce preia eficio din magazin

Cu Setează URL de callback alegi magazinul și adresa la care eficio trimite un POST, cu antetul X-Eficio-Token (cheia magazinului) și un corp JSON de forma {event, data}. Lași câmpul gol dacă preferi ca magazinul să interogheze singur eficio.

Din meniul rândului, Ce preia din magazin îți dă trei opțiuni, aplicate la fiecare trimitere de catalog: Preia prețurile de pe site, Preia stocul de pe site (stocul pleacă apoi mai departe pe canale) și Scoate produsele dezactivate pe site. Opțiunile se pot alege după prima trimitere de produse.

Ce se întâmplă după ce salvezi

• comenzile trimise la /orders apar în modulul Comenzi și se procesează ca oricare altele;
• când se schimbă statusul unei comenzi venite din magazin, eficio trimite pe callback evenimentul order.status_changed, cu datele comenzii;
• fiecare trimitere spre callback se notează în jurnalul magazinului, vizibil cu Loguri;
• pentru operații pe tot contul (produse, stoc, facturi, AWB) există și API-ul eficio v2, cu chei efc_…; documentația publică e la /api-docs.

Probleme frecvente

• magazinul rămâne la Așteaptă plugin: apelul /connect nu a reușit sau a folosit alt token; verifică tokenul cu Vezi token;
• apelurile primesc refuz după conectare: lipsește antetul cu api_token sau magazinul a fost deconectat ori șters;
• ai expus cheia: Regenerează token invalidează tokenul curent, iar magazinul trebuie să refacă handshake-ul;
• Magazinul n-a trimis încă produse, la Ce preia din magazin: trimite întâi catalogul prin /products.

Ce urmează

• conectează un curier, de exemplu FAN Courier, ca statusul de livrare să ajungă la comandă;
• conectează programul de facturare, de exemplu SmartBill;
• trimite comenzile și altor sisteme, cu acțiunea de webhook din fluxurile automate.

Întrebări frecvente