Dezvoltatori

API pentru dezvoltatori

API-ul public eBil expune la /api/v1 facturi emise, clienți, produse, categorii, plăți, facturi primite, jurnalul de casă și bancă și datele firmei. Te autentifici cu o cheie API cu prefixul ebil_, generată din Setări → API (doar managerii), iar consumul se plătește pay-as-you-go din portofel: citirile de la 0,02 € per apel, scrierile de la 0,01 €. Fiecare răspuns include meta.charged_tokens și meta.balance.

API-ul public eBil îți dă acces programatic la datele firmei tale: facturi emise, clienți, produse, categorii, plăți, facturi primite, jurnalul de casă și bancă și datele firmei. Toate cererile se autentifică cu o cheie API, iar consumul se plătește pay-as-you-go din portofel, per apel.

Facturi emise

Listare, creare cu linii, detalii și actualizare.

Clienți

CRUD complet pentru clienți și firme legate.

Produse

Nomenclator cu prețuri, TVA și categorii.

Categorii produse

CRUD cu suport pentru categorii părinte.

Plăți

Agendă de plăți, export CSV bancar, marcare plătită.

Facturi primite

Citire cu filtre pe status și perioadă, cu liniile incluse.

Casă și bancă

Conturi cu sold calculat și jurnalul de intrări și ieșiri.

Firmă

Datele firmei active ale cheii: CUI, regim fiscal, CAEN.

Autentificare

Generezi cheia API din aplicație, din pagina Setări → API (doar managerii firmei pot gestiona chei). Cheia începe cu prefixul ebil_ și se afișează o singură dată, la generare. O trimiți la fiecare cerere în headerul Authorization: Bearer sau X-API-Key. Cheia lucrează în contextul firmei pentru care a fost generată și consumă din portofelul proprietarului de resurse al firmei.

Exemplu de cerere

curl -X GET "https://app.ebil.ro/api/v1/invoices?per_page=5" \
  -H "Authorization: Bearer ebil_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

Coduri de eroare

Cod	Semnificație	Exemplu de răspuns
401	Cheie API lipsă, invalidă sau revocată.	`{"message": "Cheie API invalidă sau lipsă."}`
402	Portofelul firmei nu are credit suficient pentru apel.	`{"message": "Credit insuficient. Încarcă portofelul pentru a continua."}`
422	Validare eșuată (câmp lipsă sau invalid, resursă în stare imutabilă).	`{"message": "Unul dintre câmpurile customer_id sau customer_cui este obligatoriu."}`
404	Resursa nu există în firma cheii.	`{"message": "Factura nu a fost găsită."}`

Costuri

Citirile (listări, detalii, exporturile de date) costă 0,02 € per apel, iar scrierile și acțiunile (creări, actualizări, ștergeri, marcarea plăților) 0,01 €. Crearea de facturi, clienți, produse, categorii și generarea de plăți din facturi primite au costul propriu, mai jos. Fiecare răspuns include meta.charged_tokens (câți tokeni s-au consumat) și meta.balance (soldul rămas al portofelului).

Citire (api_sync)

0,02 €

0,2 tokeni

Scriere (api_call)

0,01 €

0,1 tokeni

Factură creată/actualizată

0,05 €

0,5 tokeni

Client creat/actualizat/șters

0,01 €

0,1 tokeni

Produs creat/actualizat/șters

0,01 €

0,1 tokeni

Categorie creată/actualizată/ștearsă

0,01 €

0,1 tokeni

Plată generată din factură primită

0,01 €

0,1 tokeni

Export CSV plăți bancare

0,025 €

0,25 tokeni

Convenții

Prefixul tuturor rutelor este /api/v1.
Listările returnează data (array) plus câmpurile de paginare Laravel: current_page, last_page, from, to, total.
Controlul paginii se face cu per_page (implicit 50; maximum 200 la majoritatea listelor, 100 la jurnal).
După fiecare răspuns primești și meta.charged_tokens și meta.balance.

