Clienți și produse
Agenda și catalogul firmei, legate de id-urile din programul tău.
Clienții
Agenda firmei: firme (după CUI) și persoane fizice (cu sau fără CNP). CUI-ul și CNP-ul se verifică după cifra de control. Pe o factură poți da un client din agendă (client_id) sau îl poți scrie direct; cu save_client, clientul scris pe factură intră și în agendă.
Modificarea unui client nu schimbă facturile emise: fiecare document își păstrează clientul de la emitere. Ștergerea îl scoate din agendă; documentele rămân neschimbate.
Sincronizarea cu ref
ref este id-ul tău pentru un client sau un produs, de exemplu id-ul din CRM sau codul din magazin. Îl dai la creare și cauți apoi după el:
GET /api/v1/companies/7/clients?ref=crm-118
GET /api/v1/companies/7/products?ref=sku-sup-1- Un client scris pe o factură, cu
refșisave_client, se potrivește cu cel din agendă după acelref, apoi după CUI sau CNP. - Un produs creat cu un
refcare există deja actualizează produsul existent: poți trimite catalogul tău întreg, la fiecare schimbare, fără dubluri.
Produsele
Catalogul firmei: produse și servicii, cu prețul (în moneda lui), unitatea, cota de TVA și codul. Pe o factură, o linie cu product_id își ia de aici datele lipsă; un preț în altă monedă decât factura se convertește la cursul BNR al zilei de emitere. Ștergerea scoate produsul din catalog (active: false); îl readuci cu PATCH și "active": true.
Referința
Lista clienților
GET /api/v1/companies/{company_id}/clients
Permisiune: clients:read.
Agenda firmei, cei mai noi primii.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
q | string | Caută în nume, CUI și email. |
cui | string | După CUI (cu sau fără RO). |
ref | string | După id-ul tău. |
limit | integer | Câte pe pagină, 1–100. Implicit 25. |
starting_after | string | next_cursor din pagina anterioară. |
Adaugă un client
POST /api/v1/companies/{company_id}/clients
Permisiune: clients:write.
CUI-ul și CNP-ul se verifică (cifra de control).
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
Corp: ClientInput, de exemplu.
{ "name": "Gamma Studio SRL", "cui": "RO33491260", "address": "Str. Lungă 4", "city": "Brașov", "county": "Brașov", "email": "office@gamma.ro", "ref": "crm-118" }Răspuns 201: Client.
Un client
GET /api/v1/companies/{company_id}/clients/{client_id}
Permisiune: clients:read.
Clientul.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
client_id în adresă | integer | Id-ul clientului. |
Răspuns 200: Client.
Modifică un client
PATCH /api/v1/companies/{company_id}/clients/{client_id}
Permisiune: clients:write.
Doar câmpurile trimise. Documentele emise își păstrează clientul de la emitere.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
client_id în adresă | integer | Id-ul clientului. |
Corp: ClientInput, de exemplu.
{ "email": "facturi@gamma.ro" }Răspuns 200: Client.
Șterge un client
DELETE /api/v1/companies/{company_id}/clients/{client_id}
Permisiune: clients:write.
Îl scoate din agendă; documentele îl păstrează.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
client_id în adresă | integer | Id-ul clientului. |
Răspuns 200: Deleted.
Lista produselor
GET /api/v1/companies/{company_id}/products
Permisiune: products:read.
Catalogul firmei, cele mai noi primele.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
q | string | Caută în denumire și cod. |
ref | string | După id-ul tău. |
active | boolean | false: cele șterse. Implicit cele din catalog. |
limit | integer | Câte pe pagină, 1–100. Implicit 25. |
starting_after | string | next_cursor din pagina anterioară. |
Adaugă un produs
POST /api/v1/companies/{company_id}/products
Permisiune: products:write.
Cu ref: dacă există deja un produs cu acest id al tău, îl actualizează.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
Corp: ProductInput, de exemplu.
{ "kind": "serviciu", "name": "Ore suport", "unit": "HUR", "price": 120, "vat_rate_id": 14, "ref": "sku-sup-1" }Răspuns 201: Product.
Un produs
GET /api/v1/companies/{company_id}/products/{product_id}
Permisiune: products:read.
Produsul.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
product_id în adresă | integer | Id-ul produsului. |
Răspuns 200: Product.
Modifică un produs
PATCH /api/v1/companies/{company_id}/products/{product_id}
Permisiune: products:write.
Doar câmpurile trimise.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
product_id în adresă | integer | Id-ul produsului. |
Corp: ProductInput, de exemplu.
{ "price": 135 }Răspuns 200: Product.
Scoate un produs din catalog
DELETE /api/v1/companies/{company_id}/products/{product_id}
Permisiune: products:write.
Rămâne pe documentele pe care apare; îl readuci cu active: true.
| Parametru | Tip | Ce este |
|---|---|---|
company_id în adresă | integer | Id-ul firmei. |
product_id în adresă | integer | Id-ul produsului. |
Răspuns 200: Deleted.
Obiectul ClientInput
Un client. Pentru e-Factura, o firmă din România are nevoie de CUI, localitate și județ.
| Câmp | Tip | Ce este |
|---|---|---|
kind | pj | pf | Firmă sau persoană fizică. Implicit pj. |
name | string | Denumirea sau numele. Obligatoriu. |
cui | string sau null | CUI-ul (cu sau fără RO); verificat. |
cnp | string sau null | CNP-ul unei persoane fizice; verificat. |
send_cnp | boolean | Transmite CNP-ul în e-Factura (altfel 13 zerouri). |
reg_com | string sau null | Registrul Comerțului. |
address | string sau null | Strada și numărul. |
city | string sau null | Localitatea; în București, sectorul. |
county | string sau null | Județul. |
country | string | Țara, ISO 3166-1. Implicit RO. |
postal_code | string sau null | Codul poștal. |
email | string sau null | Emailul (pentru trimiterea facturilor). |
phone | string sau null | Telefonul. |
contact_person | string sau null | Persoana de contact. |
notes | string sau null | Note. |
ref | string sau null | Id-ul tău pentru client; îl cauți cu ?ref=. |
Obiectul Client
Un client din agendă: id, object: "client" și câmpurile din ClientInput.
| Câmp | Tip | Ce este |
|---|---|---|
id | integer | Id-ul clientului. |
object | client | Mereu client. |
Obiectul ProductInput
Un produs sau serviciu din catalog.
| Câmp | Tip | Ce este |
|---|---|---|
kind | produs | serviciu | Produs sau serviciu. Implicit produs. |
code | string sau null | Codul. |
name | string | Denumirea. Obligatorie. |
description | string sau null | Descrierea. |
unit | string | Unitatea, cod UN/ECE. Implicit H87. |
price | number | Prețul. |
price_includes_vat | boolean | Prețul conține TVA. |
vat_rate_id | integer sau null | Cota de TVA a firmei. |
currency | string | Moneda prețului. Implicit RON. |
ref | string sau null | Id-ul tău pentru produs; îl cauți cu ?ref=. |
active | boolean | Doar la modificare: true îl readuce în catalog. |
Obiectul Product
Un produs: id, object: "product", câmpurile din ProductInput și:
| Câmp | Tip | Ce este |
|---|---|---|
id | integer | Id-ul produsului. |
object | product | Mereu product. |
vat_percent | number sau null | Procentul cotei. |
vat_category | string sau null | Categoria cotei. |
vat_label | string sau null | Eticheta cotei. |
active | boolean | În catalog (false după ștergere). |