debill
Produs Prețuri Blog Resurse Autentificare Începe gratuit

API v1

Conectează-ți site-urile.

Un cont debill, oricâte magazine. Creează un site din Site-uri & API în panou, copiază tokenul și trimite cereri JSON către https://debill.ro/api/v1.

Autentificare

Fiecare cerere trimite tokenul site-ului în header. Răspunsurile sunt JSON; limita implicită este 120 cereri/minut per site.

Authorization: Bearer dbl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Accept: application/json

Endpoint-uri

MetodăCaleDescriere
GET/meVerifică tokenul; întoarce site-ul și firma.
GET/invoicesListează facturile site-ului. Filtre: status (draft|sent|paid|overdue|cancelled), external_reference, client_id, from, to, per_page, all_sites=1.
POST/invoicesEmite o factură. Idempotent după external_reference.
GET/invoices/{id}Detaliile unei facturi, cu rânduri și link public.
POST/invoices/{id}/sendMarchează o ciornă ca emisă.
POST/invoices/{id}/payMarchează factura ca încasată (opțional paid_at).
POST/invoices/{id}/cancelAnulează factura.
GET/clientsListează clienții. Filtre: search, external_id.
POST/clientsCreează un client.
GET/clients/{id}Detaliile unui client.
PATCH/clients/{id}Actualizează un client.
GET/productsCatalogul de produse active. Filtre: search, sku.
GET/products/{id}Detaliile unui produs.

Emite o factură

Trimite fie client_id, fie un obiect client — îl potrivim după external_id, cui sau email și îl creăm dacă nu există. Rândurile pot folosi product_id din catalog. status poate fi draft, sent (implicit) sau paid.

POST https://debill.ro/api/v1/invoices
{
  "external_reference": "order-1042",
  "status": "paid",
  "issue_date": "2026-10-20",
  "due_date": "2026-11-04",
  "currency": "RON",
  "client": {
    "type": "company",
    "name": "SC Alpha SRL",
    "cui": "RO12345678",
    "email": "contabilitate@alpha.ro",
    "address": "Str. Exemplu 1", "city": "București", "country": "RO",
    "external_id": "customer-77"
  },
  "items": [
    { "description": "Tricou rebel", "unit": "buc", "quantity": 2, "unit_price": 79, "vat_rate": 21 },
    { "product_id": 5, "quantity": 1 }
  ],
  "notes": "Mulțumim pentru comandă!"
}

Răspuns 201 (sau 200 dacă factura cu acel external_reference există deja):

{
  "data": {
    "id": 128, "number": "2026-042", "status": "paid",
    "subtotal": 158.0, "vat_total": 33.18, "total": 191.18,
    "public_url": "https://debill.ro/f/…",
    "client": { "id": 31, "name": "SC Alpha SRL", … },
    "items": [ … ]
  }
}

Erorile de validare întorc 422 cu câmpul errors; un token greșit întoarce 401.

Webhook-uri

Dacă site-ul are un Webhook URL, primește un POST la evenimentele invoice.created, invoice.sent, invoice.paid, invoice.cancelled pentru facturile create de el. Reîncercăm de până la 5 ori dacă nu răspunzi cu 2xx.

X-Debill-Event: invoice.paid
X-Debill-Timestamp: 1792490000
X-Debill-Signature: sha256=<hmac_sha256(timestamp + "." + body, webhook_secret)>

{ "event": "invoice.paid", "sent_at": "…", "data": { …factura… } }

Verificare în PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $_SERVER['HTTP_X_DEBILL_TIMESTAMP'] . '.' . $body, $secret);
if (! hash_equals($expected, $_SERVER['HTTP_X_DEBILL_SIGNATURE'])) {
    http_response_code(401); exit;
}