Facturi emise

GET /api/v1/invoices

Filtre: status (draft, issued, pending, paid, partial, overdue), series, number, updated_since, per_page.

POST /api/v1/invoices

GET /api/v1/invoices/{id} acceptă și număr, ex. „EB 142"

PUT /api/v1/invoices/{id}

Creare factură (câmpuri acceptate la POST)

Câmp	Tip	Obligatoriu	Observații
customer_id	integer	da, altfel customer_cui	Clientul trebuie să existe în firmă.
customer_cui	string	alternativă la customer_id	Căutare după CUI pe clientul de tip companie.
issue_date	date (Y-m-d)	da	Data emiterii.
due_date	date	nu	Trebuie să fie ≥ issue_date.
items	array (min. 1)	da	Vezi liniile de mai jos.
items.*.product_id	integer	alternativă la name	Prețul și TVA se moștenesc din produs.
items.*.name	string	da, fără product_id	Denumire liberă a liniei.
items.*.quantity	numeric	nu	Implicit 1.
items.*.unit_price	numeric	nu	Implicit prețul produsului, altfel 0.
items.*.vat_rate	numeric (0-100)	nu	Implicit TVA-ul produsului, altfel 21.
items.*.unit	string	nu	Implicit „buc".
currency	string (3 litere)	nu	Implicit RON.
type	invoice \| proforma	nu	Implicit invoice.
series_id	integer	nu	Implicit seria implicită a firmei.
payment_method	transfer, cash, card, check, other	nu	Implicit transfer.
payment_terms	integer	nu	Termen de plată în zile.
notes	string	nu	Notă vizibilă pe document.
internal_notes	string	nu	Notă internă, neafișată clientului.

La PUT se pot actualiza doar: issue_date, due_date, payment_method, payment_terms, notes, internal_notes. Facturile înscrise în SPV nu mai pot fi modificate (corectarea se face prin notă de credit).

Exemplu

curl -X POST "https://app.ebil.ro/api/v1/invoices" \
  -H "Authorization: Bearer ebil_..." -H "Content-Type: application/json" \
  -d '{
    "customer_cui": "RO34958130",
    "issue_date": "2026-10-16",
    "due_date": "2026-10-30",
    "items": [
      {"product_id": 12, "quantity": 2},
      {"name": "Servicii consultanță", "quantity": 1, "unit_price": 450, "vat_rate": 21}
    ]
  }'

{
  "data": {
    "id": 871,
    "series": "EB",
    "number": "142",
    "display_number": "EB 142",
    "status": "pending",
    "is_draft": true,
    "type": "invoice",
    "issue_date": "2026-10-16",
    "due_date": "2026-10-30",
    "currency": "RON",
    "subtotal": 1240.0,
    "total_vat": 260.4,
    "total": 1500.4,
    "paid_amount": 0.0,
    "customer": {"id": 55, "name": "BRANDED S.R.L.", "cui": "RO34958130"},
    "anaf_status": null,
    "items": [ ... ],
    "created_at": "2026-10-16T09:12:34.000000Z",
    "updated_at": "2026-10-16T09:12:34.000000Z"
  },
  "meta": {"charged_tokens": 0.2, "balance": 41.3}
}

Clienți

GET /api/v1/customers filtre: q, updated_since, per_page

POST /api/v1/customers

GET /api/v1/customers/{id}

PUT /api/v1/customers/{id}

DEL /api/v1/customers/{id}

La POST: type (individual, company) și name sunt obligatorii. Opționale: cnp, email, phone, address, city, county, postal_code, country, bank_name, bank_iban, payment_term, discount_percent, contact_name, contact_role, contact_email, contact_phone, notes. Toate sunt acceptate și la PUT.

curl -X POST "https://app.ebil.ro/api/v1/customers" \
  -H "Authorization: Bearer ebil_..." -H "Content-Type: application/json" \
  -d '{"type": "individual", "name": "Ion Popescu", "email": "[email protected]"}'

