KatalogBeta

Documentație API

API-ul REST v1 listează și creează oferte, exportă XML pentru e-Factura și înregistrează webhooks, ca să legi Katalog de ERP-ul sau CRM-ul tău. Cererile folosesc HTTPS, JSON și o cheie API.

Bază API: https://katalog.live/api/v1Chei API în zona de administrare

Introducere

Toate cererile merg prin HTTPS, iar corpurile cererilor și ale răspunsurilor sunt JSON (UTF-8), cu excepția exportului e-Factura, care poate returna XML. O cerere eșuată primește un cod HTTP de eroare (4xx sau 5xx) și un corp de forma { "success": false, "error": "..." }.

Exemplele de mai jos folosesc o cheie de exemplu. Înlocuiește-o cu cheia ta și nu o pune niciodată în cod public sau în adrese URL.

Limbaj pentru exemple:

Autentificare

Trimite cheia în antetul Authorization ca token Bearer (sau în antetul x-api-key). Cheile se creează, se rotesc și se revocă din zona de administrare. Cheia se afișează o singură dată, la creare; în baza de date se păstrează doar un hash. O cheie poate avea acces complet sau doar de citire; cererile de scriere cu o cheie de citire primesc 403.

Antet HTTP
Authorization: Bearer kat_live_sec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Listare oferte

GET/v1/quotes

Returnează ofertele organizației tale. Parametri opționali: status (draft, sent, viewed, accepted, rejected), cui (CUI-ul clientului), limit (implicit 50, maximum 100) și offset. Răspunsul conține total, limit, offset și lista data. Pentru o singură ofertă folosește GET /v1/quotes/{id}.

Cerere cURL
curl "https://katalog.live/api/v1/quotes?status=sent&limit=20" \
  -H "Authorization: Bearer kat_live_sec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Creare ofertă

POST/v1/quotes

Creează o ofertă în starea draft. Câmpuri obligatorii: client_cui și items (listă nevidă; fiecare linie are title, quantity, unit_price fără TVA și opțional vat_rate, implicit 21). Dacă CUI-ul nu corespunde unui client existent, datele firmei se caută în ANAF. Totalurile se calculează pe server, cu rotunjire la 2 zecimale.

Cerere (cURL)
curl -X POST https://katalog.live/api/v1/quotes \
  -H "Authorization: Bearer kat_live_sec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "client_cui": "RO34567890",
    "title": "Propunere servicii IT 2026",
    "currency": "RON",
    "payment_term_days": 30,
    "discount_type": "percentage",
    "discount_value": 5,
    "items": [
      { "title": "Dezvoltare platformă web", "quantity": 1, "unit_price": 8500, "vat_rate": 21 },
      { "title": "Abonament mentenanță", "quantity": 12, "unit_price": 450, "vat_rate": 21 }
    ]
  }'
Răspuns 201 (JSON)
{
  "id": "kat_quot_77289df1a0b3c4d5",
  "quote_number": "KAT-2026-0841",
  "status": "draft",
  "portal_url": "https://katalog.live/q/kat_quot_77289df1a0b3c4d5",
  "client": { "cui": "RO34567890", "name": "TECHSOLVENT SOLUTIONS S.R.L.", "is_vat_payer": true, "address": "Iași" },
  "subtotal_net": 13900,
  "discount_amount": 695,
  "taxable_amount": 13205,
  "vat_breakdown": [{ "rate": 21, "base": 13205, "vat_amount": 2773.05 }],
  "total_gross": 15978.05,
  "created_at": "2026-10-07T12:00:00Z"
}

Export e-Factura

POST/v1/quotes/{id}/export-efactura

Generează fișierul XML în formatul e-Factura (UBL 2.1, CIUS-RO) pentru o ofertă. Cu antetul Accept: application/xml primești direct fișierul; altfel primești un răspuns JSON care conține XML-ul. Validarea și transmiterea la ANAF se fac din factură, în aplicație.

Cerere cURL
curl -X POST https://katalog.live/api/v1/quotes/kat_quot_77289df1a0b3c4d5/export-efactura \
  -H "Authorization: Bearer kat_live_sec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Accept: application/xml" \
  -o efactura.xml

Webhooks

POST/v1/webhooks

Înregistrează o adresă HTTPS care să primească evenimente. Evenimentele disponibile sunt quote.viewed, quote.accepted și quote.rejected. La înregistrare primești un secret de semnare, afișat o singură dată: păstrează-l. GET /v1/webhooks listează webhook-urile înregistrate, fără secret.

Înregistrare webhook (cURL)
curl -X POST https://katalog.live/api/v1/webhooks \
  -H "Authorization: Bearer kat_live_sec_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://erp.compania-ta.ro/webhooks/katalog",
    "events": ["quote.accepted", "quote.viewed", "quote.rejected"]
  }'