Integrare MerchantPro cu FirstBill: facturi automate din comenzi

Ce face integrarea MerchantPro – 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 MerchantPro

MerchantPro este o platformă românească de comerț electronic. Disponibilitatea API-ului și a notificărilor de comenzi depinde de abonamentul tău; verifică la suportul MerchantPro ce poți activa. Orice mecanism care trimite comenzi la o adresă HTTP poate folosi formatul FirstBill.

Cum conectezi MerchantPro la FirstBill, pas cu pas

1. Î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ă).
2. Într-un instrument de automatizare (Zapier, Make, n8n, Pabbly) creează un scenariu nou. Declanșatorul: comandă nouă, dacă platforma oferă conector sau webhook din MerchantPro.
3. 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).
4. Construiește corpul cererii în formatul comenzii FirstBill (vezi mai jos), mapând câmpurile din MerchantPro: id comandă, client, produse, TVA și starea plății.
5. Rulează un test cu o comandă reală sau de probă. Factura apare în Vânzări → Facturi emise.
6. 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.

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ă.

Particularități MerchantPro

• Dacă ai nevoie de un conector dedicat MerchantPro, scrie-ne la contact@citu.ro: prioritizăm platformele cerute de utilizatori.

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).