{
  "data": {
    "id": 102,
    "type": "individual",
    "name": "Ion Popescu",
    "cnp": null,
    "cui": null,
    "email": "[email protected]",
    "phone": null,
    "payment_term": null,
    "created_at": "2026-10-16T09:20:11.000000Z",
    "updated_at": "2026-10-16T09:20:11.000000Z"
  },
  "meta": {"charged_tokens": 0.5, "balance": 40.8}
}

Produse

GET /api/v1/products filtre: q, updated_since, per_page

POST /api/v1/products

GET /api/v1/products/{id}

PUT /api/v1/products/{id}

DEL /api/v1/products/{id}

La POST: name și price sunt obligatorii. Opționale: sku, description, unit, cost_price, vat_rate sau vat_rate_id (din nomenclatorul de cote), currency_id, product_type_id, category_id, is_active, barcode.

curl -X POST "https://app.ebil.ro/api/v1/products" \
  -H "Authorization: Bearer ebil_..." -H "Content-Type: application/json" \
  -d '{"name": "Consultanță fiscală", "unit": "oră", "price": 450, "vat_rate": 21, "category_id": 3}'

{
  "data": {
    "id": 12,
    "sku": null,
    "name": "Consultanță fiscală",
    "unit": "oră",
    "price": 450.0,
    "cost_price": null,
    "vat_rate": 21.0,
    "currency": "RON",
    "product_type": "Serviciu",
    "category": "Servicii profesionale",
    "category_id": 3,
    "is_active": true,
    "created_at": "2026-10-16T09:25:02.000000Z",
    "updated_at": "2026-10-16T09:25:02.000000Z"
  },
  "meta": {"charged_tokens": 0.5, "balance": 40.3}
}

Categorii produse

GET /api/v1/product-categories filtre: updated_since, per_page

POST /api/v1/product-categories

GET /api/v1/product-categories/{id}

PUT /api/v1/product-categories/{id}

DEL /api/v1/product-categories/{id}

Câmpuri: name (obligatoriu la POST), slug (generat din name dacă lipsește), description, parent_id (altă categorie a firmei, pentru ierarhie).

curl -X POST "https://app.ebil.ro/api/v1/product-categories" \
  -H "Authorization: Bearer ebil_..." -H "Content-Type: application/json" \
  -d '{"name": "Servicii profesionale"}'

{
  "data": {"id": 3, "name": "Servicii profesionale", "slug": "servicii-profesionale", "parent_id": null, "parent_name": null},
  "meta": {"charged_tokens": 0.25, "balance": 40.05}
}

Plăți

GET /api/v1/payments filtre: status (pending, paid, cancelled), kind (supplier, tax, fee, manual), q, per_page

POST /api/v1/payments plată manuală

GET /api/v1/payments/{id}

PUT /api/v1/payments/{id}

DEL /api/v1/payments/{id} doar plățile pending

GET /api/v1/payments/export CSV pentru import bancar (plățile pending)

POST /api/v1/payments/from-received/{receivedInvoiceId}

POST /api/v1/payments/{id}/paid

La POST (plată manuală): beneficiary_name și amount sunt obligatorii. Opționale: beneficiary_fiscal_id, beneficiary_iban, payer_iban, currency, due_date, description, kind (manual, fee), deductible, category. La POST /{id}/paid: opționale paid_at, paid_amount, payment_method.

curl -X POST "https://app.ebil.ro/api/v1/payments" \
  -H "Authorization: Bearer ebil_..." -H "Content-Type: application/json" \
  -d '{"beneficiary_name": "RCS & RDS S.A.", "amount": 120.5, "due_date": "2026-10-25", "description": "Abonament internet"}'

{
  "data": {
    "id": 340,
    "kind": "manual",
    "status": "pending",
    "reference": "EB-20261016-001",
    "beneficiary_name": "RCS & RDS S.A.",
    "amount": 120.5,
    "currency": "RON",
    "due_date": "2026-10-25",
    "paid_at": null
  },
  "meta": {"charged_tokens": 0.1, "balance": 39.95}
}

