API FacturOne
Emite facturi automat din aplicația ta, cu e-Factura. Versiunea 1. Adresa de bază: https://api.facturone.com/v1
Autentificare
Fiecare cerere are antetul Authorization: Bearer <cheie API>. Cheile se creează în
FacturOne, în aplicația API FacturOne → Chei API, și se arată o singură dată. Păstrează cheia pe server
(variabilă de mediu), niciodată în pagini web sau în aplicații instalate la clienți.
fo_test_…— modul test: facturile rămân în FacturOne AI, cu numerotare de test, nu ajung în Facturare și nu folosesc seriile reale. Sunt disponibile pe orice plan.fo_live_…— facturile reale, pe planurile Pro și Max.
Drepturi pe cheie: read (citire, PDF, e-Factura), invoices:write (emitere și stornare),
email:send (trimitere pe e-mail).
Prima cerere: verifică cheia
monthly apare doar la cheile live: facturile incluse în lună, câte ai folosit și când se resetează.
series: seriile bifate pentru API, din care alegi series la fiecare factură.
curl https://api.facturone.com/v1/me -H "Authorization: Bearer $FACTURONE_API_KEY"{
"object": "api_key",
"mode": "live",
"key_prefix": "fo_live_Ab3dE5fG",
"scopes": [
"read",
"invoices:write"
],
"limits": {
"requests_per_minute": 60,
"invoices_per_day": 500
},
"live_invoices_enabled": true,
"monthly": {
"limit": 100,
"used": 37,
"reset_at": "2027-01-01T00:00:00+02:00"
},
"series": [
"API",
"EMG-HU-FBE"
]
}Serii și numere
Fiecare factură prin API spune pe ce serie se emite, în series. Seria trebuie bifată pentru API la
API FacturOne → Facturare → Serii pentru API. Bifezi oricâte serii existente sau creezi una nouă cu un clic
(de exemplu „API”). Seriile bifate apar marcate „API” în listă. Regulile sunt aceleași în test și pe live.
Exemplu: un program de import eMAG emite pe 6 serii, câte două pentru fiecare țară, cont normal și
FBE: EMG-RO, EMG-RO-FBE, EMG-HU, EMG-HU-FBE, EMG-BG, EMG-BG-FBE. Le bifezi pe toate șase, iar programul trimite pe fiecare
factură seria potrivită.
- Fără
series: 422series_required. O serie nebifată: 422series_not_allowed, cu seriile bifate în mesaj. O serie închisă sau ștearsă în FacturOne: 409series_closed. - Recomandăm serii folosite doar de API. Dacă bifezi o serie pe care emiți și de mână, numerele se intercalează. Verificarea zilnică te anunță (în aplicația API FacturOne și pe e-mail) dacă pe o serie bifată apare o factură emisă din FacturOne.
- Dacă firma nu are o serie implicită în FacturOne, o serie nouă nu se poate crea de aici. Poți bifa o serie existentă.
Numărul facturii (number, opțional)
Dacă programul tău își ține propria numerotare, trimite number mereu. Altfel nu-l trimite
deloc.
- Fără
number, numărul îl dă FacturOne AI: cel mai mare număr folosit pe serie + 1, inclusiv numerele trimise de programul tău. Golurile din urmă nu se umplu, ca numerotarea să rămână în ordinea datelor. - Cu
number, factura primește exact acel număr, dacă e liber:- folosit deja pe serie: 409
number_taken, nu se emite nimic; - mai mare decât următorul: se emite, iar răspunsul are avertismentul
gap_after, cu numerele sărite; - sub ultimul folosit, dar liber (un gol din urmă, de exemplu o corectură): se emite, cu avertismentul
number_out_of_order. Verifică data facturii. Următoarea factură fărănumberprimește tot cel mai mare număr + 1; - sub primul număr al seriei din FacturOne: 422
number_invalid.
- folosit deja pe serie: 409
- Avertismentele vin în
warnings([{code, message}], gol de obicei), în răspuns și în webhook-uri. Fiecare apare și ca alertă în aplicația API FacturOne. - Numărul se dă o singură dată pe cerere: o reîncercare cu aceeași
Idempotency-Keyfolosește același număr. Aceeași cheie cu altnumberîntoarce 409idempotency_conflict. - Răspunsul are numărul în
numberși numărul complet îndocument_number(EMG-HU-FBE 143).
Răspuns 201 (pe scurt):
curl -X POST https://api.facturone.com/v1/invoices \
-H "Authorization: Bearer $FACTURONE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: emag-hu-fbe-3411" \
-d '{"series": "EMG-HU-FBE", "number": 143, "client": {"cui": "RO12345674"}, "lines": [{"name": "Comanda eMAG 3411", "quantity": 1, "unit_price": 100, "vat_rate": 21}]}'{
"id": "inv_8a7b6c5d4e3f2a1b0c9d8e7f",
"status": "issued",
"series": "EMG-HU-FBE",
"number": 143,
"document_number": "EMG-HU-FBE 143",
"warnings": [
{
"code": "gap_after",
"message": "Numărul 143 lasă un gol pe seria EMG-HU-FBE: 2 numere nefolosite (141–142). Următoarea factură fără number primește 144."
}
]
}Emiteri simultane și răspunsuri neclare
- Pe aceeași serie se emite o singură factură odată. Seriile diferite nu se așteaptă una pe alta. Cererile
simultane pe o serie așteaptă la rând câteva secunde; dacă rândul durează prea mult primești 503
series_busycuRetry-After. Reîncerci cu aceeașiIdempotency-Key. - Dacă FacturOne nu confirmă o factură (rețea, timeout), nu o trimitem orbește a doua oară: o căutăm întâi, după
număr. O a doua trimitere are același număr, deci nu poate face o factură dublă. Dacă nu putem afla ce s-a
întâmplat, primești 202 cu factura în
"status": "pending_confirmation"(fără număr) șiRetry-After: 60. Vezi mai jos.
Facturi neconfirmate (pending_confirmation)
Câmpul status al facturii e issued (emisă), pending_confirmation (FacturOne nu a
confirmat-o încă) sau failed (nu s-a creat). O factură neconfirmată:
- are
numberșidocument_numbergoale; PDF-ul, e-mailul și stornarea întorc 409invoice_pending_confirmationpână se lămurește; - se verifică automat la câteva minute, la fiecare
GET /v1/invoices/{id}(cel mult o dată pe minut) și la reîncercarea cu aceeașiIdempotency-Key. Cererea nu se mai trimite a doua oară; - dacă o găsim în FacturOne, devine
issued, cu număr, și primeștiinvoice.created; - dacă după 15 minute tot nu există, devine
failed: nu se numără în limita lunară și primeștiinvoice.failed. Aceeași cheie întoarce de acum 409invoice_failed; trimite factura din nou cu o cheie nouă.
Facturi
POST /v1/invoices — emite o factură
Antetul Idempotency-Key e obligatoriu: un identificator unic al facturii în sistemul tău
(ex. abonament-1042-2026-12). Aceeași cheie cu același conținut întoarce aceeași factură
(antet Idempotent-Replayed: true), deci poți reîncerca liniștit după o eroare de rețea.
Aceeași cheie cu alt conținut întoarce 409. Cheile se păstrează 30 de zile.
| Câmp | Tip | Obligatoriu | Ce înseamnă |
|---|---|---|---|
client.type | text | nu | company (implicit cu CUI) sau individual (persoană fizică) |
client.cui | text | da, la firme | CUI cu sau fără RO. Restul datelor firmei se completează din baza FacturOne AI. |
client.name | text | la persoane fizice | Denumirea / numele. La firme, doar dacă vrei să înlocuiești ce știm. |
client.address, client.city, client.county | text | la persoane fizice și la firme necunoscute | Adresa, localitatea, județul (nume sau cod: Cluj / CJ). În București: sectorul. |
client.country | text | nu | Cod de două litere; implicit RO. |
client.email, client.phone | text | nu | Contact. |
lines[] | listă | da (1–100) | Rândurile facturii. |
lines[].name | text | da | Denumirea produsului sau serviciului. |
lines[].quantity | număr | da | Mai mare decât 0, maximum 3 zecimale. |
lines[].unit | text | nu | Unitatea de măsură; implicit buc. |
lines[].unit_price | număr | da | Preț unitar fără TVA, maximum 2 zecimale. |
lines[].vat_rate | număr | da | 21, 11 sau 0. Firmă neplătitoare de TVA: 0. |
series | text | da | Una din seriile bifate pentru API (vezi „Serii și numere”). Aceleași reguli în test și pe live. |
number | număr întreg | nu | Numărul facturii. Fără el, îl dă FacturOne AI: cel mai mare număr folosit pe serie + 1. Cu el, factura primește exact acest număr, dacă e liber. |
issue_date | AAAA-LL-ZZ | nu | Implicit azi. Cel mult câteva zile în urmă și doar dacă seria rămâne cronologică. |
due_date | AAAA-LL-ZZ | nu | Implicit data facturii + 15 zile. |
currency | text | nu | RON implicit; altă monedă cu cursul BNR al datei facturii. |
notes | text | nu | Observații pe factură (maximum 1000 de caractere). |
send_to_efactura | da / nu | nu | Implicit setarea e-Factura automată a firmei. Cu false, factura nu pleacă la ANAF nici prin trimiterea automată. |
Corp:
Cerere:
Răspuns 201:
{
"series": "API",
"client": {
"cui": "RO12345674"
},
"lines": [
{
"name": "Abonament noiembrie 2026",
"quantity": 1,
"unit": "buc",
"unit_price": 199.0,
"vat_rate": 21
}
],
"notes": "Plata în 14 zile.",
"send_to_efactura": true
}curl -X POST https://api.facturone.com/v1/invoices \
-H "Authorization: Bearer $FACTURONE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: abonament-1042-2026-12" \
-d '{"series": "API", "client": {"cui": "RO12345674"}, "lines": [{"name": "Abonament noiembrie 2026", "quantity": 1, "unit": "buc", "unit_price": 199.0, "vat_rate": 21}], "notes": "Plata în 14 zile.", "send_to_efactura": true}'{
"id": "inv_3f9c1d2e7a8b4c5d6e7f8a9b",
"object": "invoice",
"mode": "test",
"status": "issued",
"series": "API",
"number": 12,
"document_number": "TEST API 12",
"issue_date": "2026-12-01",
"due_date": "2026-12-16",
"currency": "RON",
"exchange_rate": null,
"client": {
"type": "company",
"name": "CLIENT EXEMPLU SRL",
"cui": "RO12345674",
"reg_com": "J40/123/2020",
"address": "Str. Exemplu 1",
"city": "SECTOR1",
"county": "București",
"sector": 1,
"country": "RO",
"email": null,
"phone": null
},
"lines": [
{
"name": "Abonament noiembrie 2026",
"quantity": 1.0,
"unit": "buc",
"unit_price": 199.0,
"vat_rate": 21,
"net_amount": 199.0,
"vat_amount": 41.79,
"total": 240.79
}
],
"totals": {
"net": 199.0,
"vat": 41.79,
"total": 240.79,
"vat_breakdown": [
{
"category": "S",
"rate": 21,
"taxable": 199.0,
"vat": 41.79
}
]
},
"notes": "Plata în 14 zile.",
"send_to_efactura": true,
"efactura": {
"status": "accepted",
"upload_index": null,
"errors": []
},
"kind": "invoice",
"reverses": null,
"cancelled_by": null,
"paid_at": null,
"email_status": "none",
"email_status_at": null,
"warnings": [],
"created_at": "2026-12-01T05:00:03Z"
}GET /v1/invoices — lista facturilor emise prin API
Filtre: date_from, date_to (data facturii), series, client_cui,
efactura_status (not_sent, pending, accepted, rejected).
Paginare: limit (1–100, implicit 20) și starting_after = next_cursor din
răspunsul anterior. Cele mai noi primele.
curl "https://api.facturone.com/v1/invoices?date_from=2026-12-01&efactura_status=rejected&limit=50" \
-H "Authorization: Bearer $FACTURONE_API_KEY"{
"object": "list",
"data": [
"…facturi…"
],
"has_more": true,
"next_cursor": "inv_3f9c1d2e7a8b4c5d6e7f8a9b"
}GET /v1/invoices/{id} — o factură
kind e invoice sau storno; cancelled_by arată stornarea, dacă există;
paid_at apare când factura e încasată integral în FacturOne.
curl https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b \
-H "Authorization: Bearer $FACTURONE_API_KEY"GET /v1/invoices/{id}/pdf — PDF-ul
În test, fiecare pagină are „TEST — fără valoare fiscală”.
curl https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/pdf \
-H "Authorization: Bearer $FACTURONE_API_KEY" -o factura.pdfGET /v1/invoices/{id}/pdf-link — link semnat, cu expirare
Un link pe care îl poți pune într-un e-mail sau în contul clientului tău, fără cheie.
expires_in: între 60 și 604800 secunde (7 zile); implicit 3600. Linkul expirat întoarce 410.
curl "https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/pdf-link?expires_in=86400" \
-H "Authorization: Bearer $FACTURONE_API_KEY"{
"url": "https://api.facturone.com/v1/files/eyJjIjoi…",
"expires_at": "2026-12-02T05:00:03Z"
}GET /v1/invoices/{id}/efactura — starea în e-Factura
not_sent (nu s-a cerut trimiterea), pending (în coadă sau la ANAF), accepted,
rejected. La respingere, errors are motivele pe înțeles; textul original ANAF e în
detail.
Înainte să trimitem o factură la ANAF, îi verificăm XML-ul la serviciul de validare ANAF. Dacă are erori,
nu o trimitem: starea devine rejected, cu motivele, și primești evenimentul efactura.rejected.
Corectezi factura în FacturOne; la următoarea trimitere automată o verificăm din nou. În test: rezultatul
validării XML-ului la serviciul public ANAF.
curl https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/efactura \
-H "Authorization: Bearer $FACTURONE_API_KEY"{
"status": "rejected",
"upload_index": "5012345678",
"errors": [
{
"code": "BR-RO-101",
"message": "Pentru București, localitatea trebuie să fie sectorul: SECTOR1 … SECTOR6.",
"detail": "textul ANAF"
}
],
"test": false,
"validation": null,
"updated_at": "2026-12-01T09:12:00Z"
}Trimitere pe e-mail
POST /v1/invoices/{id}/email
Cheia are nevoie de dreptul email:send. Pe live, e-mailul pleacă din FacturOne, cu PDF-ul atașat,
la fel ca din ecranul facturii, cu răspuns la adresa firmei tale. Răspunsul e 202 cu
"status": "queued": FacturOne nu confirmă livrarea.
Factura arată starea ultimei trimiteri în email_status, cu momentul în email_status_at:
none: niciun e-mail trimis prin API;queued: pe live, e-mailul a fost predat către FacturOne. Rămânequeued: FacturOne nu ne confirmă încă livrarea, așa că nu putem spune dacă a ajuns în căsuța clientului. Totqueuedrămâne și când FacturOne nu a răspuns la trimitere (502email_not_sent): e-mailul poate să fi plecat;sent_to_provider: în test, e-mailul a fost predat furnizorului nostru de e-mail;failed: e-mailul sigur nu a plecat.
to: 1–5 adrese, verificate.subjectșimessagesunt opționale; poți folosi{nr_factura},{data_factura},{data_scadenta},{firma_client},{firma}.- Limită pe zi, pe firmă, numărată în adrese (implicit 200 pe live). La depășire: 429
email_limit_reached, până la miezul nopții. Idempotency-Keye opțional; cu el, aceeași cerere nu trimite e-mailul de două ori.- În test, e-mailul pleacă doar la adresa contului tău FacturOne, cu „TEST” în subiect și un link spre
PDF-ul de test. Adresele cerute apar în
requested_to.
curl -X POST https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/email \
-H "Authorization: Bearer $FACTURONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to": ["[email protected]"], "subject": "Factura {nr_factura}", "message": "Bună ziua,\n\nAveți atașată factura {nr_factura} din {data_factura}.\n\nMulțumim!"}'{
"object": "invoice_email",
"id": "eml_5d4c3b2a1f0e9d8c7b6a5f4e",
"invoice_id": "inv_3f9c1d2e7a8b4c5d6e7f8a9b",
"livemode": true,
"to": [
"[email protected]"
],
"subject": "Factura API 12",
"status": "queued",
"created_at": "2026-12-01T05:01:10Z"
}Stornare
POST /v1/invoices/{id}/storno
Stornare totală: o factură nouă cu aceleași rânduri și cantități negative, cu „Storno factura seria X nr. Y”
în descriere. Merge la e-Factura ca orice factură. Factura stornată primește cancelled_by și evenimentul
invoice.cancelled.
Idempotency-Keye obligatoriu. O factură se stornează o singură dată: a doua încercare, cu altă cheie, întoarce 409already_cancelled.- Corpul e opțional:
issue_date(implicit azi, nu înaintea facturii),send_to_efactura(implicit ca la factura stornată),notes(text adăugat în descriere). - Seria: implicit seria facturii stornate, cu numărul dat de FacturOne AI. Cu
seriesalegi altă serie bifată pentru API; cunumber, numărul. Aceleași reguli ca la emitere: 409number_takenla un număr folosit,warningsla un gol sau la un număr sub ultimul. Dacă seria facturii stornate nu mai e bifată, primești 422series_not_allowed: o bifezi din nou sau trimiți altă serie înseries. - Stornarea păstrează cursul valutar al facturii stornate. Stornările se numără împreună cu facturile în facturile incluse în lună, dar nu sunt oprite niciodată de limită.
- Stornarea parțială (doar unele rânduri sau cantități) nu e disponibilă: o cerere cu
linesprimește 422partial_storno_not_supported. Stornezi toată factura și emiți una nouă cu ce rămâne. - În XML-ul e-Factura al stornării de test apare referința la factura stornată
(
cac:BillingReference, cu numărul și data ei). Pe live, XML-ul îl generează programul de facturare; referința apare în descriere și, după actualizarea programului, și în XML. - În test se face o stornare de test, cu aceleași reguli, pe numerotarea de test.
curl -X POST https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/storno \
-H "Authorization: Bearer $FACTURONE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: storno-abonament-1042-2026-12" \
-d '{"notes": "Abonament anulat"}'Webhook-uri
Îți trimitem un POST cu evenimentul în format JSON la adresele HTTPS adăugate în API
FacturOne → Webhook-uri, pentru evenimentele alese. Evenimentele din modul test pleacă și ele, cu
"livemode": false.
| Eveniment | Când |
|---|---|
invoice.created | S-a emis o factură (și o stornare: are kind = storno). |
efactura.accepted | ANAF a acceptat factura. |
efactura.rejected | ANAF a respins factura sau validarea dinaintea trimiterii a găsit erori; motivele în efactura.errors. |
invoice.paid | Factura apare încasată integral în FacturOne (încasări marcate în program). |
invoice.cancelled | Factura a fost stornată; cancelled_by arată stornarea. |
invoice.failed | Facturare nu a creat factura rămasă neconfirmată (status failed); nu se numără în limită. |
monthly_limit.warning | Ai ajuns la 80% sau la 100% din facturile incluse în lună. |
Exemplu:
{
"id": "evt_9a8b7c6d5e4f3a2b1c0d9e8f",
"object": "event",
"type": "invoice.paid",
"created": "2026-12-12T10:20:00Z",
"livemode": true,
"data": {
"object": {
"id": "inv_3f9c1d2e7a8b4c5d6e7f8a9b",
"object": "invoice",
"mode": "live",
"status": "issued",
"series": "API",
"number": 12,
"document_number": "API 12",
"issue_date": "2026-12-01",
"due_date": "2026-12-16",
"currency": "RON",
"exchange_rate": null,
"client": {
"type": "company",
"name": "CLIENT EXEMPLU SRL",
"cui": "RO12345674",
"reg_com": "J40/123/2020",
"address": "Str. Exemplu 1",
"city": "SECTOR1",
"county": "București",
"sector": 1,
"country": "RO",
"email": null,
"phone": null
},
"lines": [
{
"name": "Abonament noiembrie 2026",
"quantity": 1.0,
"unit": "buc",
"unit_price": 199.0,
"vat_rate": 21,
"net_amount": 199.0,
"vat_amount": 41.79,
"total": 240.79
}
],
"totals": {
"net": 199.0,
"vat": 41.79,
"total": 240.79,
"vat_breakdown": [
{
"category": "S",
"rate": 21,
"taxable": 199.0,
"vat": 41.79
}
]
},
"notes": "Plata în 14 zile.",
"send_to_efactura": true,
"efactura": {
"status": "accepted",
"upload_index": null,
"errors": []
},
"kind": "invoice",
"reverses": null,
"cancelled_by": null,
"paid_at": "2026-12-12T10:20:00Z",
"email_status": "none",
"email_status_at": null,
"warnings": [],
"created_at": "2026-12-01T05:00:03Z"
}
}
}{
"id": "evt_1b2c3d4e5f6a7b8c9d0e1f2a",
"object": "event",
"type": "monthly_limit.warning",
"created": "2026-12-20T08:00:00Z",
"livemode": true,
"data": {
"object": {
"object": "monthly_usage",
"month": "2026-12",
"threshold": 80,
"included": 100,
"used": 80,
"over_limit": "block",
"reset_at": "2027-01-01T00:00:00+02:00"
}
}
}Antete și semnătură
FacturOne-Signature: t=1765534800,v1=5f2b…:v1e HMAC-SHA256, în hex, al textului<t>.<corpul exact>, cu secretul adresei (whsec_…, arătat o singură dată când adaugi adresa).FacturOne-Timestamp(acelașit),FacturOne-Event-Id,FacturOne-Event-Type.- Verifică semnătura pe corpul brut, nu pe JSON-ul reconstruit, și respinge mesajele mai vechi de 5 minute.
- Rotirea secretului (API FacturOne → Webhook-uri → „Schimbă secretul”): secretul nou semnează imediat, iar
cel vechi încă 24 de ore. În acest timp antetul are două valori
v1(t=…,v1=<cu secretul nou>,v1=<cu cel vechi>); mesajul e bun dacă oricare se potrivește. Exemplele de mai jos fac asta.
Verificarea semnăturii
Aceeași verificare în Node, PHP și Python; alegi limbajul deasupra codului.
<?php
// $body: corpul exact, așa cum a venit (file_get_contents("php://input")).
function verify_facturone(string $body, string $header, string $secret, int $tolerance = 300): bool
{
$t = 0;
$signatures = [];
foreach (explode(",", $header) as $part) {
[$name, $value] = array_pad(explode("=", trim($part), 2), 2, "");
if ($name === "t") {
$t = (int) $value;
} elseif ($name === "v1") {
$signatures[] = $value;
}
}
if ($t === 0 || abs(time() - $t) > $tolerance) {
return false;
}
$expected = hash_hmac("sha256", $t . "." . $body, $secret);
// După rotirea secretului, antetul are două v1 timp de 24 de ore: oricare poate fi bun.
foreach ($signatures as $signature) {
if (hash_equals($expected, $signature)) {
return true;
}
}
return false;
}$body = file_get_contents("php://input");
$header = $_SERVER["HTTP_FACTURONE_SIGNATURE"] ?? "";
if (!verify_facturone($body, $header, getenv("FACTURONE_WEBHOOK_SECRET"))) {
http_response_code(400);
exit;
}
$event = json_decode($body, true);
// Același eveniment poate veni de două ori: ține minte $event["id"].
http_response_code(200);// Node.js 18+. rawBody: Buffer cu corpul exact, așa cum a venit.
import crypto from "node:crypto";
export function verifyFacturOne(rawBody, header, secret, toleranceSeconds = 300) {
const parts = String(header || "").split(",").map((part) => part.trim().split("="));
const t = Number((parts.find(([name]) => name === "t") || [])[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(rawBody).digest();
// După rotirea secretului, antetul are două v1 timp de 24 de ore: oricare poate fi bun.
return parts
.filter(([name, value]) => name === "v1" && /^[0-9a-f]{64}$/.test(value || ""))
.some(([, value]) => crypto.timingSafeEqual(Buffer.from(value, "hex"), expected));
}// Express: citește corpul brut, nu JSON-ul refăcut.
import express from "express";
const app = express();
app.post("/webhooks/facturone", express.raw({ type: "application/json" }), (req, res) => {
const ok = verifyFacturOne(req.body, req.get("FacturOne-Signature"), process.env.FACTURONE_WEBHOOK_SECRET);
if (!ok) return res.status(400).send("semnătură greșită");
const event = JSON.parse(req.body.toString("utf8"));
// Același eveniment poate veni de două ori: ține minte event.id și sari peste repetări.
res.sendStatus(200); // în cel mult 10 secunde; lucrul lung, după
});import hashlib
import hmac
import time
def verify_facturone(body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
# body: corpul exact, așa cum a venit.
t, signatures = 0, []
for part in (header or "").split(","):
name, _, value = part.strip().partition("=")
if name == "t" and value.isdigit():
t = int(value)
elif name == "v1":
signatures.append(value)
if not t or abs(time.time() - t) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
# După rotirea secretului, antetul are două v1 timp de 24 de ore: oricare poate fi bun.
return any(hmac.compare_digest(expected, signature) for signature in signatures)# Flask
import os
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/webhooks/facturone")
def facturone_webhook():
body = request.get_data() # octeții exacți
if not verify_facturone(body, request.headers.get("FacturOne-Signature", ""), os.environ["FACTURONE_WEBHOOK_SECRET"]):
abort(400)
event = request.get_json()
# Același eveniment poate veni de două ori: ține minte event["id"].
return "", 200Livrare și reîncercări
- Răspunde cu un cod 2xx în cel mult 10 secunde. Orice alt răspuns, o redirecționare sau lipsa răspunsului înseamnă eșec; reîncercăm după 1 minut, 5 minute, 30 de minute, 2 ore și 12 ore, apoi ne oprim.
- Același eveniment poate ajunge de două ori, iar ordinea nu e garantată. Ține minte
id-ul evenimentului; pentru starea curentă, citește factura cuGET /v1/invoices/{id}. - Adresa trebuie să fie publică, pe HTTPS. Nu trimitem la adrese din rețele private sau locale și nu urmăm redirecționări.
- Fiecare adresă primește evenimentele din „Test și live” (implicit), „Doar test” sau „Doar live”.
- O adresă care eșuează de 20 de ori la rând sau care nu a avut nicio livrare reușită 3 zile o oprim automat (pragurile pot diferi pe cont) și îți trimitem un e-mail cu ultimul răspuns primit. O repornești din API FacturOne → Webhook-uri.
- O livrare eșuată se poate trimite din nou cu „Retrimite” din jurnal: același eveniment, același
id, deci îl recunoști dacă l-ai procesat deja. - Butonul „Trimite un test” din API FacturOne → Webhook-uri trimite evenimentul
webhook.test. Jurnalul de livrări (ultimele 100 de livrări; le păstrăm 90 de zile) arată fiecare încercare și răspunsul primit.
Erori
Toate erorile au același format: cod stabil (în engleză, pentru programul tău), mesaj în română
(pentru oameni), câmpul greșit și id-ul cererii (îl găsești și în antetul X-Request-Id;
trimite-l când ne scrii).
Fiecare răspuns are antetul X-Request-Id. Dacă trimiți tu un X-Request-Id (8–64 de caractere:
litere, cifre și . _ : -), îl păstrăm, ca să găsești cererea în jurnalele tale și în ale noastre;
altfel generăm unul (req_…). Lista completă a codurilor e mai jos și în contractul OpenAPI
(x-error-codes).
| Cod | HTTP | Ce înseamnă | Ce faci |
|---|---|---|---|
bad_request | 400 | Cererea nu poate fi citită. | Verifică metoda, antetele și corpul cererii. |
invalid_json | 400 | Corpul cererii nu este JSON valid. | Trimite JSON valid, cu Content-Type: application/json. |
idempotency_key_required | 400 | Lipsește antetul Idempotency-Key. | Trimite un identificator unic al operației (ex. comanda-1042), același la fiecare reîncercare. |
idempotency_key_invalid | 400 | Idempotency-Key are alt format decât 1–128 caractere ASCII vizibile. | Folosește doar litere, cifre și semne, fără spații. |
invalid_cursor | 400 | Cursorul de paginare nu este valid. | Folosește next_cursor din răspunsul anterior. |
missing_api_key | 401 | Lipsește cheia API. | Trimite antetul Authorization: Bearer <cheie API>. |
invalid_api_key | 401 | Cheia nu există sau e scrisă greșit. | Verifică cheia; dacă ai pierdut-o, creează alta în API FacturOne → Chei API. |
api_key_revoked | 401 | Cheia a fost revocată. | Folosește o cheie activă. |
forbidden | 403 | Acces interzis. | Verifică cheia și drepturile ei. |
api_disabled | 403 | API-ul nu este pornit pentru firmă. | Activează aplicația API FacturOne din App Store sau scrie-ne. |
plan_not_allowed | 403 | Planul firmei nu include API-ul sau cheile live. | Folosește o cheie de test sau schimbă planul. |
insufficient_scope | 403 | Cheia nu are dreptul cerut (ex. email:send). | Creează o cheie cu dreptul necesar în API FacturOne → Chei API. |
live_invoices_disabled | 403 | Facturile reale prin API nu sunt încă pornite pentru firmă. | Lucrează cu o cheie de test până la pornire. |
email_disabled | 403 | Trimiterea pe e-mail prin API e oprită în acest mod. | Scrie-ne dacă ai nevoie de ea. |
not_found | 404 | Ruta sau fișierul nu există. | Verifică adresa. |
invoice_not_found | 404 | Factura nu există pentru cheia folosită (alt id, altă firmă sau celălalt mod, test / live). | Verifică id-ul și cheia. |
method_not_allowed | 405 | Metoda nu este permisă pe această rută. | Verifică metoda (GET, POST …). |
idempotency_conflict | 409 | Idempotency-Key a fost folosită deja pentru alt conținut. | Folosește o cheie nouă pentru o operație nouă. |
idempotency_key_in_progress | 409 | O cerere cu aceeași Idempotency-Key încă rulează. | Reîncearcă după Retry-After. |
already_cancelled | 409 | Factura e deja stornată. | Nu mai e nimic de făcut; cancelled_by arată stornarea. |
storno_in_progress | 409 | O altă stornare a acestei facturi nu s-a terminat. | Reîncearcă stornarea cu aceeași Idempotency-Key. |
number_taken | 409 | Numărul trimis în number e deja folosit pe serie. Fără number: un număr luat chiar atunci de o factură emisă de mână pe aceeași serie. | Cu number: trimite alt număr sau nu-l trimite. Fără number: reîncearcă după Retry-After, cu aceeași Idempotency-Key. |
series_closed | 409 | Seria bifată pentru API a fost închisă sau ștearsă în FacturOne. | Redeschide seria în FacturOne sau bifează alta: API FacturOne → Facturare → Serii pentru API. |
invoice_pending_confirmation | 409 | FacturOne nu a confirmat încă factura (status pending_confirmation). | Reîncearcă după Retry-After sau așteaptă invoice.created. |
invoice_failed | 409 | Factura acestei Idempotency-Key nu s-a creat în FacturOne și nu se numără. | Trimite factura din nou, cu o Idempotency-Key nouă. |
link_expired | 410 | Linkul semnat a expirat. | Cere un link nou cu /pdf-link. |
payload_too_large | 413 | Corpul cererii depășește 256 KB. | Trimite mai puține rânduri pe factură. |
unsupported_media_type | 415 | Corpul nu este trimis ca JSON. | Trimite Content-Type: application/json. |
validation_error | 422 | Un câmp lipsește sau are alt format. | Corectează câmpul din field (vezi și details). |
client_not_found | 422 | Nu găsim firma cu acest CUI. | Verifică CUI-ul sau trimite denumirea, adresa, localitatea și județul clientului. |
client_incomplete | 422 | Clientului îi lipsesc date cerute de e-Factura (adresă, localitate, județ). | Completează câmpul din field. |
email_invalid | 422 | Adresa de e-mail nu este validă. | Corectează adresa din field. |
series_required | 422 | Lipsește series: fiecare factură spune pe ce serie se emite. | Trimite una din seriile bifate în API FacturOne → Facturare → Serii pentru API. |
series_invalid | 422 | Seria are alt format decât 1–20 litere, cifre sau cratime. | Trimite numele seriei exact ca în FacturOne (ex. API, EMG-HU-FBE). |
series_not_allowed | 422 | Seria trimisă nu e bifată pentru API (în test și pe live). | Bifeaz-o în API FacturOne → Facturare → Serii pentru API sau trimite una din seriile bifate; mesajul le arată. |
number_invalid | 422 | Numărul trimis e sub primul număr al seriei din FacturOne. | Trimite un număr de la primul număr al seriei în sus sau nu trimite number. |
date_in_future | 422 | Data e în viitor. | Trimite data de azi sau una din trecut. |
date_too_old | 422 | Data e mai veche decât permite FacturOne. | Folosește o dată mai apropiată. |
date_not_chronological | 422 | Pe serie există deja o factură cu dată mai nouă. | Folosește data ultimei facturi din serie sau una mai nouă. |
due_date_before_issue | 422 | Scadența e înaintea datei facturii. | Trimite o scadență egală sau mai târzie. |
storno_date_before_invoice | 422 | Data stornării e înaintea datei facturii stornate. | Folosește data facturii sau una mai nouă. |
vat_rate_invalid | 422 | Cota de TVA nu este permisă sau nu există în contul firmei. | Folosește una dintre cotele firmei (ex. 21, 11, 0). |
vat_not_allowed | 422 | Firma nu este plătitoare de TVA, dar factura are TVA. | Trimite cota 0 pe rânduri. |
currency_not_supported | 422 | Moneda nu este un cod ISO de trei litere. | Trimite codul monedei (ex. RON, EUR). |
exchange_rate_unavailable | 422 | Nu există curs BNR pentru moneda și data facturii. | Reîncearcă după publicarea cursului sau emite în RON. |
facturare_rejected | 422 | FacturOne a refuzat factura la propriile verificări. | Verifică datele facturii; codul FacturOne e în mesaj. |
storno_not_allowed | 422 | O factură de stornare nu se mai stornează. | Stornează factura inițială. |
partial_storno_not_supported | 422 | Stornarea parțială nu este disponibilă. | Stornează toată factura, apoi emite una nouă cu ce rămâne. |
account_email_missing | 422 | Contul FacturOne nu are adresă de e-mail pentru e-mailurile de test. | Adaugă adresa în contul FacturOne. |
rate_limited | 429 | Prea multe cereri într-un minut. | Așteaptă Retry-After secunde; urmărește X-RateLimit-Remaining. |
daily_invoice_limit | 429 | Ai atins limita de facturi pe zi. | Reîncearcă după Retry-After (miezul nopții, ora României). |
monthly_limit_reached | 429 | Ai atins facturile incluse pe lună (stornările incluse), iar firma are blocare la depășire. Stornările nu sunt oprite. | Nu reîncerca automat: așteaptă reset_at din details sau cere mărirea limitei. |
email_limit_reached | 429 | Ai atins limita de e-mailuri pe zi. | Reîncearcă după Retry-After (miezul nopții). |
internal_error | 500 | Eroare neașteptată la noi. | Reîncearcă peste câteva minute, cu aceeași Idempotency-Key; dacă persistă, trimite-ne request_id. |
email_not_sent | 502 | FacturOne nu a trimis e-mailul sau nu a confirmat trimiterea. | Verifică email_status al facturii înainte să reîncerci, ca să nu trimiți de două ori. |
facturare_unavailable | 503 | FacturOne nu răspunde sau nu ne putem conecta. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |
series_busy | 503 | Seria e ocupată cu alte facturi ale firmei prin API. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |
busy | 503 | Prea multe facturi de test simultan pe aceeași serie. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |
upstream_timeout | 504 | FacturOne nu a răspuns la timp. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |
{
"error": {
"code": "validation_error",
"message": "Trebuie să fie mai mare decât 0.",
"field": "lines[0].quantity",
"request_id": "req_8c1d2e3f4a5b6c7d8e9f0a1b"
}
}Limite
Cereri și facturi pe zi
Limitele depind de mod și de plan (test: 30 de cereri pe minut și 200 de facturi pe zi; Pro: 60 și 500;
Max: 120 și 2.000). Fiecare răspuns are X-RateLimit-Limit, X-RateLimit-Remaining,
X-RateLimit-Reset. La depășire primești 429 și antetul Retry-After (secunde).
Limitele tale exacte: GET /v1/me.
Facturi incluse pe lună
Pe live, planul include un număr de facturi pe lună calendaristică, după ora României: Pro 100, Max 1.000, dacă nu am convenit altfel. Stornările se numără împreună cu facturile, dar o stornare nu e oprită niciodată de limită: la limita atinsă trece și se numără peste ea. Facturile de test nu se numără.
- Răspunsurile pentru cheile live au
X-Monthly-Limit(incluse),X-Monthly-Used(facturi și stornări folosite luna aceasta) șiX-Monthly-Reset(când se resetează, ex.2027-01-01T00:00:00+02:00). - La limită, o factură nouă primește 429
monthly_limit_reached(o stornare nu), cuRetry-Afterpână la resetare șidetails(limit,used,reset_at). Nu reîncerca automat: limita se resetează pe 1 ale lunii sau o mărim la cerere. - La 80% și la 100% primești un e-mail (îl poți opri din aplicația API FacturOne) și evenimentul
monthly_limit.warning.
{
"error": {
"code": "monthly_limit_reached",
"message": "Ai atins limita lunară de 100 facturi prin API. Limita se resetează pe 1 ale lunii sau o poți mări din FacturOne. Stornările trec în continuare.",
"field": null,
"request_id": "req_…",
"details": [
{
"limit": 100,
"used": 100,
"reset_at": "2027-01-01T00:00:00+02:00"
}
]
}
}Modul test
- Aceleași reguli de serie și număr ca pe live: doar seriile bifate pentru API,
numberopțional, cu aceleași erori și avertismente. Numerotarea e separată: facturile de test au număr propriu (TEST API 1,TEST API 2…), pe fiecare serie, și nu ating numerele reale. - XML-ul e-Factura se generează la fel ca pentru facturile reale și se validează la serviciul public ANAF; dacă ANAF nu răspunde, rulează o validare locală, iar răspunsul spune care.
- Le vezi în aplicație la API FacturOne → Facturare → Facturi de test, cu PDF, XML și răspunsul validării. Se șterg singure după 30 de zile sau cu butonul „Șterge datele de test”.
- E-mailurile de test pleacă doar la adresa contului tău. Webhook-urile pleacă, cu
"livemode": false. - Stornarea funcționează și în test. Facturile de test nu se numără în limita lunară.
Exemple de cod
Fiecare program face tot drumul unei facturi: o emite cu Idempotency-Key, o citește, descarcă PDF-ul,
o trimite pe e-mail și o stornează. Le rulăm automat pe un server de test, cu o cheie de test, la fiecare
versiune. Pornește-le cu FACTURONE_API_KEY în mediu; cu o cheie fo_test_… nu se creează nimic
real.
#!/usr/bin/env bash
# curl + jq. Aceeași Idempotency-Key la orice reîncercare: nu se emite a doua factură.
set -euo pipefail
API="${FACTURONE_API_URL:-https://api.facturone.com/v1}"
AUTH="Authorization: Bearer $FACTURONE_API_KEY"
invoice=$(curl -sS --fail-with-body -X POST "$API/invoices" -H "$AUTH" \
-H "Content-Type: application/json" -H "Idempotency-Key: comanda-1042" \
-d '{"series": "API", "client": {"cui": "RO12345674"},
"lines": [{"name": "Abonament noiembrie 2026", "quantity": 1, "unit_price": 199, "vat_rate": 21}]}')
id=$(jq -r .id <<<"$invoice")
echo "Emisă: $(jq -r .document_number <<<"$invoice") ($id)"
jq -r '.warnings[] | "Avertisment: \(.code): \(.message)"' <<<"$invoice"
curl -sS --fail-with-body "$API/invoices/$id" -H "$AUTH" | jq -r '"Stare: \(.status), e-Factura: \(.efactura.status)"'
curl -sS --fail-with-body "$API/invoices/$id/pdf" -H "$AUTH" -o factura.pdf
echo "PDF: factura.pdf"
curl -sS --fail-with-body -X POST "$API/invoices/$id/email" -H "$AUTH" \
-H "Content-Type: application/json" -d '{"to": ["[email protected]"]}' | jq -r '"Email: \(.status)"'
storno=$(curl -sS --fail-with-body -X POST "$API/invoices/$id/storno" -H "$AUTH" -H "Idempotency-Key: comanda-1042-storno")
echo "Stornare: $(jq -r .document_number <<<"$storno")"<?php
// PHP 8 cu extensia curl.
define('FACTURONE_API', getenv('FACTURONE_API_URL') ?: 'https://api.facturone.com/v1');
define('FACTURONE_KEY', getenv('FACTURONE_API_KEY'));
function facturone(string $method, string $path, ?array $body = null, ?string $idempotencyKey = null, bool $raw = false)
{
$headers = ['Authorization: Bearer ' . FACTURONE_KEY];
if ($body !== null) {
$headers[] = 'Content-Type: application/json';
}
if ($idempotencyKey !== null) {
$headers[] = 'Idempotency-Key: ' . $idempotencyKey;
}
$ch = curl_init(FACTURONE_API . $path);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => $method,
CURLOPT_HTTPHEADER => $headers,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
if ($response === false || $status >= 400) {
$error = json_decode((string) $response, true)['error'] ?? ['code' => curl_error($ch), 'message' => ''];
throw new RuntimeException("$status {$error['code']}: {$error['message']}");
}
return $raw ? $response : json_decode($response, true);
}
// Aceeași Idempotency-Key la reîncercare: nu se emite a doua factură.
$invoice = facturone('POST', '/invoices', [
'series' => 'API', // una din seriile bifate în API FacturOne → Facturare; fără number, îl dă FacturOne AI
'client' => ['cui' => 'RO12345674'],
'lines' => [['name' => 'Abonament noiembrie 2026', 'quantity' => 1, 'unit_price' => 199, 'vat_rate' => 21]],
], 'comanda-1042');
echo "Emisă: {$invoice['document_number']} ({$invoice['id']})\n";
foreach ($invoice['warnings'] as $warning) {
echo "Avertisment: {$warning['code']}: {$warning['message']}\n";
}
$read = facturone('GET', "/invoices/{$invoice['id']}");
echo "Stare: {$read['status']}, e-Factura: {$read['efactura']['status']}\n";
file_put_contents('factura.pdf', facturone('GET', "/invoices/{$invoice['id']}/pdf", null, null, true));
echo "PDF: factura.pdf\n";
$email = facturone('POST', "/invoices/{$invoice['id']}/email", ['to' => ['[email protected]']]);
echo "Email: {$email['status']}\n";
$storno = facturone('POST', "/invoices/{$invoice['id']}/storno", null, 'comanda-1042-storno');
echo "Stornare: {$storno['document_number']}\n";// Node.js 18+ (fetch inclus). Rulează ca modul: node factura.mjs
import { writeFile } from "node:fs/promises";
const API = process.env.FACTURONE_API_URL ?? "https://api.facturone.com/v1";
const KEY = process.env.FACTURONE_API_KEY;
async function facturone(method, path, { body, idempotencyKey } = {}) {
const headers = { Authorization: `Bearer ${KEY}` };
if (body) headers["Content-Type"] = "application/json";
if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
const res = await fetch(API + path, { method, headers, body: body ? JSON.stringify(body) : undefined });
if (!res.ok) {
const { error } = await res.json().catch(() => ({ error: {} }));
throw new Error(`${res.status} ${error.code}: ${error.message} (request_id ${error.request_id})`);
}
return res;
}
const invoice = await (await facturone("POST", "/invoices", {
idempotencyKey: "comanda-1042", // aceeași cheie la reîncercare: nu se emite a doua factură
body: {
series: "API", // una din seriile bifate în API FacturOne → Facturare; number lipsă: îl dă FacturOne AI
client: { cui: "RO12345674" },
lines: [{ name: "Abonament noiembrie 2026", quantity: 1, unit_price: 199, vat_rate: 21 }],
},
})).json();
console.log(`Emisă: ${invoice.document_number} (${invoice.id})`);
for (const warning of invoice.warnings) console.log(`Avertisment: ${warning.code}: ${warning.message}`);
const read = await (await facturone("GET", `/invoices/${invoice.id}`)).json();
console.log(`Stare: ${read.status}, e-Factura: ${read.efactura.status}`);
const pdf = Buffer.from(await (await facturone("GET", `/invoices/${invoice.id}/pdf`)).arrayBuffer());
await writeFile("factura.pdf", pdf);
console.log("PDF: factura.pdf");
const email = await (await facturone("POST", `/invoices/${invoice.id}/email`, {
body: { to: ["[email protected]"] },
})).json();
console.log(`Email: ${email.status}`);
const storno = await (await facturone("POST", `/invoices/${invoice.id}/storno`, {
idempotencyKey: "comanda-1042-storno",
})).json();
console.log(`Stornare: ${storno.document_number}`);# Python 3.9+, doar biblioteca standard.
import json
import os
import urllib.error
import urllib.request
API = os.environ.get("FACTURONE_API_URL", "https://api.facturone.com/v1")
KEY = os.environ["FACTURONE_API_KEY"]
def facturone(method, path, body=None, idempotency_key=None, raw=False):
headers = {"Authorization": f"Bearer {KEY}", "User-Agent": "aplicatia-mea/1.0"}
data = None
if body is not None:
headers["Content-Type"] = "application/json"
data = json.dumps(body).encode()
if idempotency_key:
headers["Idempotency-Key"] = idempotency_key
request = urllib.request.Request(API + path, data=data, headers=headers, method=method)
try:
with urllib.request.urlopen(request, timeout=60) as response:
content = response.read()
except urllib.error.HTTPError as exc:
error = json.loads(exc.read() or b"{}").get("error", {})
raise RuntimeError(f"{exc.code} {error.get('code')}: {error.get('message')} (request_id {error.get('request_id')})")
return content if raw else json.loads(content)
# Aceeași Idempotency-Key la reîncercare: nu se emite a doua factură.
invoice = facturone("POST", "/invoices", {
"series": "API", # una din seriile bifate în API FacturOne → Facturare; fără number, îl dă FacturOne AI
"client": {"cui": "RO12345674"},
"lines": [{"name": "Abonament noiembrie 2026", "quantity": 1, "unit_price": 199, "vat_rate": 21}],
}, idempotency_key="comanda-1042")
print(f"Emisă: {invoice['document_number']} ({invoice['id']})")
for warning in invoice["warnings"]:
print(f"Avertisment: {warning['code']}: {warning['message']}")
read = facturone("GET", f"/invoices/{invoice['id']}")
print(f"Stare: {read['status']}, e-Factura: {read['efactura']['status']}")
with open("factura.pdf", "wb") as file:
file.write(facturone("GET", f"/invoices/{invoice['id']}/pdf", raw=True))
print("PDF: factura.pdf")
email = facturone("POST", f"/invoices/{invoice['id']}/email", {"to": ["[email protected]"]})
print(f"Email: {email['status']}")
storno = facturone("POST", f"/invoices/{invoice['id']}/storno", idempotency_key="comanda-1042-storno")
print(f"Stornare: {storno['document_number']}")Ghid: facturi lunare automate
Pentru un site care emite pe 1 ale lunii facturi către firme, pentru abonamente.
1. Seria și cheia de test
În FacturOne: API FacturOne → Facturare → Serii pentru API, bifează seria pe care emiți (sau creează seria
„API”). Seria e necesară și în test. Apoi API FacturOne → Chei API → Cheie nouă, mod Test, drepturi „Citire” și
„Emitere facturi” (și „Trimitere pe e-mail”, dacă vrei să trimitem noi facturile clienților tăi). Copiaz-o în
variabila de mediu FACTURONE_API_KEY de pe serverul tău. Verifică: GET /v1/me trebuie să răspundă
cu "mode": "test".
2. Prima factură de test
Trimite o factură pentru un client real, după CUI. Folosește ca Idempotency-Key ceva ce
identifică factura în sistemul tău: id-ul abonamentului + luna (abonament-1042-2026-12).
Verifică: PDF-ul (/pdf), starea e-Factura (/efactura → accepted) și pagina
„Facturi de test” din aplicație. Dacă validarea spune rejected, corectează datele după
mesajele din errors.
curl -X POST https://api.facturone.com/v1/invoices \
-H "Authorization: Bearer $FACTURONE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: abonament-1042-2026-12" \
-d '{"series": "API", "client": {"cui": "RO12345674"}, "lines": [{"name": "Abonament noiembrie 2026", "quantity": 1, "unit": "buc", "unit_price": 199.0, "vat_rate": 21}], "notes": "Plata în 14 zile.", "send_to_efactura": true}'3. Webhook-urile
Adaugă o adresă HTTPS a aplicației tale în API FacturOne → Webhook-uri, cu evenimentele
invoice.created, efactura.rejected și invoice.paid. Salvează secretul în
FACTURONE_WEBHOOK_SECRET și verifică semnătura ca în exemplele de mai sus. Apasă „Trimite un test” și
urmărește jurnalul de livrări. Așa afli fără să întrebi periodic când ANAF respinge o factură și când clientul a
plătit. Dacă adaugi monthly_limit.warning, afli din timp când te apropii de limita lunară.
4. Rularea lunară
- Pentru fiecare abonament activ: o cerere
POST /v1/invoicescu"series": "API"și cheia de idempotențăabonament-<id>-<AAAA-LL>. Fărănumber: numerele le dăm noi, la rând. Cererile pot fi trimise una după alta; pe aceeași serie se emit oricum pe rând. - La 429 cu
rate_limited, 503 sau eroare de rețea aștepțiRetry-Afterși reîncerci cu aceeași cheie de idempotență. Nu se creează dubluri. - La 429 cu
monthly_limit_reachedte oprești: facturile rămase așteaptă luna următoare sau mărirea limitei. AntetulX-Monthly-Usedîți arată din timp cât ai folosit. - La 4xx (în afară de 429) nu reîncerci: corectezi datele (
error.fieldarată ce). - Salvează
idșidocument_numberlângă abonament. Pentru PDF în contul clientului:/pdf-linkcuexpires_inpotrivit, sauPOST /v1/invoices/{id}/email. - Dacă un abonament se anulează după facturare:
POST /v1/invoices/{id}/storno.
# Pe 1 ale lunii, la 06:00 (ora serverului tău)
0 6 1 * * /usr/bin/php /var/www/site/scripts/facturi-lunare.php >> /var/log/facturi-lunare.log 2>&15. Trecerea la cheia live
- Planul firmei trebuie să fie Pro sau Max.
- Seria bifată în API FacturOne → Facturare → Serii pentru API e aceeași pentru test și live: pe live facturile primesc numerele reale ale seriei.
GET /v1/mecu cheia live aratălive_invoices_enabled. Cât efalse, crearea pe live întoarce 403live_invoices_disabledși rămâi pe cheia de test.- Creează o cheie Live și înlocuiește variabila de mediu. Nu schimbi nimic în cod: aceleași rute, aceleași
răspunsuri, cu
"mode": "live", iar webhook-urile vin cu"livemode": true. - Revocă cheia de test când nu mai ai nevoie de ea.
Ghid: Shopify fără aplicație
Un magazin Shopify poate emite factura când comanda e plătită, fără nicio aplicație instalată: Shopify Flow
trimite comanda la POST /v1/invoices.
Ce verifici întâi în contul Shopify
Planul Shopify. Merge pe Grow, Advanced și Plus. Pe Basic acțiunea „Send HTTP request” lipsește (Shopify Flow e gratuit pe toate planurile, dar acțiunea doar pe acestea trei). Pe Basic folosește un instrument fără cod, cu declanșatorul de comandă plătită din Shopify: vezi ghidul Zapier, Make, n8n. Webhook-urile din Shopify (Setări → Notificări → Webhook-uri) există pe orice plan, dar trimit un corp fix și nu pot adăuga cheia API, deci nu pot chema direct FacturOne.
- Verifică: deschide Flow, creează un workflow și caută acțiunea „Send HTTP request”. Dacă nu apare, planul tău nu o are.
- Permisiunea „Manage connections and secrets” pentru cine configurează workflow-ul: cheia API stă într-un secret Flow, nu în textul workflow-ului.
- Prețurile: dacă în Shopify prețurile includ TVA, exemplul de mai jos le împarte la 1,21. Dacă vinzi și cu
11%, fă un workflow separat sau schimbă
vat_ratepentru acele produse. - Clienții firme: Shopify nu cere CUI la checkout. Dacă îl ceri tu (de ex. un câmp „CUI” în checkout),
trimite
"client": {"cui": "…"}în loc de datele persoanei fizice. - Seria: bifează în FacturOne seria pe care emiți (de ex. „API”) și trimite-o în
series. Numărul îl dăm noi, deci nu trimitenumber.
Pașii
- În FacturOne: API FacturOne → Chei API → Cheie nouă, întâi una de test (
fo_test_…). - În Shopify: Flow → Settings → Secrets, un secret cu numele
facturone_api_keyși cheia ca valoare. - Workflow nou cu declanșatorul „Order paid” și acțiunea „Send HTTP request”: metoda
POST, adresahttps://api.facturone.com/v1/invoices, antetele și corpul de mai jos. - La „On client error (4XX response)” alege „Fail” (vezi greșeala în „Recent runs” și o corectezi); la
„On server error (5XX or 429 response)” alege „Retry”. Flow reîncearcă până la 24 de ore, cu aceeași
Idempotency-Key, deci nu apar facturi duble. - Plasează o comandă de test, apoi verifică factura în API FacturOne → Facturare → Facturi de test. Când totul e bine, înlocuiește secretul cu o cheie live.
Antete:
Corp (Liquid, așa cum îl scrii în Flow):
Dacă magazinul vinde în mai multe țări sau și prin FBE, alege seria după țara comenzii, cu o
condiție Liquid în corp, de exemplu:
"series": "{% if order.shippingAddress.countryCodeV2 == 'HU' %}EMG-HU{% else %}EMG-RO{% endif %}",.
Bifează în FacturOne toate seriile pe care le poate alege condiția.
- Un răspuns 201 sau 202 înseamnă că am primit factura. Cu 202 (
pending_confirmation) o confirmăm în câteva minute; afli rezultatul prin webhook-ulinvoice.createdsauinvoice.failed. - Flow așteaptă cel mult 30 de secunde un răspuns, apoi reîncearcă; aceeași cheie întoarce aceeași factură.
- Pentru stornare la anularea comenzii ai nevoie de
id-ul facturii: salvează-l pe comandă (de ex. într-un metafield, cu „Run code” și „Update order metafield”), apoi trimitePOST /v1/invoices/{id}/stornodintr-un al doilea workflow.
Authorization: Bearer {{secrets.facturone_api_key}}
Content-Type: application/json
Idempotency-Key: shopify-{{order.id}}{
"series": "API",
"client": {
"type": "individual",
"name": {{ order.billingAddress.name | json }},
"address": {{ order.billingAddress.address1 | json }},
"city": {{ order.billingAddress.city | json }},
"county": {{ order.billingAddress.province | json }},
"country": "{{ order.billingAddress.countryCodeV2 }}",
"email": {{ order.email | json }}
},
"lines": [
{% for lineItems_item in order.lineItems %}
{
"name": {{ lineItems_item.title | json }},
"quantity": {{ lineItems_item.quantity }},
"unit_price": {{ lineItems_item.discountedUnitPriceAfterAllDiscountsSet.shopMoney.amount | divided_by: 1.21 | round: 2 }},
"vat_rate": 21
}{% unless forloop.last %},{% endunless %}
{% endfor %}
{% if order.shippingLine %}
,{
"name": "Transport",
"quantity": 1,
"unit_price": {{ order.shippingLine.discountedPriceSet.shopMoney.amount | divided_by: 1.21 | round: 2 }},
"vat_rate": 21
}
{% endif %}
],
"currency": "{{ order.currencyCode }}",
"notes": "Comanda Shopify {{ order.name }}"
}Ghid: WooCommerce (WordPress)
Un magazin WooCommerce emite factura la plată și o stornează la anulare cu un fragment PHP, fără plugin. Fragmentul de mai jos îl rulăm automat, la fiecare versiune, pe un server de test.
Ce verifici întâi
- Acces la fișierele temei (o temă copil) sau un plugin de fragmente, de exemplu Code Snippets. Nu pune fragmentul în tema principală: se pierde la actualizare.
- Prețurile: fragmentul ia din comandă prețul fără TVA și TVA-ul calculat de WooCommerce, pe fiecare rând, și alege cota cea mai apropiată (21, 11 sau 0). Verifică în WooCommerce → Setări → Taxe că ai cotele corecte.
- Clienții firme: WooCommerce nu are câmp de CUI. Dacă îl ceri la checkout (un câmp suplimentar sau un plugin
românesc), pune numele câmpului în
FACTURONE_CUI_META. Fără CUI, clientul e persoană fizică. - Seriile: bifează în FacturOne toate seriile din
FACTURONE_SERIES(API FacturOne → Facturare → Serii pentru API). Fragmentul alege seria după țara de facturare. - Webhook-urile din WooCommerce (Setări → Avansat → Webhook-uri) trimit comanda cu un corp fix, fără cheia API în antet, deci nu pot chema direct FacturOne. Fragmentul face asta.
Pașii
- În FacturOne: o cheie de test (
fo_test_…), cu drepturile „Citire” și „Emitere facturi”. - În
wp-config.php, deasupra liniei „That's all, stop editing!”:define('FACTURONE_API_KEY', 'fo_test_…');. Cheia nu stă în baza de date și nu apare în panou. - Copiază fragmentul în
functions.phpal temei copil sau într-un fragment nou din Code Snippets. Schimbă seriile și câmpul de CUI dacă e nevoie. - Plasează o comandă de test și plătește-o (sau marcheaz-o „Finalizată”). În comandă apare nota „Factura FacturOne TEST API 1.”, iar factura e în API FacturOne → Facturare → Facturi de test.
- Anulează comanda: apare nota „Stornare FacturOne …”.
- Când totul e bine, pune în
wp-config.phpcheia live.
Idempotency-Keyewoo-<id comandă>(șiwoo-<id>-storno). O comandă plătită care trece și prin „Finalizată” primește tot o singură factură.- Erori: 5xx, 429 și lipsa răspunsului se reîncearcă după 5 minute (WP-Cron), cu aceeași cheie, deci fără dubluri.
La 429
monthly_limit_reachednu reîncearcă. Alt 4xx lasă o notă pe comandă cu codul și mesajul; corectezi datele și pornești din nou acțiunea (de ex. schimbi starea comenzii). - Dacă nota spune
invoice_failed, factura nu s-a creat: șterge câmpul_facturone_invoice_idal comenzii, dacă există, și retrimite cu o cheie nouă (schimbă prefixulwoo-pentru acea comandă). - WP-Cron rulează la vizitele pe site. Pe un magazin cu puține vizite, pornește un cron real al serverului.
<?php
// FacturOne pentru WooCommerce: factura la plată, stornarea la anulare sau rambursare.
// Pune fragmentul în functions.php al temei copil sau într-un plugin de fragmente (ex. Code Snippets).
// Cheia stă în wp-config.php, nu aici: define('FACTURONE_API_KEY', 'fo_test_…');
if (!defined('FACTURONE_API_URL')) {
define('FACTURONE_API_URL', 'https://api.facturone.com/v1');
}
// Seria după țara de facturare; celelalte țări merg pe FACTURONE_DEFAULT_SERIES.
// Toate seriile de aici trebuie bifate în FacturOne: API FacturOne → Facturare → Serii pentru API.
const FACTURONE_SERIES = ['RO' => 'API', 'HU' => 'API-HU', 'BG' => 'API-BG'];
const FACTURONE_DEFAULT_SERIES = 'API';
// Câmpul comenzii în care ții CUI-ul firmei (gol: client persoană fizică).
const FACTURONE_CUI_META = '_billing_cui';
// Plată online confirmată; la ramburs sau transfer bancar, când marchezi comanda „Finalizată”.
add_action('woocommerce_payment_complete', 'facturone_issue_invoice');
add_action('woocommerce_order_status_completed', 'facturone_issue_invoice');
add_action('woocommerce_order_status_cancelled', 'facturone_storno');
add_action('woocommerce_order_status_refunded', 'facturone_storno');
add_action('facturone_retry', 'facturone_retry', 10, 2);
function facturone_vat_rate(float $net, float $tax): int
{
if ($net <= 0 || $tax <= 0) {
return 0;
}
$percent = $tax / $net * 100;
$best = 0;
foreach ([21, 11, 0] as $rate) {
if (abs($percent - $rate) < abs($percent - $best)) {
$best = $rate;
}
}
return $best;
}
function facturone_invoice_body(WC_Order $order): array
{
$lines = [];
foreach ($order->get_items() as $item) {
$quantity = (float) $item->get_quantity();
$net = (float) $item->get_total(); // fără TVA, după reduceri
$lines[] = [
'name' => $item->get_name(),
'quantity' => $quantity,
'unit_price' => round($net / $quantity, 2),
'vat_rate' => facturone_vat_rate($net, (float) $item->get_total_tax()),
];
}
$shipping = (float) $order->get_shipping_total();
if ($shipping > 0) {
$lines[] = [
'name' => 'Transport',
'quantity' => 1,
'unit_price' => round($shipping, 2),
'vat_rate' => facturone_vat_rate($shipping, (float) $order->get_shipping_tax()),
];
}
$country = $order->get_billing_country() ?: 'RO';
$cui = trim((string) $order->get_meta(FACTURONE_CUI_META));
if ($cui !== '') {
$client = ['cui' => $cui, 'email' => $order->get_billing_email()];
} else {
$client = [
'type' => 'individual',
'name' => trim($order->get_billing_first_name() . ' ' . $order->get_billing_last_name()),
'address' => $order->get_billing_address_1(),
'city' => $order->get_billing_city(),
'county' => $order->get_billing_state(),
'country' => $country,
'email' => $order->get_billing_email(),
];
}
return [
'series' => FACTURONE_SERIES[$country] ?? FACTURONE_DEFAULT_SERIES,
'client' => $client,
'lines' => $lines,
'currency' => $order->get_currency(),
'notes' => 'Comanda ' . $order->get_order_number(),
];
}
// POST la FacturOne. 2xx: salvează factura. 5xx, 429, fără răspuns: reîncearcă mai târziu, cu aceeași
// Idempotency-Key (nu apar dubluri). Alt 4xx: o notă pe comandă; corectezi datele și o retrimiți.
function facturone_send(WC_Order $order, string $path, array $body, string $key, string $kind): void
{
$response = wp_remote_post(FACTURONE_API_URL . $path, [
'timeout' => 30,
'headers' => [
'Authorization' => 'Bearer ' . FACTURONE_API_KEY,
'Content-Type' => 'application/json',
'Idempotency-Key' => $key,
],
'body' => wp_json_encode($body),
]);
$status = is_wp_error($response) ? 0 : (int) wp_remote_retrieve_response_code($response);
$data = is_wp_error($response) ? [] : (json_decode(wp_remote_retrieve_body($response), true) ?: []);
if ($status >= 200 && $status < 300) {
$order->update_meta_data($kind === 'storno' ? '_facturone_storno_id' : '_facturone_invoice_id', $data['id']);
$order->save();
$what = $kind === 'storno' ? 'Stornare FacturOne' : 'Factura FacturOne';
$order->add_order_note($status === 202 ? "$what în confirmare ({$data['id']})." : "$what {$data['document_number']}.");
foreach ($data['warnings'] ?? [] as $warning) {
$order->add_order_note('FacturOne: ' . $warning['message']);
}
return;
}
$error = $data['error'] ?? ['code' => 'network', 'message' => 'FacturOne nu a răspuns.'];
// 409 cu Retry-After: încă în lucru, factura în confirmare sau numărul luat chiar atunci de mână.
$wait = ['idempotency_key_in_progress', 'invoice_pending_confirmation', 'number_taken'];
$retry = $status === 0 || $status >= 500 || ($status === 429 && $error['code'] !== 'monthly_limit_reached')
|| ($status === 409 && in_array($error['code'], $wait, true));
$order->add_order_note("FacturOne: {$error['code']}: {$error['message']}" . ($retry ? ' Reîncerc mai târziu.' : ''));
if ($retry) {
wp_schedule_single_event(time() + 300, 'facturone_retry', [$order->get_id(), $kind]);
}
}
function facturone_issue_invoice($order_id): void
{
$order = wc_get_order($order_id);
if (!$order || $order->get_meta('_facturone_invoice_id')) {
return;
}
facturone_send($order, '/invoices', facturone_invoice_body($order), 'woo-' . $order->get_id(), 'invoice');
}
function facturone_storno($order_id): void
{
$order = wc_get_order($order_id);
$invoice = $order ? $order->get_meta('_facturone_invoice_id') : '';
if (!$invoice || $order->get_meta('_facturone_storno_id')) {
return;
}
$path = '/invoices/' . rawurlencode($invoice) . '/storno';
facturone_send($order, $path, ['notes' => 'Comanda ' . $order->get_order_number() . ' anulată'], 'woo-' . $order->get_id() . '-storno', 'storno');
}
function facturone_retry($order_id, $kind): void
{
$kind === 'storno' ? facturone_storno($order_id) : facturone_issue_invoice($order_id);
}Ghid: Zapier, Make, n8n (și Stripe)
Orice platformă care are un declanșator „comandă plătită” sau „plată reușită” în Zapier, Make sau n8n poate emite
factura fără cod: Shopify (și pe Basic), WooCommerce, Stripe, PayPal, formulare, tabele. Instrumentul primește
evenimentul și cheamă POST /v1/invoices.
Ce verifici întâi
- Zapier: acțiunea „Webhooks by Zapier” e disponibilă doar pe planurile plătite (Professional și peste).
- Make: modulul HTTP „Make a request”. n8n: nodul „HTTP Request”. Verifică limitele de operații ale planului tău.
- Seria din
seriese bifată în API FacturOne → Facturare → Serii pentru API.
Pașii (la fel în toate trei)
- Declanșatorul: comanda plătită din platforma ta. Numele diferă de la un instrument la altul; la Stripe alege
evenimentul
checkout.session.completed(plată la checkout) sauinvoice.paid(abonamente). - Acțiunea HTTP: metoda
POST, adresahttps://api.facturone.com/v1/invoices, corpul JSON de mai jos. - Antetele:
Authorization: Bearer <cheia>,Content-Type: application/jsonșiIdempotency-Key= id-ul comenzii din declanșator (de ex.shopify-<id comandă>). Unde instrumentul are credențiale salvate (n8n, Make), pune cheia acolo, nu în textul fluxului. - Testează cu o cheie
fo_test_…, verifică factura în API FacturOne → Facturare → Facturi de test, apoi pune cheia live.
- Prețurile din câmpurile
unit_pricesunt fără TVA. Dacă platforma îți dă prețuri cu TVA, împarte-le la 1,21 (sau la 1,11) în pasul de formatare al instrumentului. - Erori: la 4xx opriți rularea și vezi mesajul în istoricul rulărilor; nu reîncerca până nu corectezi datele.
La 5xx, 429 sau timeout, reîncearcă după
Retry-After, cu aceeașiIdempotency-Key. - Stornarea: un al doilea flux, cu declanșatorul „comandă anulată” sau „rambursare”, care cheamă
POST /v1/invoices/{id}/storno. Id-ul facturii îl iei din răspunsul primului flux (salvează-l într-un tabel sau în comanda din platformă), cuIdempotency-Key= id-ul comenzii + „-storno”. - Stripe: webhook-urile Stripe semnează mesajul cu
Stripe-Signatureși trimit un corp fix, fără cheia API, deci nu pot chema direct FacturOne. Folosește declanșatorul Stripe din Zapier, Make sau n8n. CUI-ul clientului îl iei dintr-un câmp personalizat al Checkout (custom_fields) sau din datele fiscale ale clientului Stripe.
{
"series": "API",
"client": {
"type": "individual",
"name": "<numele clientului>",
"address": "<adresa>",
"city": "<localitatea>",
"county": "<județul>",
"country": "<codul țării, ex. RO>",
"email": "<e-mailul>"
},
"lines": [
{"name": "<produsul>", "quantity": 1, "unit_price": 100.00, "vat_rate": 21}
],
"currency": "RON",
"notes": "Comanda <numărul comenzii>"
}Postman și Bruno
Colecția Postman (format 2.1, o importă și Bruno și Insomnia) e generată din contractul OpenAPI. După import,
completează variabilele colecției base_url (ex. https://api.facturone.com) și api_key
(o cheie de test). Ți-o trimitem la cerere; contractul complet e la
https://api.facturone.com/v1/openapi.json, iar Postman și Bruno îl importă și direct.
Versiuni
Calea /v1 rămâne compatibilă: pot apărea câmpuri, evenimente și rute noi, opționale. O schimbare care
strică ar veni în /v2, cu cel puțin 6 luni în care /v1 merge în continuare. Contractul
complet: https://api.facturone.com/v1/openapi.json.