Integrare OpenCart cu FirstBill: facturi automate din comenzi

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

OpenCart este o platformă open-source de magazin online. Comenzile pot fi trimise la FirstBill dintr-o extensie care se atașează evenimentelor de comandă.

Cum conectezi OpenCart 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. În OpenCart adaugă o extensie, un modul sau un fragment de cod care rulează când o comandă este plasată sau plătită, la punctele de extensie de mai jos.
3. Din acel cod trimite comanda ca JSON la adresa webhook, cu antetul X-Firstbill-Token (exemplul de cod este mai jos).
4. Pregătește corpul în formatul comenzii FirstBill: id comandă, client, produse, TVA și starea plății.
5. Testează pe un mediu de test sau cu o comandă de probă. Factura apare în Vânzări → Facturi emise.
6. Eroarea, dacă există, apare în Configurare → Magazine online, la conexiunea respectivă.

Puncte de extensie în OpenCart

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.

Exemplu de cod (PHP)

Funcția de mai jos trimite o comandă la FirstBill. Este un punct de pornire: apelează-o din punctul de extensie ales, după ce construiești `$order`.

<?php
// Exemplu de pornire: trimite comanda la FirstBill. Testează pe un mediu de test înainte de producție.
function firstbill_send_order(array $order): void {
    $ch = curl_init('https://cloud.firstbill.ro/api/hooks/ID_CONEXIUNE');
    curl_setopt_array($ch, [
        CURLOPT_POST => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT => 10,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-Firstbill-Token: TOKENUL_TAU'],
        CURLOPT_POSTFIELDS => json_encode($order, JSON_UNESCAPED_UNICODE),
    ]);
    curl_exec($ch);
    curl_close($ch);
}

// $order are structura din „Formatul comenzii FirstBill”: externalId, customer, lines, paid etc.

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