Facturi primite (doar citire)

Importul rămâne în aplicație (upload XML/PDF, SPV, email); API-ul expune listarea și detaliul, cu liniile incluse, pentru sincronizări externe.

GET /api/v1/received-invoices

Filtre: q, status (imported, validated, paid, partial, rejected, archived, storno), date_from, date_to, per_page (max. 200).

GET /api/v1/received-invoices/{id} cu items

curl "https://app.ebil.ro/api/v1/received-invoices?status=paid&date_from=2026-10-01" \
  -H "Authorization: Bearer ebil_..."

{
  "data": [
    {
      "id": 61,
      "series": "AR",
      "number": "4412",
      "display_number": "AR 4412",
      "status": "paid",
      "payment_status": "paid",
      "supplier": {"name": "Romtelecom S.A.", "fiscal_id": "RO 7738111"},
      "issue_date": "2026-10-02",
      "currency": "RON",
      "subtotal": 238.0,
      "total_vat": 57.12,
      "total": 295.12,
      "paid_amount": 295.12,
      "remaining_amount": 0.0
    }
  ],
  "current_page": 1, "last_page": 1, "from": 1, "to": 1, "total": 1,
  "meta": {"charged_tokens": 0.2, "balance": 39.75}
}

Casă și bancă (doar citire)

Jurnalul se scrie exclusiv prin fluxurile interne (extrase bancare, plăți, sincronizări); API-ul expune conturile, cu soldul calculat, și intrările de jurnal pentru reconciliere și raportare externă.

GET /api/v1/cashbook-accounts

GET /api/v1/cashbook-entries

Filtre: account_id, direction (in, out), date_from, date_to, q, per_page (max. 100).

curl "https://app.ebil.ro/api/v1/cashbook-entries?direction=out&date_from=2026-10-01&per_page=3" \
  -H "Authorization: Bearer ebil_..."

{
  "data": [
    {
      "id": 5231,
      "account": {"id": 4, "name": "Cont ING", "type": "bank", "currency": "RON"},
      "date": "2026-10-03",
      "direction": "out",
      "amount": 295.12,
      "currency": "RON",
      "counterparty": "Romtelecom S.A.",
      "details": "Plata factura AR 4412",
      "received_invoice_id": 61
    }
  ],
  "current_page": 1, "last_page": 8, "from": 1, "to": 3, "total": 22,
  "meta": {"charged_tokens": 0.2, "balance": 39.55}
}

Firmă

GET /api/v1/company

curl "https://app.ebil.ro/api/v1/company" -H "Authorization: Bearer ebil_..."

{
  "data": {
    "id": 7,
    "name": "BRANDED S.R.L.",
    "cui": "RO34958130",
    "registration_number": "J2015001395167",
    "legal_form": "Societate cu raspundere limitata",
    "is_vat_payer": true,
    "tax_regime": "profit",
    "address": "Str. Vidin nr. 12, Pielești, Dolj",
    "caen_code": "6201",
    "caen_description": "Activități de realizare a softului la comandă (software orientat pe client)"
  },
  "meta": {"charged_tokens": 0.2, "balance": 39.35}
}

MCP (Model Context Protocol)

Același registru de tool-uri AI al asistentului eBil este expus și ca server MCP streamable HTTP la POST /api/mcp, cu aceeași cheie API (vezi autentificarea): tool-urile de citire rulează gratuit, iar cele mutante necesită opțiunea „Permite modificări prin MCP" activată pe cheie. Se pot conecta clienți AI precum Claude Desktop sau ChatGPT.

API eBil

Generează o cheie și începe integrarea

Din aplicație, pagina Setări → API (doar managerii). Plătești doar apelurile efectuate, din portofelul firmei.

Creează cont gratuit Vezi prețurile

Primești 5 € credit de start. Nu ai nevoie de card.