Endpoint-urile aplicațiilor conectate | eZif pentru dezvoltatori

Adresa de bază: https://dev.ezif.ro/api/ext/v1 (test) / https://app.ezif.ro/api/ext/v1 (producție). Autentificarea: Autentificarea și semnătura.

Metoda	Cale	Drept	Ce face
GET	`/ping`	—	firma, utilizatorul tehnic, drepturile, seriile, setările și evenimentele cheii
POST	`/proformas`	`proforma:write`	emite proforma cu plată; idempotentă pe `external_id`
GET	`/proformas/{id}`	`documents:read`	proforma: stare, total, încasat, rest, valabilitate, `pay_url`, `pdf_url`, încasările, factura emisă
GET	`/proformas/by-external/{external_id}`	`documents:read`	aceeași, după `external_id`
POST	`/proformas/{id}/payments`	`payment:write`	plata raportată de aplicație; la plata integrală, răspunsul conține factura emisă
POST	`/proformas/{id}/cancel`	`proforma:write`	anulează o proformă neplătită
POST	`/proformas/{id}/send`	`proforma:write`	retrimite proforma pe e-mail (aceeași adresă sau `{"email": "…"}`)
GET	`/invoices`	`documents:read`	lista facturilor și a stornărilor: `since`, `series`, `status`, `spv`, `page`, `per_page`
GET	`/invoices/{id}` · `/invoices/by-external/{id}` · `/invoices/{id}/pdf`	`documents:read`	factura (cu `from_proforma_id`), după `external_id`, PDF
POST	`/invoices/{id}/storno`	`invoice:write`	storno total; webhook `invoice.storno`
POST	`/callback` · `/callback/test`	`webhooks:manage`	adresa de webhook a aplicației și testul ei

Metodele pentru magazine (POST /invoices, încasarea pe factură, conversia, articolele, stocul) sunt în API-ul extern.

POST /proformas

{
  "external_id": "PJAPI-SUB-1842-2026-10",
  "currency": "RON", "price_mode": "net", "valid_days": 15,
  "client": {"name": "Alfa Instal SRL", "cui": "RO12345678", "reg_com": "J40/1/2020",
             "email": "contabilitate@alfainstal.ro", "county": "B", "city": "Sector 3", "street": "Str. Alfa 1"},
  "lines": [{"code": "PJAPI-PRO", "name": "Abonament pjAPI.ro Pro — octombrie 2026",
             "qty": 1, "price": 249.00, "vat": 21, "service": true}],
  "period": {"from": "2026-10-01", "to": "2026-10-31"},
  "notes": "Abonament lunar, cont #1842"
}

Câmp	Explicație
`external_id`	obligatoriu, unic pe firmă (abonament + perioadă). A doua cerere cu același `external_id` întoarce aceeași proformă, cu `"duplicate": true`, fără e-mail nou
`series`	opțional; doar seria cheii sau una din „seriile permise” (altfel 403 `SERIES_NOT_ALLOWED`)
`valid_days`	1–90; lipsă = valabilitatea din setările cheii
`client`, `lines`, `currency`, `price_mode`	aceleași reguli ca la `POST /invoices`; adresa clientului e obligatorie (apare pe factura din e-Factura)
`period`	perioada abonamentului; apare pe proformă și pe factură („Perioada: 01.10.2026 – 31.10.2026”)

Răspunsul 201:

{"id": 9012, "kind": "proforma", "series": "PJPF", "number_text": "PJPF00042", "issue_date": "2026-10-01",
 "valid_until": "2026-10-16", "currency": "RON", "total": "301.29", "paid": "0.00", "remaining": "301.29", "status": "unpaid",
 "external_id": "PJAPI-SUB-1842-2026-10", "period": {"from": "2026-10-01", "to": "2026-10-31"},
 "pay_url": "https://app.ezif.ro/api/public/plata/…", "pdf_url": "https://app.ezif.ro/api/public/documente/…",
 "payments": [], "invoice": null, "emailed": true}

POST /proformas/{id}/payments

{"amount": 301.29, "paid_on": "2026-10-03", "method": "card", "reference": "pi_3Q…", "external_id": "PJAPI-PAY-55120"}

method: card, online, transfer, numerar, alta. external_id al plății: aceeași plată nu se înregistrează de două ori. Răspunsul: proforma actualizată; la plata integrală, status: "invoiced" și invoice:

"invoice": {"id": 9013, "number_text": "PJ00118", "total": "301.29", "paid": "301.29", "payment_status": "paid",
            "spv_status": "queued", "pdf_url": "https://app.ezif.ro/api/public/documente/…"}

GET /invoices

Parametru	Valori
`since`	ISO 8601 (ex. `2026-10-01T00:00:00Z`): doar documentele modificate după
`series`	prefixul seriei (ex. `PJ`)
`status`	`issued` (neîncasate), `paid`, `cancelled` (stornate)
`spv`	`accepted`, `rejected`, `pending`
`page`, `per_page`	`per_page` ≤ 200 (implicit 100)

Răspunsul: {"page": 1, "per_page": 100, "invoices": [{…factura…, "from_proforma_id": 9012}]}, cele mai noi primele. Parametrii nu intră în semnătură (doar calea).