API FacturOneDocumentație v1

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
curl https://api.facturone.com/v1/me -H "Authorization: Bearer $FACTURONE_API_KEY"
JSON
{
  "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: 422 series_required. O serie nebifată: 422 series_not_allowed, cu seriile bifate în mesaj. O serie închisă sau ștearsă în FacturOne: 409 series_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ă number primește tot cel mai mare număr + 1;
    • sub primul număr al seriei din FacturOne: 422 number_invalid.
  • 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-Key folosește același număr. Aceeași cheie cu alt number întoarce 409 idempotency_conflict.
  • Răspunsul are numărul în number și numărul complet în document_number (EMG-HU-FBE 143).

Răspuns 201 (pe scurt):

cURL
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}]}'
JSON
{
  "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_busy cu Retry-After. Reîncerci cu aceeași Idempotency-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) și Retry-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 și document_number goale; PDF-ul, e-mailul și stornarea întorc 409 invoice_pending_confirmation pâ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și Idempotency-Key. Cererea nu se mai trimite a doua oară;
  • dacă o găsim în FacturOne, devine issued, cu număr, și primești invoice.created;
  • dacă după 15 minute tot nu există, devine failed: nu se numără în limita lunară și primești invoice.failed. Aceeași cheie întoarce de acum 409 invoice_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âmpTipObligatoriuCe înseamnă
client.typetextnucompany (implicit cu CUI) sau individual (persoană fizică)
client.cuitextda, la firmeCUI cu sau fără RO. Restul datelor firmei se completează din baza FacturOne AI.
client.nametextla persoane fiziceDenumirea / numele. La firme, doar dacă vrei să înlocuiești ce știm.
client.address, client.city, client.countytextla persoane fizice și la firme necunoscuteAdresa, localitatea, județul (nume sau cod: Cluj / CJ). În București: sectorul.
client.countrytextnuCod de două litere; implicit RO.
client.email, client.phonetextnuContact.
lines[]listăda (1–100)Rândurile facturii.
lines[].nametextdaDenumirea produsului sau serviciului.
lines[].quantitynumărdaMai mare decât 0, maximum 3 zecimale.
lines[].unittextnuUnitatea de măsură; implicit buc.
lines[].unit_pricenumărdaPreț unitar fără TVA, maximum 2 zecimale.
lines[].vat_ratenumărda21, 11 sau 0. Firmă neplătitoare de TVA: 0.
seriestextdaUna din seriile bifate pentru API (vezi „Serii și numere”). Aceleași reguli în test și pe live.
numbernumăr întregnuNumă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_dateAAAA-LL-ZZnuImplicit azi. Cel mult câteva zile în urmă și doar dacă seria rămâne cronologică.
due_dateAAAA-LL-ZZnuImplicit data facturii + 15 zile.
currencytextnuRON implicit; altă monedă cu cursul BNR al datei facturii.
notestextnuObservații pe factură (maximum 1000 de caractere).
send_to_efacturada / nunuImplicit setarea e-Factura automată a firmei. Cu false, factura nu pleacă la ANAF nici prin trimiterea automată.

Corp:

Cerere:

Răspuns 201:

JSON
{
  "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
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}'
JSON
{
  "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
curl "https://api.facturone.com/v1/invoices?date_from=2026-12-01&efactura_status=rejected&limit=50" \
  -H "Authorization: Bearer $FACTURONE_API_KEY"
JSON
{
  "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
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
curl https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/pdf \
  -H "Authorization: Bearer $FACTURONE_API_KEY" -o factura.pdf

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
curl "https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/pdf-link?expires_in=86400" \
  -H "Authorization: Bearer $FACTURONE_API_KEY"
JSON
{
  "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
curl https://api.facturone.com/v1/invoices/inv_3f9c1d2e7a8b4c5d6e7f8a9b/efactura \
  -H "Authorization: Bearer $FACTURONE_API_KEY"
JSON
{
  "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âne queued: FacturOne nu ne confirmă încă livrarea, așa că nu putem spune dacă a ajuns în căsuța clientului. Tot queued rămâne și când FacturOne nu a răspuns la trimitere (502 email_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 și message sunt 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-Key e 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
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!"}'
JSON
{
  "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-Key e obligatoriu. O factură se stornează o singură dată: a doua încercare, cu altă cheie, întoarce 409 already_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 series alegi altă serie bifată pentru API; cu number, numărul. Aceleași reguli ca la emitere: 409 number_taken la un număr folosit, warnings la un gol sau la un număr sub ultimul. Dacă seria facturii stornate nu mai e bifată, primești 422 series_not_allowed: o bifezi din nou sau trimiți altă serie în series.
  • 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 lines primește 422 partial_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
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.

EvenimentCând
invoice.createdS-a emis o factură (și o stornare: are kind = storno).
efactura.acceptedANAF a acceptat factura.
efactura.rejectedANAF a respins factura sau validarea dinaintea trimiterii a găsit erori; motivele în efactura.errors.
invoice.paidFactura apare încasată integral în FacturOne (încasări marcate în program).
invoice.cancelledFactura a fost stornată; cancelled_by arată stornarea.
invoice.failedFacturare nu a creat factura rămasă neconfirmată (status failed); nu se numără în limită.
monthly_limit.warningAi ajuns la 80% sau la 100% din facturile incluse în lună.

Exemplu:

JSON
{
  "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"
    }
  }
}
JSON
{
  "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…: v1 e 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și t), 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: verificarea
<?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;
}
PHP: folosirea
$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);

Livrare ș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 cu GET /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).

CodHTTPCe înseamnăCe faci
bad_request400Cererea nu poate fi citită.Verifică metoda, antetele și corpul cererii.
invalid_json400Corpul cererii nu este JSON valid.Trimite JSON valid, cu Content-Type: application/json.
idempotency_key_required400Lipsește antetul Idempotency-Key.Trimite un identificator unic al operației (ex. comanda-1042), același la fiecare reîncercare.
idempotency_key_invalid400Idempotency-Key are alt format decât 1–128 caractere ASCII vizibile.Folosește doar litere, cifre și semne, fără spații.
invalid_cursor400Cursorul de paginare nu este valid.Folosește next_cursor din răspunsul anterior.
missing_api_key401Lipsește cheia API.Trimite antetul Authorization: Bearer <cheie API>.
invalid_api_key401Cheia nu există sau e scrisă greșit.Verifică cheia; dacă ai pierdut-o, creează alta în API FacturOne → Chei API.
api_key_revoked401Cheia a fost revocată.Folosește o cheie activă.
forbidden403Acces interzis.Verifică cheia și drepturile ei.
api_disabled403API-ul nu este pornit pentru firmă.Activează aplicația API FacturOne din App Store sau scrie-ne.
plan_not_allowed403Planul firmei nu include API-ul sau cheile live.Folosește o cheie de test sau schimbă planul.
insufficient_scope403Cheia nu are dreptul cerut (ex. email:send).Creează o cheie cu dreptul necesar în API FacturOne → Chei API.
live_invoices_disabled403Facturile reale prin API nu sunt încă pornite pentru firmă.Lucrează cu o cheie de test până la pornire.
email_disabled403Trimiterea pe e-mail prin API e oprită în acest mod.Scrie-ne dacă ai nevoie de ea.
not_found404Ruta sau fișierul nu există.Verifică adresa.
invoice_not_found404Factura nu există pentru cheia folosită (alt id, altă firmă sau celălalt mod, test / live).Verifică id-ul și cheia.
method_not_allowed405Metoda nu este permisă pe această rută.Verifică metoda (GET, POST …).
idempotency_conflict409Idempotency-Key a fost folosită deja pentru alt conținut.Folosește o cheie nouă pentru o operație nouă.
idempotency_key_in_progress409O cerere cu aceeași Idempotency-Key încă rulează.Reîncearcă după Retry-After.
already_cancelled409Factura e deja stornată.Nu mai e nimic de făcut; cancelled_by arată stornarea.
storno_in_progress409O altă stornare a acestei facturi nu s-a terminat.Reîncearcă stornarea cu aceeași Idempotency-Key.
number_taken409Numă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_closed409Seria 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_confirmation409FacturOne nu a confirmat încă factura (status pending_confirmation).Reîncearcă după Retry-After sau așteaptă invoice.created.
invoice_failed409Factura acestei Idempotency-Key nu s-a creat în FacturOne și nu se numără.Trimite factura din nou, cu o Idempotency-Key nouă.
payload_too_large413Corpul cererii depășește 256 KB.Trimite mai puține rânduri pe factură.
unsupported_media_type415Corpul nu este trimis ca JSON.Trimite Content-Type: application/json.
validation_error422Un câmp lipsește sau are alt format.Corectează câmpul din field (vezi și details).
client_not_found422Nu găsim firma cu acest CUI.Verifică CUI-ul sau trimite denumirea, adresa, localitatea și județul clientului.
client_incomplete422Clientului îi lipsesc date cerute de e-Factura (adresă, localitate, județ).Completează câmpul din field.
email_invalid422Adresa de e-mail nu este validă.Corectează adresa din field.
series_required422Lipsește series: fiecare factură spune pe ce serie se emite.Trimite una din seriile bifate în API FacturOne → Facturare → Serii pentru API.
series_invalid422Seria 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_allowed422Seria 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_invalid422Numă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_future422Data e în viitor.Trimite data de azi sau una din trecut.
date_too_old422Data e mai veche decât permite FacturOne.Folosește o dată mai apropiată.
date_not_chronological422Pe serie există deja o factură cu dată mai nouă.Folosește data ultimei facturi din serie sau una mai nouă.
due_date_before_issue422Scadența e înaintea datei facturii.Trimite o scadență egală sau mai târzie.
storno_date_before_invoice422Data stornării e înaintea datei facturii stornate.Folosește data facturii sau una mai nouă.
vat_rate_invalid422Cota de TVA nu este permisă sau nu există în contul firmei.Folosește una dintre cotele firmei (ex. 21, 11, 0).
vat_not_allowed422Firma nu este plătitoare de TVA, dar factura are TVA.Trimite cota 0 pe rânduri.
currency_not_supported422Moneda nu este un cod ISO de trei litere.Trimite codul monedei (ex. RON, EUR).
exchange_rate_unavailable422Nu există curs BNR pentru moneda și data facturii.Reîncearcă după publicarea cursului sau emite în RON.
facturare_rejected422FacturOne a refuzat factura la propriile verificări.Verifică datele facturii; codul FacturOne e în mesaj.
storno_not_allowed422O factură de stornare nu se mai stornează.Stornează factura inițială.
partial_storno_not_supported422Stornarea parțială nu este disponibilă.Stornează toată factura, apoi emite una nouă cu ce rămâne.
account_email_missing422Contul FacturOne nu are adresă de e-mail pentru e-mailurile de test.Adaugă adresa în contul FacturOne.
rate_limited429Prea multe cereri într-un minut.Așteaptă Retry-After secunde; urmărește X-RateLimit-Remaining.
daily_invoice_limit429Ai atins limita de facturi pe zi.Reîncearcă după Retry-After (miezul nopții, ora României).
monthly_limit_reached429Ai 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_reached429Ai atins limita de e-mailuri pe zi.Reîncearcă după Retry-After (miezul nopții).
internal_error500Eroare neașteptată la noi.Reîncearcă peste câteva minute, cu aceeași Idempotency-Key; dacă persistă, trimite-ne request_id.
email_not_sent502FacturOne 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_unavailable503FacturOne nu răspunde sau nu ne putem conecta.Reîncearcă după Retry-After, cu aceeași Idempotency-Key.
series_busy503Seria e ocupată cu alte facturi ale firmei prin API.Reîncearcă după Retry-After, cu aceeași Idempotency-Key.
busy503Prea multe facturi de test simultan pe aceeași serie.Reîncearcă după Retry-After, cu aceeași Idempotency-Key.
upstream_timeout504FacturOne nu a răspuns la timp.Reîncearcă după Retry-After, cu aceeași Idempotency-Key.
JSON
{
  "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) și X-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), cu Retry-After până la resetare și details (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.
JSON
{
  "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, number opț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.

factura.sh
#!/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")"

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
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/invoices cu "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ți Retry-After și reîncerci cu aceeași cheie de idempotență. Nu se creează dubluri.
  • La 429 cu monthly_limit_reached te oprești: facturile rămase așteaptă luna următoare sau mărirea limitei. Antetul X-Monthly-Used îți arată din timp cât ai folosit.
  • La 4xx (în afară de 429) nu reîncerci: corectezi datele (error.field arată ce).
  • Salvează id și document_number lângă abonament. Pentru PDF în contul clientului: /pdf-link cu expires_in potrivit, sau POST /v1/invoices/{id}/email.
  • Dacă un abonament se anulează după facturare: POST /v1/invoices/{id}/storno.
Text
# 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>&1

5. 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/me cu cheia live arată live_invoices_enabled. Cât e false, crearea pe live întoarce 403 live_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_rate pentru 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 trimite number.

Pașii

  1. În FacturOne: API FacturOne → Chei API → Cheie nouă, întâi una de test (fo_test_…).
  2. În Shopify: Flow → Settings → Secrets, un secret cu numele facturone_api_key și cheia ca valoare.
  3. Workflow nou cu declanșatorul „Order paid” și acțiunea „Send HTTP request”: metoda POST, adresa https://api.facturone.com/v1/invoices, antetele și corpul de mai jos.
  4. 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.
  5. 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-ul invoice.created sau invoice.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 trimite POST /v1/invoices/{id}/storno dintr-un al doilea workflow.
Text
Authorization: Bearer {{secrets.facturone_api_key}}
Content-Type: application/json
Idempotency-Key: shopify-{{order.id}}
JSON
{
  "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

  1. În FacturOne: o cheie de test (fo_test_…), cu drepturile „Citire” și „Emitere facturi”.
  2. Î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.
  3. Copiază fragmentul în functions.php al temei copil sau într-un fragment nou din Code Snippets. Schimbă seriile și câmpul de CUI dacă e nevoie.
  4. 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.
  5. Anulează comanda: apare nota „Stornare FacturOne …”.
  6. Când totul e bine, pune în wp-config.php cheia live.
  • Idempotency-Key e woo-<id comandă> (și woo-<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_reached nu 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_id al comenzii, dacă există, și retrimite cu o cheie nouă (schimbă prefixul woo- pentru acea comandă).
  • WP-Cron rulează la vizitele pe site. Pe un magazin cu puține vizite, pornește un cron real al serverului.
Text
<?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 series e bifată în API FacturOne → Facturare → Serii pentru API.

Pașii (la fel în toate trei)

  1. 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) sau invoice.paid (abonamente).
  2. Acțiunea HTTP: metoda POST, adresa https://api.facturone.com/v1/invoices, corpul JSON de mai jos.
  3. Antetele: Authorization: Bearer <cheia>, Content-Type: application/json și Idempotency-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.
  4. 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_price sunt 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și Idempotency-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ă), cu Idempotency-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.
JSON
{
  "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.