Documentație API

API REST pentru integrarea QuickInvoice cu aplicații externe: emite facturi, citește clienți și produse, primește webhooks semnate. Base URL: https://quickinvoice.ro/api/v1

Introducere

Toate cererile folosesc JSON și sunt izolate pe firma căreia îi aparține cheia API. Rate limit: 120 requesturi/minut per cheie. Cheile se generează din Dashboard → Setări → API & Integrări.

Autentificare

Trimite cheia (format qi_live_…) în oricare dintre headere:

Authorization: Bearer qi_live_...
X-Api-Key: qi_live_...

# Test conexiune
curl https://quickinvoice.ro/api/v1/ping -H "X-Api-Key: qi_live_..."
# → { "ok": true, "company": "SC Exemplu SRL", "taxCode": "RO12345678", "apiVersion": "v1" }

Facturi

GET /invoices · GET /invoices/:id · POST /invoices · GET /invoices/:id/pdf

La listare accepți: status (DRAFT, SENT, VIEWED, PAID, PARTIAL, OVERDUE, CANCELED), type (INVOICE, PROFORMA, DELIVERY_NOTE), customerId, search, dateFrom/dateTo, page, limit (max 100).

# Emite o factură (unitPrice = preț NET; TVA se calculează din taxRate)
curl -X POST https://quickinvoice.ro/api/v1/invoices \
  -H "X-Api-Key: qi_live_..." -H "Content-Type: application/json" \
  -d '{
    "customerName": "SC Exemplu SRL",
    "customerCIF": "RO12345678",
    "customerEmail": "client@exemplu.ro",
    "items": [
      { "description": "Servicii web", "quantity": 1, "unitPrice": 500, "taxRate": 21 }
    ]
  }'

Dacă nu trimiți o serie, se folosește seria default a firmei. Clientul se creează/actualizează automat după telefon. Descarcă PDF-ul cu GET /invoices/:id/pdf.

Clienți

GET /customers?search=&limit=&offset= · GET /customers/:id · POST /customers (telefon obligatoriu).

Produse

GET /products?search=&categoryId=&type= (PRODUCT sau SERVICE) · GET /products/:id. Read-only în v1.

Webhooks

Primești un POST JSON de fiecare dată când se produce un eveniment. Adaugi endpoint-urile din Dashboard → Setări → API & Integrări → Webhooks. Evenimente disponibile:

invoice.created, invoice.paid, invoice.overdue, customer.created, payment.received.

POST <url-ul tău>
X-QuickInvoice-Event: invoice.created
X-QuickInvoice-Signature: sha256=<hmac>

{
  "event": "invoice.created",
  "createdAt": "2026-07-05T10:00:00.000Z",
  "data": {
    "invoiceId": "…", "invoiceNumber": "FACT-2026-0001",
    "total": 266.20, "currency": "RON", "status": "SENT"
  }
}

Verifică semnătura: calculează HMAC-SHA256 peste corpul brut al cererii cu secretul webhook-ului (whsec_…) și compară cu header-ul X-QuickInvoice-Signature. Un endpoint care eșuează repetat se dezactivează automat.

// Node.js — verificare semnătură
const crypto = require('crypto');
const expected = 'sha256=' + crypto.createHmac('sha256', WHSEC)
  .update(rawBody).digest('hex');
const valid = expected === req.headers['x-quickinvoice-signature'];

Zapier

Cel mai simplu, fără aplicație de instalat: creează un Zap cu trigger „Webhooks by Zapier → Catch Hook", copiază URL-ul generat și adaugă-l ca webhook în QuickInvoice (alegi evenimentul). De acum fiecare factură/plată pornește Zap-ul. Poți mapa câmpurile din data în orice acțiune (Google Sheets, email, CRM etc.).

Ca alternativă de polling, Zapier poate interoga periodic GET https://quickinvoice.ro/api/v1/invoices?limit=… și deduplica după id.

Make (Integromat)

În Make adaugă modulul „Webhooks → Custom webhook", copiază adresa și pune-o ca webhook în QuickInvoice. Scenariul pornește instant la fiecare eveniment, cu tot payload-ul disponibil pentru pașii următori.

WooCommerce

Instalează pluginul oficial QuickInvoice for WooCommerce, pune cheia API în WooCommerce → QuickInvoice și facturile se emit automat la fiecare comandă plătită, cu descărcare PDF din pagina comenzii și CUI preluat pentru B2B.

Shopify

Fără aplicație de instalat: în Shopify Admin → Settings → Notifications → Webhooks adaugi un webhook Order payment (JSON) către:

https://quickinvoice.ro/api/v1/webhooks/shopify?key=qi_live_...

Factura se emite automat la fiecare comandă plătită, race-safe, fără duplicate.

Erori

Format standard, coduri uzuale:

400 cerere invalidă · 401 cheie lipsă/invalidă/revocată · 404 resursă inexistentă · 429 rate limit depășit.