API

Adresa de bazăCopiază linkul

Toate cererile pleacă spre https://api.brivio.ro. Răspunsurile sunt JSON, iar erorile respectă un contract unic: cod, mesaj și, unde se aplică, lista câmpurilor invalide.

Domeniul acoperitCopiază linkul

Endpoint-urile acoperă documentele de vânzare, partenerii, catalogul și stocul. Spațiile (/spaces) grupează domeniile, site-urile și aplicațiile unui proiect și se pot administra cu o cheie API; transferurile de spații (/space-transfers) sunt doar de citire, pentru că mutarea unui spațiu la altă organizație cere o persoană în aplicație, cu al doilea factor de autentificare. Operațiunile contabile nu sunt expuse la scriere: notele se generează din documente, iar o cale directă de scriere ar putea produce înregistrări fără document sursă.

Abonați la newsletter (dublă confirmare)Copiază linkul

POST /v1/marketing/subscribers permite serverului din spatele unui formular public (subsolul unui site, o pagină de prezentare) să adauge o persoană la newsletterul organizației tale. Brivio trimite emailul de confirmare, găzduiește pagina de confirmare și păstrează dovada consimțământului; persoana devine abonat abia după ce confirmă.

Cheia are nevoie de permisiunea marketing_subscribers:write. Aceasta este independentă și nu este inclusă în marketing:write, astfel încât o cheie aflată pe serverul unui formular public poate adăuga abonați, dar nu poate trimite campanii. Antetul opțional Idempotency-Key este respectat (reluare timp de 24 de ore).

Corpul cererii:

• email — obligatoriu, maximum 320 de caractere, transformat de server în litere mici.
• name — opțional, maximum 200 de caractere.
• locale — ro sau en, implicit ro; limba emailului și a paginilor de confirmare.
• source — opțional, maximum 120 de caractere; locul în care se află formularul, pentru raportările tale.
• redirect_url — URL https opțional; după o confirmare reușită, persoana este trimisă acolo (303) cu ?status=confirmed.
• consent — obligatoriu, dovada pe care art. 7 alin. (1) din GDPR o cere operatorului:
  • text_version — obligatoriu, 1–64 de caractere, versiunea textului de consimțământ pe care l-a văzut persoana;
  • text — opțional, maximum 2000 de caractere, păstrat doar ca hash SHA-256;
  • ip — opțional, IP-ul utilizatorului final (nu al serverului tău), păstrat doar ca hash cu sare;
  • user_agent — opțional, trunchiat la 300 de caractere.

Brivio păstrează hash-uri, nu IP-ul și textul în clar: sunt suficiente pentru a dovedi ulterior ce text a acceptat o anumită cerere, fără a stoca mai multe date personale decât cere dovada.

Răspunsurile folosesc plicul obișnuit { data, error }, cu un obiect MarketingSubscriber:

• 201 — a fost creat un abonat nou, cu starea pending, și s-a trimis emailul de confirmare.
• 200 — adresa este deja cunoscută în organizația ta. Apelul este idempotent per adresă: starea curentă este întoarsă neschimbată, sau confirmarea este retrimisă dacă abonatul este încă pending și a trecut intervalul de așteptare, sau o adresă dezabonată (unsubscribed) revine la pending. confirmation_sent îți spune dacă apelul acesta a trimis un email.
• 422 VALIDATION_ERROR, 401, 403 SCOPE_REQUIRED, 429 RATE_LIMITED.

Starea trece prin pending → subscribed → unsubscribed. Linkul de confirmare deschide o pagină cu un buton: simpla deschidere a linkului (GET) nu modifică nimic, pentru că scanerele de securitate ale serverelor de email urmează toate linkurile; apăsarea butonului (POST) confirmă. Linkul este semnat, de unică folosință și valabil 24 de ore. Fiecare abonat primește și unsubscribe_url, un link de dezabonare dintr-un clic (RFC 8058) care funcționează atât din butonul de dezabonare al clientului de email, cât și din browser.

Limite: 600 de cereri pe oră per organizație și cel mult un email de confirmare la 10 minute pentru aceeași adresă.

curl https://api.brivio.ro/v1/marketing/subscribers \
	-H "Authorization: Bearer $BRIVIO_API_KEY" \
	-H "Content-Type: application/json" \
	-H "Idempotency-Key: 6f1c2e4a-newsletter-footer" \
	-d '{
		"email": "ana@example.ro",
		"name": "Ana",
		"locale": "ro",
		"source": "example.ro/footer",
		"redirect_url": "https://example.ro/newsletter/confirmat",
		"consent": { "text_version": "2026-10-05", "text": "Sunt de acord să primesc newsletterul lunar.", "ip": "203.0.113.7" }
	}'

const subscriber = await brivio.marketing.createSubscriber({
	email: "ana@example.ro",
	name: "Ana",
	locale: "ro",
	source: "example.ro/footer",
	consent: { text_version: "2026-10-05", text: consentText, ip: request.ip },
});
// subscriber.status rămâne "pending" până când Ana confirmă

$subscriber = $brivio->createMarketingSubscriber([
		'email' => 'ana@example.ro',
		'locale' => 'ro',
		'source' => 'example.ro/footer',
		'consent' => ['text_version' => '2026-10-05', 'ip' => $_SERVER['REMOTE_ADDR']],
]);

Referința completăCopiază linkul

Fiecare operațiune, cu forma cererii, răspunsurile și exemple de cod, este generată din documentul OpenAPI la /reference. Același document stă la baza SDK-urilor TypeScript, PHP, Python, Go, Java și .NET, deci ce citești acolo este exact ce apelează SDK-ul.