{"openapi":"3.1.0","info":{"title":"FacturOne API","description":"API-ul public FacturOne: facturi emise automat din aplicația ta, cu e-Factura.\n\nAutentificare: `Authorization: Bearer <cheie API>`. Cheile `fo_test_…` lucrează doar cu date de test; cheile `fo_live_…` cu facturile reale.\n\nDocumentație cu exemple: `/v1/docs`.\n\n## Coduri de eroare\n\n| Cod | HTTP | Ce înseamnă | Ce faci |\n|---|---|---|---|\n| `bad_request` | 400 | Cererea nu poate fi citită. | Verifică metoda, antetele și corpul cererii. |\n| `invalid_json` | 400 | Corpul cererii nu este JSON valid. | Trimite JSON valid, cu Content-Type: application/json. |\n| `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. |\n| `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. |\n| `invalid_cursor` | 400 | Cursorul de paginare nu este valid. | Folosește next_cursor din răspunsul anterior. |\n| `missing_api_key` | 401 | Lipsește cheia API. | Trimite antetul Authorization: Bearer <cheie API>. |\n| `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. |\n| `api_key_revoked` | 401 | Cheia a fost revocată. | Folosește o cheie activă. |\n| `forbidden` | 403 | Acces interzis. | Verifică cheia și drepturile ei. |\n| `api_disabled` | 403 | API-ul nu este pornit pentru firmă. | Activează aplicația API FacturOne din App Store sau scrie-ne. |\n| `plan_not_allowed` | 403 | Planul firmei nu include API-ul sau cheile live. | Folosește o cheie de test sau schimbă planul. |\n| `insufficient_scope` | 403 | Cheia nu are dreptul cerut (ex. email:send). | Creează o cheie cu dreptul necesar în API FacturOne → Chei API. |\n| `live_invoices_disabled` | 403 | Facturile reale prin API nu sunt încă pornite pentru firmă. | Lucrează cu o cheie de test până la pornire. |\n| `email_disabled` | 403 | Trimiterea pe e-mail prin API e oprită în acest mod. | Scrie-ne dacă ai nevoie de ea. |\n| `not_found` | 404 | Ruta sau fișierul nu există. | Verifică adresa. |\n| `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. |\n| `method_not_allowed` | 405 | Metoda nu este permisă pe această rută. | Verifică metoda (GET, POST …). |\n| `idempotency_conflict` | 409 | Idempotency-Key a fost folosită deja pentru alt conținut. | Folosește o cheie nouă pentru o operație nouă. |\n| `idempotency_key_in_progress` | 409 | O cerere cu aceeași Idempotency-Key încă rulează. | Reîncearcă după Retry-After. |\n| `already_cancelled` | 409 | Factura e deja stornată. | Nu mai e nimic de făcut; cancelled_by arată stornarea. |\n| `storno_in_progress` | 409 | O altă stornare a acestei facturi nu s-a terminat. | Reîncearcă stornarea cu aceeași Idempotency-Key. |\n| `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. |\n| `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. |\n| `invoice_pending_confirmation` | 409 | FacturOne nu a confirmat încă factura (status pending_confirmation). | Reîncearcă după Retry-After sau așteaptă invoice.created. |\n| `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ă. |\n| `link_expired` | 410 | Linkul semnat a expirat. | Cere un link nou cu /pdf-link. |\n| `payload_too_large` | 413 | Corpul cererii depășește 256 KB. | Trimite mai puține rânduri pe factură. |\n| `unsupported_media_type` | 415 | Corpul nu este trimis ca JSON. | Trimite Content-Type: application/json. |\n| `validation_error` | 422 | Un câmp lipsește sau are alt format. | Corectează câmpul din field (vezi și details). |\n| `client_not_found` | 422 | Nu găsim firma cu acest CUI. | Verifică CUI-ul sau trimite denumirea, adresa, localitatea și județul clientului. |\n| `client_incomplete` | 422 | Clientului îi lipsesc date cerute de e-Factura (adresă, localitate, județ). | Completează câmpul din field. |\n| `email_invalid` | 422 | Adresa de e-mail nu este validă. | Corectează adresa din field. |\n| `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. |\n| `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). |\n| `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ă. |\n| `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. |\n| `date_in_future` | 422 | Data e în viitor. | Trimite data de azi sau una din trecut. |\n| `date_too_old` | 422 | Data e mai veche decât permite FacturOne. | Folosește o dată mai apropiată. |\n| `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ă. |\n| `due_date_before_issue` | 422 | Scadența e înaintea datei facturii. | Trimite o scadență egală sau mai târzie. |\n| `storno_date_before_invoice` | 422 | Data stornării e înaintea datei facturii stornate. | Folosește data facturii sau una mai nouă. |\n| `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). |\n| `vat_not_allowed` | 422 | Firma nu este plătitoare de TVA, dar factura are TVA. | Trimite cota 0 pe rânduri. |\n| `currency_not_supported` | 422 | Moneda nu este un cod ISO de trei litere. | Trimite codul monedei (ex. RON, EUR). |\n| `exchange_rate_unavailable` | 422 | Nu există curs BNR pentru moneda și data facturii. | Reîncearcă după publicarea cursului sau emite în RON. |\n| `facturare_rejected` | 422 | FacturOne a refuzat factura la propriile verificări. | Verifică datele facturii; codul FacturOne e în mesaj. |\n| `storno_not_allowed` | 422 | O factură de stornare nu se mai stornează. | Stornează factura inițială. |\n| `partial_storno_not_supported` | 422 | Stornarea parțială nu este disponibilă. | Stornează toată factura, apoi emite una nouă cu ce rămâne. |\n| `account_email_missing` | 422 | Contul FacturOne nu are adresă de e-mail pentru e-mailurile de test. | Adaugă adresa în contul FacturOne. |\n| `rate_limited` | 429 | Prea multe cereri într-un minut. | Așteaptă Retry-After secunde; urmărește X-RateLimit-Remaining. |\n| `daily_invoice_limit` | 429 | Ai atins limita de facturi pe zi. | Reîncearcă după Retry-After (miezul nopții, ora României). |\n| `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. |\n| `email_limit_reached` | 429 | Ai atins limita de e-mailuri pe zi. | Reîncearcă după Retry-After (miezul nopții). |\n| `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. |\n| `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. |\n| `facturare_unavailable` | 503 | FacturOne nu răspunde sau nu ne putem conecta. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |\n| `series_busy` | 503 | Seria e ocupată cu alte facturi ale firmei prin API. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |\n| `busy` | 503 | Prea multe facturi de test simultan pe aceeași serie. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |\n| `upstream_timeout` | 504 | FacturOne nu a răspuns la timp. | Reîncearcă după Retry-After, cu aceeași Idempotency-Key. |","version":"1.0.0"},"paths":{"/v1/me":{"get":{"tags":["Cont"],"summary":"Verifică cheia API","description":"Modul cheii (live / test), drepturile și limitele ei, seriile bifate pentru API. Bun ca prim apel.","operationId":"me_v1_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}}},"security":[{"ApiKey":[]}]}},"/v1/invoices":{"post":{"tags":["Facturi"],"summary":"Emite o factură","description":"Cu o cheie de test, factura rămâne în FacturOne AI (numerotare de test, XML validat la ANAF). Cu o cheie live, factura se creează în Facturare. Antetul `Idempotency-Key` e obligatoriu: aceeași cheie și același conținut întorc aceeași factură (antet `Idempotent-Replayed: true`); aceeași cheie cu alt conținut întoarce 409.","operationId":"create_invoice_v1_invoices_post","security":[{"ApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identificator unic al facturii în sistemul tău (ex. abonament-123-2026-11).","title":"Idempotency-Key"},"description":"Identificator unic al facturii în sistemul tău (ex. abonament-123-2026-11)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Factura emisă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceOut"}}},"headers":{"X-Monthly-Limit":{"description":"Doar live: facturi incluse pe lună.","schema":{"type":"integer"}},"X-Monthly-Used":{"description":"Doar live: facturi reale luna aceasta.","schema":{"type":"integer"}},"X-Monthly-Reset":{"description":"Doar live: când se resetează limita (ora României).","schema":{"type":"string","format":"date-time"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Date invalide; `field` arată câmpul. Seria lipsește (`series_required`), nu e bifată pentru API (`series_not_allowed`) sau numărul e sub primul număr al seriei (`number_invalid`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri (`rate_limited`), facturi pe zi (`daily_invoice_limit`) sau limita lunară (`monthly_limit_reached`, cu `details` și Retry-After până la resetare).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"202":{"description":"Doar live: Facturare nu a confirmat încă factura (`status: pending_confirmation`, fără număr). O verificăm automat; urmează `invoice.created` sau `invoice.failed`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceOut"}}}},"409":{"description":"Idempotency-Key folosită pentru alt conținut (`idempotency_conflict`), numărul trimis e deja folosit (`number_taken`), seria e închisă în FacturOne (`series_closed`) sau factura acestei chei nu s-a creat (`invoice_failed`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Facturare nu a răspuns; reîncearcă cu aceeași cheie.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Seria e ocupată (`series_busy`) sau Facturare nu răspunde.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Facturi"],"summary":"Lista facturilor emise prin API","description":"Cele mai noi primele. Pagina următoare: `starting_after` = `next_cursor` din răspuns.","operationId":"list_invoices_v1_invoices_get","security":[{"ApiKey":[]}],"parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Data facturii, de la (inclusiv).","title":"Date From"},"description":"Data facturii, de la (inclusiv)."},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Data facturii, până la (inclusiv).","title":"Date To"},"description":"Data facturii, până la (inclusiv)."},{"name":"series","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"Numele seriei (ex. EMG-HU-FBE).","title":"Series"},"description":"Numele seriei (ex. EMG-HU-FBE)."},{"name":"client_cui","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"description":"CUI-ul clientului, cu sau fără RO.","title":"Client Cui"},"description":"CUI-ul clientului, cu sau fără RO."},{"name":"efactura_status","in":"query","required":false,"schema":{"anyOf":[{"enum":["not_sent","pending","accepted","rejected"],"type":"string"},{"type":"null"}],"title":"Efactura Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"description":"Cursorul primit în `next_cursor`.","title":"Starting After"},"description":"Cursorul primit în `next_cursor`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invoices/{invoice_id}":{"get":{"tags":["Facturi"],"summary":"O factură","operationId":"get_invoice_v1_invoices__invoice_id__get","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceOut"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invoices/{invoice_id}/pdf":{"get":{"tags":["Facturi"],"summary":"PDF-ul facturii","description":"Facturile de test au „TEST — fără valoare fiscală” pe fiecare pagină.","operationId":"get_invoice_pdf_v1_invoices__invoice_id__pdf_get","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"PDF-ul facturii.","content":{"application/pdf":{}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invoices/{invoice_id}/pdf-link":{"get":{"tags":["Facturi"],"summary":"Link semnat către PDF","description":"Linkul merge fără cheie API până la `expires_at`. `expires_in`: 60 – 604800 secunde.","operationId":"get_invoice_pdf_link_v1_invoices__invoice_id__pdf_link_get","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}},{"name":"expires_in","in":"query","required":false,"schema":{"type":"integer","maximum":604800,"minimum":60,"default":3600,"title":"Expires In"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfLink"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/files/{token}":{"get":{"tags":["Facturi"],"summary":"PDF prin link semnat","description":"Fără cheie API. Linkul expirat întoarce 410.","operationId":"get_signed_file_v1_files__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"PDF-ul facturii.","content":{"application/pdf":{}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Not Found"},"410":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Gone"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/invoices/{invoice_id}/storno":{"post":{"tags":["Facturi"],"summary":"Stornează o factură","description":"Stornare totală: o factură nouă cu aceleași linii și cantități negative, cu „Storno factura seria X nr. Y” în descriere. Implicit pe seria facturii stornate, cu numărul dat de FacturOne AI; opțional `series` (una din seriile bifate pentru API) și `number`, cu aceleași reguli ca la emitere. Merge la e-Factura ca orice factură. Factura stornată primește `cancelled_by`. `Idempotency-Key` e obligatoriu. Stornările se numără împreună cu facturile în facturile incluse pe lună, dar nu sunt oprite niciodată de limită. În test: stornare de test, pe contoarele de test.","operationId":"storno_invoice_v1_invoices__invoice_id__storno_post","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Identificator unic al stornării în sistemul tău.","title":"Idempotency-Key"},"description":"Identificator unic al stornării în sistemul tău."}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/StornoCreate"},{"type":"null"}],"title":"Body"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceOut"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Factura e deja stornată, cheia e folosită altfel sau numărul trimis e folosit (`number_taken`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invoices/{invoice_id}/email":{"post":{"tags":["Facturi"],"summary":"Trimite factura pe e-mail","description":"Live: Facturare trimite e-mailul cu PDF-ul atașat, ca din ecranul facturii; răspunsul e `queued` (Facturare nu confirmă livrarea). Test: e-mailul pleacă doar la adresa contului tău, cu „TEST” în subiect și un link către PDF-ul de test. Cheia are nevoie de dreptul `email:send`. `Idempotency-Key` e opțional: cu el, aceeași cerere nu trimite de două ori.","operationId":"email_invoice_v1_invoices__invoice_id__email_post","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Opțional. Aceeași cheie nu trimite e-mailul de două ori.","title":"Idempotency-Key"},"description":"Opțional. Aceeași cheie nu trimite e-mailul de două ori."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceEmail"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceEmailOut"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Limita de e-mailuri pe zi (`email_limit_reached`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Idempotency-Key folosită pentru alt e-mail.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"502":{"description":"Facturare nu a confirmat trimiterea (`email_not_sent`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/invoices/{invoice_id}/efactura":{"get":{"tags":["Facturi"],"summary":"Starea în e-Factura","description":"`not_sent`, `pending`, `accepted` sau `rejected`, indexul de încărcare și motivele respingerii, pe înțeles (textul ANAF în `detail`). În test: rezultatul validării XML la ANAF.","operationId":"get_invoice_efactura_v1_invoices__invoice_id__efactura_get","security":[{"ApiKey":[]}],"parameters":[{"name":"invoice_id","in":"path","required":true,"schema":{"type":"string","title":"Invoice Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EfacturaState"}}}},"400":{"description":"Cerere invalidă (JSON, Idempotency-Key).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Cheie lipsă, greșită sau revocată.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"API oprit, plan fără live, drept lipsă.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Factura nu există (pentru cheia și modul folosite).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Parametri invalizi; `field` arată care.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Prea multe cereri sau facturi; vezi Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"webhooks":{"invoice.created":{"post":{"tags":["Webhook-uri"],"summary":"Factură emisă","description":"O factură nouă prin API (și stornările, cu `kind: storno`).\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_invoice_created","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"efactura.accepted":{"post":{"tags":["Webhook-uri"],"summary":"Acceptată în e-Factura","description":"ANAF a acceptat factura.\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_efactura_accepted","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"efactura.rejected":{"post":{"tags":["Webhook-uri"],"summary":"Respinsă în e-Factura","description":"ANAF a respins factura sau validarea dinaintea trimiterii a găsit erori; motivele sunt în `efactura.errors`.\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_efactura_rejected","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"invoice.paid":{"post":{"tags":["Webhook-uri"],"summary":"Factură încasată","description":"Factura apare încasată integral în FacturOne (`paid_at`).\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_invoice_paid","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"invoice.cancelled":{"post":{"tags":["Webhook-uri"],"summary":"Factură stornată","description":"Factura a fost stornată; `cancelled_by` arată stornarea.\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_invoice_cancelled","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"invoice.failed":{"post":{"tags":["Webhook-uri"],"summary":"Factură neemisă","description":"O factură rămasă `pending_confirmation` nu a fost creată în Facturare; are `status: failed` și nu se numără.\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_invoice_failed","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"monthly_limit.warning":{"post":{"tags":["Webhook-uri"],"summary":"Limita lunară: 80% și 100%","description":"Facturile reale din lună, stornările incluse, au ajuns la 80% sau la 100% din cele incluse. `data.object` e `monthly_usage`.\n\nAntete: `FacturOne-Signature: t=<timp unix>,v1=<HMAC-SHA256 hex>`, `FacturOne-Timestamp`, `FacturOne-Event-Id`, `FacturOne-Event-Type`. `v1` = HMAC-SHA256 al textului `<t>.<corpul exact>`, cu secretul adresei (`whsec_…`). Răspunde 2xx în cel mult 10 secunde; altfel reîncercăm după 1 min, 5 min, 30 min, 2 h și 12 h. Exemple de verificare în Node, PHP și Python: /v1/docs#webhooks.","operationId":"webhook_monthly_limit_warning","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}},"required":true},"responses":{"200":{"description":"Orice răspuns 2xx confirmă primirea.","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ClientIn":{"properties":{"type":{"anyOf":[{"type":"string","enum":["company","individual"]},{"type":"null"}],"title":"Type","description":"`company` (implicit când există `cui`) sau `individual` (persoană fizică)."},"cui":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Cui","description":"Firmă: CUI, cu sau fără RO. Persoană fizică: CNP (opțional).","examples":["RO12345674"]},"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Name","description":"Denumirea. La firme se completează din baza FacturOne AI."},"reg_com":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Reg Com","description":"Nr. Registrul Comerțului."},"address":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Address"},"city":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"City","description":"Localitatea. În București: sectorul."},"county":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"County","description":"Județul: nume (Cluj) sau cod (CJ)."},"sector":{"anyOf":[{"type":"integer","maximum":6.0,"minimum":1.0},{"type":"null"}],"title":"Sector","description":"Sectorul, pentru București."},"country":{"type":"string","maxLength":2,"minLength":2,"title":"Country","description":"Cod de țară ISO, două litere.","default":"RO"},"email":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}],"title":"Phone"}},"additionalProperties":false,"type":"object","title":"ClientIn"},"ClientOut":{"properties":{"type":{"type":"string","title":"Type"},"name":{"type":"string","title":"Name"},"cui":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cui"},"reg_com":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reg Com"},"address":{"type":"string","title":"Address"},"city":{"type":"string","title":"City"},"county":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"County"},"sector":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Sector"},"country":{"type":"string","title":"Country"},"email":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email"},"phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Phone"}},"type":"object","required":["type","name","address","city","country"],"title":"ClientOut"},"EfacturaError":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail"}},"type":"object","required":["code","message"],"title":"EfacturaError"},"EfacturaState":{"properties":{"status":{"type":"string","enum":["not_sent","pending","accepted","rejected"],"title":"Status"},"upload_index":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upload Index"},"errors":{"items":{"$ref":"#/components/schemas/EfacturaError"},"type":"array","title":"Errors","default":[]},"test":{"type":"boolean","title":"Test"},"validation":{"anyOf":[{"$ref":"#/components/schemas/Validation"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At"}},"type":"object","required":["status","test"],"title":"EfacturaState"},"EfacturaSummary":{"properties":{"status":{"type":"string","enum":["not_sent","pending","accepted","rejected"],"title":"Status"},"upload_index":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Upload Index"},"errors":{"items":{"$ref":"#/components/schemas/EfacturaError"},"type":"array","title":"Errors","default":[]}},"type":"object","required":["status"],"title":"EfacturaSummary"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","examples":["validation_error"]},"message":{"type":"string","title":"Message","examples":["Câmpul este obligatoriu."]},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","examples":["lines[0].quantity"]},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"},"details":{"anyOf":[{"items":{"$ref":"#/components/schemas/ErrorDetail"},"type":"array"},{"type":"null"}],"title":"Details"}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorDetail":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"}},"type":"object","required":["code","message"],"title":"ErrorDetail"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"InvoiceCreate":{"properties":{"client":{"$ref":"#/components/schemas/ClientIn"},"lines":{"items":{"$ref":"#/components/schemas/LineIn"},"type":"array","maxItems":100,"minItems":1,"title":"Lines"},"series":{"type":"string","maxLength":20,"minLength":1,"title":"Series","description":"Obligatoriu. Una din seriile bifate pentru API în API FacturOne → Facturare → Serii pentru API (aceleași reguli în test și pe live).","examples":["API"]},"number":{"anyOf":[{"type":"integer","maximum":2147483647.0,"minimum":1.0},{"type":"null"}],"title":"Number","description":"Opțional. Fără el, FacturOne AI dă cel mai mare număr folosit pe serie + 1. Cu el, factura primește exact acest număr dacă e liber (409 number_taken dacă e folosit); un număr cu gol sau sub ultimul folosit se emite, cu un avertisment în warnings.","examples":[143]},"issue_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Issue Date","description":"Implicit azi (ora României)."},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Due Date","description":"Implicit data facturii + 15 zile."},"currency":{"type":"string","maxLength":3,"minLength":3,"title":"Currency","description":"RON sau o monedă cu curs BNR.","default":"RON"},"notes":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Notes","description":"Observații, apar pe factură."},"send_to_efactura":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send To Efactura","description":"Implicit setarea e-Factura automată a firmei."}},"additionalProperties":false,"type":"object","required":["client","lines","series"],"title":"InvoiceCreate"},"InvoiceEmail":{"properties":{"to":{"items":{"type":"string"},"type":"array","maxItems":5,"minItems":1,"title":"To","description":"Destinatarii, 1–5 adrese. Fiecare adresă primește factura cu PDF-ul atașat.","examples":[["contabilitate@client.ro"]]},"subject":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Subject","description":"Subiectul. Implicit: „Factura {nr_factura} din {data_factura}”."},"message":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Message","description":"Textul e-mailului (text simplu). Poți folosi {nr_factura}, {data_factura}, {data_scadenta}, {firma_client} și {firma}."}},"additionalProperties":false,"type":"object","required":["to"],"title":"InvoiceEmail"},"InvoiceEmailOut":{"properties":{"object":{"type":"string","const":"invoice_email","title":"Object","default":"invoice_email"},"id":{"type":"string","title":"Id"},"invoice_id":{"type":"string","title":"Invoice Id"},"livemode":{"type":"boolean","title":"Livemode"},"to":{"items":{"type":"string"},"type":"array","title":"To"},"requested_to":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Requested To","description":"Doar în test: adresele cerute. E-mailul de test pleacă doar la adresa contului."},"subject":{"type":"string","title":"Subject"},"status":{"type":"string","enum":["queued","sent_to_provider"],"title":"Status"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","invoice_id","livemode","to","subject","status","created_at"],"title":"InvoiceEmailOut"},"InvoiceList":{"properties":{"object":{"type":"string","const":"list","title":"Object","default":"list"},"data":{"items":{"$ref":"#/components/schemas/InvoiceOut"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More"},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor"}},"type":"object","required":["data","has_more"],"title":"InvoiceList"},"InvoiceOut":{"properties":{"id":{"type":"string","title":"Id","examples":["inv_3f9c1d2e7a8b4c5d6e7f8a9b"]},"object":{"type":"string","const":"invoice","title":"Object","default":"invoice"},"mode":{"type":"string","enum":["live","test"],"title":"Mode"},"status":{"type":"string","enum":["issued","pending_confirmation","failed"],"title":"Status","description":"`issued`: factura există. `pending_confirmation`: Facturare nu a confirmat-o încă; o verificăm și primești `invoice.created` sau `invoice.failed`. `failed`: Facturare nu a creat-o și nu se numără.","default":"issued"},"series":{"type":"string","title":"Series"},"number":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number"},"document_number":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Document Number","description":"Gol cât timp factura nu e emisă."},"issue_date":{"type":"string","format":"date","title":"Issue Date"},"due_date":{"type":"string","format":"date","title":"Due Date"},"currency":{"type":"string","title":"Currency"},"exchange_rate":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Exchange Rate"},"client":{"$ref":"#/components/schemas/ClientOut"},"lines":{"items":{"$ref":"#/components/schemas/LineOut"},"type":"array","title":"Lines"},"totals":{"$ref":"#/components/schemas/TotalsOut"},"notes":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Notes"},"send_to_efactura":{"type":"boolean","title":"Send To Efactura"},"efactura":{"$ref":"#/components/schemas/EfacturaSummary"},"kind":{"type":"string","enum":["invoice","storno"],"title":"Kind","description":"`storno` pentru factura de stornare (cantități negative).","default":"invoice"},"reverses":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reverses","description":"La stornare: id-ul facturii stornate."},"cancelled_by":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cancelled By","description":"Dacă factura a fost stornată: id-ul stornării."},"paid_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Paid At","description":"Când am văzut factura încasată integral în FacturOne (doar live)."},"email_status":{"type":"string","enum":["none","queued","sent_to_provider","failed"],"title":"Email Status","description":"Ultima trimitere pe email: `none` (niciuna), `queued` (live: predat către FacturOne, care nu confirmă livrarea), `sent_to_provider` (test: predat furnizorului de e-mail), `failed`.","default":"none"},"email_status_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Email Status At","description":"Când s-a schimbat `email_status`."},"warnings":{"items":{"$ref":"#/components/schemas/WarningOut"},"type":"array","title":"Warnings","description":"Avertismente despre număr: `gap_after` (numere sărite), `number_out_of_order` (sub ultimul folosit)."},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["id","mode","series","number","issue_date","due_date","currency","client","lines","totals","send_to_efactura","efactura","created_at"],"title":"InvoiceOut"},"KeyLimits":{"properties":{"requests_per_minute":{"type":"integer","title":"Requests Per Minute"},"invoices_per_day":{"type":"integer","title":"Invoices Per Day"}},"type":"object","required":["requests_per_minute","invoices_per_day"],"title":"KeyLimits"},"LineIn":{"properties":{"name":{"type":"string","maxLength":300,"minLength":1,"title":"Name","examples":["Abonament noiembrie"]},"quantity":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"string"}],"title":"Quantity","examples":[1]},"unit":{"type":"string","maxLength":20,"minLength":1,"title":"Unit","description":"Unitatea de măsură (buc, ore, luna, kg …).","default":"buc"},"unit_price":{"anyOf":[{"type":"number","minimum":0.0},{"type":"string"}],"title":"Unit Price","description":"Preț unitar fără TVA.","examples":[100.0]},"vat_rate":{"type":"integer","title":"Vat Rate","description":"Cota TVA: 21, 11 sau 0.","examples":[21]}},"additionalProperties":false,"type":"object","required":["name","quantity","unit_price","vat_rate"],"title":"LineIn"},"LineOut":{"properties":{"name":{"type":"string","title":"Name"},"quantity":{"type":"number","title":"Quantity"},"unit":{"type":"string","title":"Unit"},"unit_price":{"type":"number","title":"Unit Price"},"vat_rate":{"type":"integer","title":"Vat Rate"},"net_amount":{"type":"number","title":"Net Amount"},"vat_amount":{"type":"number","title":"Vat Amount"},"total":{"type":"number","title":"Total"}},"type":"object","required":["name","quantity","unit","unit_price","vat_rate","net_amount","vat_amount","total"],"title":"LineOut"},"Me":{"properties":{"object":{"type":"string","title":"Object","default":"api_key"},"mode":{"type":"string","title":"Mode"},"key_prefix":{"type":"string","title":"Key Prefix"},"scopes":{"items":{"type":"string"},"type":"array","title":"Scopes"},"limits":{"$ref":"#/components/schemas/KeyLimits"},"live_invoices_enabled":{"type":"boolean","title":"Live Invoices Enabled"},"monthly":{"anyOf":[{"$ref":"#/components/schemas/MonthlyUsage"},{"type":"null"}]},"series":{"items":{"type":"string"},"type":"array","title":"Series","description":"Seriile bifate pentru API (API FacturOne → Facturare → Serii pentru API); `series` din factură e una din ele."}},"type":"object","required":["mode","key_prefix","scopes","limits","live_invoices_enabled"],"title":"Me"},"MonthlyUsage":{"properties":{"limit":{"type":"integer","title":"Limit"},"used":{"type":"integer","title":"Used"},"reset_at":{"type":"string","title":"Reset At"}},"type":"object","required":["limit","used","reset_at"],"title":"MonthlyUsage"},"PdfLink":{"properties":{"url":{"type":"string","title":"Url"},"expires_at":{"type":"string","title":"Expires At"}},"type":"object","required":["url","expires_at"],"title":"PdfLink"},"StornoCreate":{"properties":{"issue_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Issue Date","description":"Data stornării. Implicit: azi (ora României)."},"send_to_efactura":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Send To Efactura","description":"Implicit: ca la factura stornată."},"notes":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}],"title":"Notes","description":"Text adăugat după „Storno factura seria X nr. Y”."},"lines":{"anyOf":[{"items":{"type":"object"},"type":"array"},{"type":"null"}],"title":"Lines","description":"Stornarea parțială nu este disponibilă: cu acest câmp răspunsul e 422 partial_storno_not_supported."},"series":{"anyOf":[{"type":"string","maxLength":20,"minLength":1},{"type":"null"}],"title":"Series","description":"Implicit seria facturii stornate. Altfel una din seriile bifate pentru API.","examples":["API"]},"number":{"anyOf":[{"type":"integer","maximum":2147483647.0,"minimum":1.0},{"type":"null"}],"title":"Number","description":"Opțional, cu aceleași reguli ca la emitere."}},"additionalProperties":false,"type":"object","title":"StornoCreate"},"TotalsOut":{"properties":{"net":{"type":"number","title":"Net"},"vat":{"type":"number","title":"Vat"},"total":{"type":"number","title":"Total"},"vat_breakdown":{"items":{"$ref":"#/components/schemas/VatBreakdown"},"type":"array","title":"Vat Breakdown"}},"type":"object","required":["net","vat","total","vat_breakdown"],"title":"TotalsOut"},"Validation":{"properties":{"source":{"type":"string","enum":["anaf","local"],"title":"Source"},"valid":{"type":"boolean","title":"Valid"},"errors":{"items":{"$ref":"#/components/schemas/EfacturaError"},"type":"array","title":"Errors","default":[]},"trace_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Trace Id"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["source","valid"],"title":"Validation"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"VatBreakdown":{"properties":{"category":{"type":"string","title":"Category"},"rate":{"type":"integer","title":"Rate"},"taxable":{"type":"number","title":"Taxable"},"vat":{"type":"number","title":"Vat"}},"type":"object","required":["category","rate","taxable","vat"],"title":"VatBreakdown"},"WarningOut":{"properties":{"code":{"type":"string","enum":["gap_after","number_out_of_order"],"title":"Code"},"message":{"type":"string","title":"Message"}},"type":"object","required":["code","message"],"title":"WarningOut"},"WebhookData":{"properties":{"object":{"type":"object","title":"Object","description":"Factura (același obiect ca la GET /v1/invoices/{id}) sau, la monthly_limit.warning, `monthly_usage`: month, threshold (80 / 100), included, used, over_limit, reset_at."}},"type":"object","required":["object"],"title":"WebhookData"},"WebhookEvent":{"properties":{"id":{"type":"string","title":"Id","description":"Unic; păstrează-l ca să sari peste repetări.","examples":["evt_9a8b7c6d5e4f3a2b1c0d9e8f"]},"object":{"type":"string","const":"event","title":"Object","default":"event"},"type":{"type":"string","enum":["invoice.created","efactura.accepted","efactura.rejected","invoice.paid","invoice.cancelled","invoice.failed","monthly_limit.warning","webhook.test"],"title":"Type"},"created":{"type":"string","title":"Created","examples":["2026-12-12T10:20:00Z"]},"livemode":{"type":"boolean","title":"Livemode","description":"false pentru evenimentele din modul test."},"data":{"$ref":"#/components/schemas/WebhookData"}},"type":"object","required":["id","type","created","livemode","data"],"title":"WebhookEvent"}},"securitySchemes":{"ApiKey":{"type":"http","description":"Cheia API, în antetul `Authorization: Bearer fo_test_…` (sau `fo_live_…`).","scheme":"bearer"}}},"x-error-codes":[{"code":"bad_request","status":400,"meaning":"Cererea nu poate fi citită.","action":"Verifică metoda, antetele și corpul cererii."},{"code":"invalid_json","status":400,"meaning":"Corpul cererii nu este JSON valid.","action":"Trimite JSON valid, cu Content-Type: application/json."},{"code":"idempotency_key_required","status":400,"meaning":"Lipsește antetul Idempotency-Key.","action":"Trimite un identificator unic al operației (ex. comanda-1042), același la fiecare reîncercare."},{"code":"idempotency_key_invalid","status":400,"meaning":"Idempotency-Key are alt format decât 1–128 caractere ASCII vizibile.","action":"Folosește doar litere, cifre și semne, fără spații."},{"code":"invalid_cursor","status":400,"meaning":"Cursorul de paginare nu este valid.","action":"Folosește next_cursor din răspunsul anterior."},{"code":"missing_api_key","status":401,"meaning":"Lipsește cheia API.","action":"Trimite antetul Authorization: Bearer <cheie API>."},{"code":"invalid_api_key","status":401,"meaning":"Cheia nu există sau e scrisă greșit.","action":"Verifică cheia; dacă ai pierdut-o, creează alta în API FacturOne → Chei API."},{"code":"api_key_revoked","status":401,"meaning":"Cheia a fost revocată.","action":"Folosește o cheie activă."},{"code":"forbidden","status":403,"meaning":"Acces interzis.","action":"Verifică cheia și drepturile ei."},{"code":"api_disabled","status":403,"meaning":"API-ul nu este pornit pentru firmă.","action":"Activează aplicația API FacturOne din App Store sau scrie-ne."},{"code":"plan_not_allowed","status":403,"meaning":"Planul firmei nu include API-ul sau cheile live.","action":"Folosește o cheie de test sau schimbă planul."},{"code":"insufficient_scope","status":403,"meaning":"Cheia nu are dreptul cerut (ex. email:send).","action":"Creează o cheie cu dreptul necesar în API FacturOne → Chei API."},{"code":"live_invoices_disabled","status":403,"meaning":"Facturile reale prin API nu sunt încă pornite pentru firmă.","action":"Lucrează cu o cheie de test până la pornire."},{"code":"email_disabled","status":403,"meaning":"Trimiterea pe e-mail prin API e oprită în acest mod.","action":"Scrie-ne dacă ai nevoie de ea."},{"code":"not_found","status":404,"meaning":"Ruta sau fișierul nu există.","action":"Verifică adresa."},{"code":"invoice_not_found","status":404,"meaning":"Factura nu există pentru cheia folosită (alt id, altă firmă sau celălalt mod, test / live).","action":"Verifică id-ul și cheia."},{"code":"method_not_allowed","status":405,"meaning":"Metoda nu este permisă pe această rută.","action":"Verifică metoda (GET, POST …)."},{"code":"idempotency_conflict","status":409,"meaning":"Idempotency-Key a fost folosită deja pentru alt conținut.","action":"Folosește o cheie nouă pentru o operație nouă."},{"code":"idempotency_key_in_progress","status":409,"meaning":"O cerere cu aceeași Idempotency-Key încă rulează.","action":"Reîncearcă după Retry-After."},{"code":"already_cancelled","status":409,"meaning":"Factura e deja stornată.","action":"Nu mai e nimic de făcut; cancelled_by arată stornarea."},{"code":"storno_in_progress","status":409,"meaning":"O altă stornare a acestei facturi nu s-a terminat.","action":"Reîncearcă stornarea cu aceeași Idempotency-Key."},{"code":"number_taken","status":409,"meaning":"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.","action":"Cu number: trimite alt număr sau nu-l trimite. Fără number: reîncearcă după Retry-After, cu aceeași Idempotency-Key."},{"code":"series_closed","status":409,"meaning":"Seria bifată pentru API a fost închisă sau ștearsă în FacturOne.","action":"Redeschide seria în FacturOne sau bifează alta: API FacturOne → Facturare → Serii pentru API."},{"code":"invoice_pending_confirmation","status":409,"meaning":"FacturOne nu a confirmat încă factura (status pending_confirmation).","action":"Reîncearcă după Retry-After sau așteaptă invoice.created."},{"code":"invoice_failed","status":409,"meaning":"Factura acestei Idempotency-Key nu s-a creat în FacturOne și nu se numără.","action":"Trimite factura din nou, cu o Idempotency-Key nouă."},{"code":"link_expired","status":410,"meaning":"Linkul semnat a expirat.","action":"Cere un link nou cu /pdf-link."},{"code":"payload_too_large","status":413,"meaning":"Corpul cererii depășește 256 KB.","action":"Trimite mai puține rânduri pe factură."},{"code":"unsupported_media_type","status":415,"meaning":"Corpul nu este trimis ca JSON.","action":"Trimite Content-Type: application/json."},{"code":"validation_error","status":422,"meaning":"Un câmp lipsește sau are alt format.","action":"Corectează câmpul din field (vezi și details)."},{"code":"client_not_found","status":422,"meaning":"Nu găsim firma cu acest CUI.","action":"Verifică CUI-ul sau trimite denumirea, adresa, localitatea și județul clientului."},{"code":"client_incomplete","status":422,"meaning":"Clientului îi lipsesc date cerute de e-Factura (adresă, localitate, județ).","action":"Completează câmpul din field."},{"code":"email_invalid","status":422,"meaning":"Adresa de e-mail nu este validă.","action":"Corectează adresa din field."},{"code":"series_required","status":422,"meaning":"Lipsește series: fiecare factură spune pe ce serie se emite.","action":"Trimite una din seriile bifate în API FacturOne → Facturare → Serii pentru API."},{"code":"series_invalid","status":422,"meaning":"Seria are alt format decât 1–20 litere, cifre sau cratime.","action":"Trimite numele seriei exact ca în FacturOne (ex. API, EMG-HU-FBE)."},{"code":"series_not_allowed","status":422,"meaning":"Seria trimisă nu e bifată pentru API (în test și pe live).","action":"Bifeaz-o în API FacturOne → Facturare → Serii pentru API sau trimite una din seriile bifate; mesajul le arată."},{"code":"number_invalid","status":422,"meaning":"Numărul trimis e sub primul număr al seriei din FacturOne.","action":"Trimite un număr de la primul număr al seriei în sus sau nu trimite number."},{"code":"date_in_future","status":422,"meaning":"Data e în viitor.","action":"Trimite data de azi sau una din trecut."},{"code":"date_too_old","status":422,"meaning":"Data e mai veche decât permite FacturOne.","action":"Folosește o dată mai apropiată."},{"code":"date_not_chronological","status":422,"meaning":"Pe serie există deja o factură cu dată mai nouă.","action":"Folosește data ultimei facturi din serie sau una mai nouă."},{"code":"due_date_before_issue","status":422,"meaning":"Scadența e înaintea datei facturii.","action":"Trimite o scadență egală sau mai târzie."},{"code":"storno_date_before_invoice","status":422,"meaning":"Data stornării e înaintea datei facturii stornate.","action":"Folosește data facturii sau una mai nouă."},{"code":"vat_rate_invalid","status":422,"meaning":"Cota de TVA nu este permisă sau nu există în contul firmei.","action":"Folosește una dintre cotele firmei (ex. 21, 11, 0)."},{"code":"vat_not_allowed","status":422,"meaning":"Firma nu este plătitoare de TVA, dar factura are TVA.","action":"Trimite cota 0 pe rânduri."},{"code":"currency_not_supported","status":422,"meaning":"Moneda nu este un cod ISO de trei litere.","action":"Trimite codul monedei (ex. RON, EUR)."},{"code":"exchange_rate_unavailable","status":422,"meaning":"Nu există curs BNR pentru moneda și data facturii.","action":"Reîncearcă după publicarea cursului sau emite în RON."},{"code":"facturare_rejected","status":422,"meaning":"FacturOne a refuzat factura la propriile verificări.","action":"Verifică datele facturii; codul FacturOne e în mesaj."},{"code":"storno_not_allowed","status":422,"meaning":"O factură de stornare nu se mai stornează.","action":"Stornează factura inițială."},{"code":"partial_storno_not_supported","status":422,"meaning":"Stornarea parțială nu este disponibilă.","action":"Stornează toată factura, apoi emite una nouă cu ce rămâne."},{"code":"account_email_missing","status":422,"meaning":"Contul FacturOne nu are adresă de e-mail pentru e-mailurile de test.","action":"Adaugă adresa în contul FacturOne."},{"code":"rate_limited","status":429,"meaning":"Prea multe cereri într-un minut.","action":"Așteaptă Retry-After secunde; urmărește X-RateLimit-Remaining."},{"code":"daily_invoice_limit","status":429,"meaning":"Ai atins limita de facturi pe zi.","action":"Reîncearcă după Retry-After (miezul nopții, ora României)."},{"code":"monthly_limit_reached","status":429,"meaning":"Ai atins facturile incluse pe lună (stornările incluse), iar firma are blocare la depășire. Stornările nu sunt oprite.","action":"Nu reîncerca automat: așteaptă reset_at din details sau cere mărirea limitei."},{"code":"email_limit_reached","status":429,"meaning":"Ai atins limita de e-mailuri pe zi.","action":"Reîncearcă după Retry-After (miezul nopții)."},{"code":"internal_error","status":500,"meaning":"Eroare neașteptată la noi.","action":"Reîncearcă peste câteva minute, cu aceeași Idempotency-Key; dacă persistă, trimite-ne request_id."},{"code":"email_not_sent","status":502,"meaning":"FacturOne nu a trimis e-mailul sau nu a confirmat trimiterea.","action":"Verifică email_status al facturii înainte să reîncerci, ca să nu trimiți de două ori."},{"code":"facturare_unavailable","status":503,"meaning":"FacturOne nu răspunde sau nu ne putem conecta.","action":"Reîncearcă după Retry-After, cu aceeași Idempotency-Key."},{"code":"series_busy","status":503,"meaning":"Seria e ocupată cu alte facturi ale firmei prin API.","action":"Reîncearcă după Retry-After, cu aceeași Idempotency-Key."},{"code":"busy","status":503,"meaning":"Prea multe facturi de test simultan pe aceeași serie.","action":"Reîncearcă după Retry-After, cu aceeași Idempotency-Key."},{"code":"upstream_timeout","status":504,"meaning":"FacturOne nu a răspuns la timp.","action":"Reîncearcă după Retry-After, cu aceeași Idempotency-Key."}],"servers":[{"url":"https://api.facturone.com"}]}