Integrare Ecwid cu FirstBill: facturi automate din comenzi
Actualizat la
Pe scurt
Ecwid se conectează la FirstBill prin formatul de comandă FirstBill, trimis de un instrument de automatizare (Zapier, Make, n8n, Pabbly) sau de un script. În FirstBill creezi o conexiune în Configurare → Magazine online, apoi fiecare comandă devine factură o singură dată, cu clientul, TVA-ul și încasarea. Integrarea necesită planul Pro.
Ce face integrarea Ecwid – FirstBill
- Emite automat factura pentru fiecare comandă, cu numerotarea și seria firmei tale.
- Caută clientul după CUI (sau după email și nume) și îl creează dacă nu există.
- Preia cotele de TVA, reducerile și transportul din comandă.
- Înregistrează încasarea pe factură când comanda este plătită.
- Nu emite niciodată două facturi pentru aceeași comandă, chiar dacă platforma retrimite notificarea.
- Afișează în FirstBill, la conexiune, numărul de facturi emise și ultima eroare, dacă apare.
Metode de integrare pentru Ecwid
Ecwid (Lightspeed) adaugă un magazin pe un site existent. Are API REST și notificări de comenzi, care cer un token de acces pentru aplicație. Formatul lor diferă de cel FirstBill, deci este nevoie de un pas de mapare.
| Metodă | Disponibilitate | Observații |
|---|---|---|
| Webhook direct Ecwid → FirstBill | Nu | Notificarea cere citirea comenzii prin API cu token; este nevoie de mapare. |
| Zapier, Make, n8n | Depinde de conector | Verifică declanșatorul pentru comenzi Ecwid în catalogul instrumentului. |
| API Ecwid | Posibil | Pentru dezvoltatori: primești notificarea, citești comanda și o trimiți la FirstBill. |
Cum conectezi Ecwid la FirstBill, pas cu pas
- În FirstBill (planul Pro), deschide Configurare → Magazine online, alege „Altă platformă / Zapier / Make / cod propriu” și creează conexiunea. Copiază adresa webhook și tokenul (se afișează o singură dată).
- Într-un instrument de automatizare (Zapier, Make, n8n, Pabbly) creează un scenariu nou. Declanșatorul: comandă nouă din Ecwid.
- Adaugă acțiunea „Webhook / HTTP request”, metoda POST, tip conținut JSON. Adresa: adresa webhook copiată. Antet: X-Firstbill-Token cu tokenul (sau adaugă ?token=… la adresă, dacă instrumentul nu permite antete).
- Construiește corpul cererii în formatul comenzii FirstBill (vezi mai jos), mapând câmpurile din Ecwid: id comandă, client, produse, TVA și starea plății.
- Rulează un test cu o comandă reală sau de probă. Factura apare în Vânzări → Facturi emise.
- Dacă primești eroare, deschide Configurare → Magazine online: ultima eroare apare la conexiunea respectivă.
Formatul comenzii FirstBill
Exemplu de corp JSON pentru o comandă plătită, cu două bucăți dintr-un produs și transport:
{
"externalId": "1001",
"customer": {
"name": "FIRMA CLIENT SRL",
"cui": "RO12345678",
"address": "Str. Exemplu 1",
"city": "Focșani",
"county": "VN",
"email": "client@exemplu.ro",
"phone": "0700000000"
},
"lines": [
{ "name": "Produs", "quantity": 2, "unitPrice": 50, "vatRate": 21, "sku": "P1" }
],
"shipping": { "name": "Curier", "price": 15, "vatRate": 21 },
"priceIncludesVat": false,
"paid": true,
"paymentMethod": "CARD_ONLINE",
"notes": "Comandă #1001"
}Câmpurile comenzii FirstBill
Comenzile se trimit ca JSON, la adresa webhook a conexiunii. Doar identificatorul comenzii, numele clientului și produsele sunt obligatorii.
| Câmp | Ce trimiți din platformă |
|---|---|
| externalId | Numărul sau ID-ul unic al comenzii. Aceeași valoare retrimisă nu emite o a doua factură. |
| customer.name | Denumirea firmei sau numele persoanei. |
| customer.cui | CUI-ul, dacă magazinul îl colectează (câmp personalizat la checkout). Fără CUI, clientul rămâne persoană fizică. |
| customer.address, city, county, email, phone | Datele de facturare. Județul poate fi numele sau codul (Vrancea sau VN). |
| lines[].name, quantity, unitPrice | Produsele. Prețul este fără TVA, sau cu TVA dacă pui priceIncludesVat true. |
| lines[].vatRate | Cota de TVA (21, 11 sau 0). Dacă lipsește, se folosește 21 pentru firmele plătitoare de TVA. |
| lines[].discount | Valoarea totală a reducerii liniei, în aceeași logică a prețului. |
| shipping.price | Costul transportului, trecut ca linie separată pe factură. |
| priceIncludesVat | true dacă prețurile din magazin includ TVA. |
| paid, paymentMethod | paid true înregistrează și încasarea. Metode: CARD_ONLINE, COD (ramburs), TRANSFER, CASH, CARD și altele. |
TVA, CUI și transport
- Cotele de TVA se iau din comandă. Dacă magazinul nu are taxe configurate, prețurile se tratează ca având TVA inclus.
- Pentru clienți persoane juridice, magazinul trebuie să colecteze CUI-ul la checkout (câmp personalizat). FirstBill nu importă CNP-ul: persoanele fizice rămân fără CUI.
- Transportul apare ca linie separată, cu cota lui de TVA.
- Firmele neplătitoare de TVA emit facturi fără TVA, indiferent de cotele din comandă.
- Dacă ai activată transmiterea automată în SPV, factura emisă din comandă se transmite ca orice altă factură.
Ce îți trebuie
- Un cont FirstBill cu planul Pro (integrările cu magazine online folosesc conexiuni webhook și API).
- Acces de administrator în magazin, ca să poți adăuga un webhook sau o automatizare.
- Pentru e-Factura: firma conectată la ANAF în FirstBill (planul Start sau Pro).
Întrebări frecvente
- Am nevoie de token Ecwid?
- Pentru citirea comenzii prin API, da: un token de acces al aplicației. Un instrument de automatizare îl gestionează în locul tău.
- Cum evit facturile duble?
- Trimite numărul comenzii ca externalId; FirstBill nu emite două facturi pentru aceeași valoare.
- Pot emite automat facturi din comenzile Ecwid?
- Da, în planul Pro. Fiecare comandă Ecwid devine o factură în FirstBill, o singură dată, cu încasarea înregistrată dacă este plătită.
- Ce se întâmplă dacă Ecwid trimite aceeași comandă de două ori?
- FirstBill recunoaște comanda după identificatorul ei și întoarce factura deja emisă, fără să creeze alta.
Începe gratuit
Creează un cont și emite prima factură în câteva minute. Nu ai nevoie de card pentru planul gratuit.