API pentru parteneri

Pe scurt

API-ul xDomenii permite registrarilor și firmelor de găzduire să ofere clienților lor vânzarea domeniilor pe marketplace-ul xDomenii.ro, direct din panoul propriu. Pentru WHMCS există un modul gata făcut, descărcabil din Cont → Integrări. Pentru alte platforme folosiți API-ul descris mai jos.

Principii:

• Contul clientului, banii clientului. Fiecare client își conectează propriul cont xDomenii, prin acord explicit. Banii din vânzare ajung la el prin Stripe, iar factura de comision e emisă pe numele lui.
• Partenerul nu vede date sensibile. Prin API nu se pot citi parole, plăți, date de facturare sau datele de contact ale cumpărătorilor și nu se pot accepta oferte în numele clientului.
• Verificarea proprietății. Partenerii aprobați de echipa xDomenii confirmă ei că domeniul aparține clientului (fără înregistrare DNS). Până la aprobare, se folosește înregistrarea TXT obișnuită.

Adresa de bază: https://xdomenii.ro/api/v1. Toate răspunsurile sunt JSON, în UTF-8.

Comisionul de parteneriat

Partenerii aprobați primesc 20% din comisionul xDomenii (fără TVA) pentru fiecare domeniu vândut de un client listat prin integrarea lor. La comisionul standard de 10%, înseamnă aproximativ 2% din prețul de vânzare, pentru vânzări pe care altfel nu le-ați monetiza.

Termenii sunt stabiliți printr-un contract de parteneriat acceptat electronic din cont, cu PDF descărcabil. Pentru volume mari, termenii se pot negocia; orice modificare intră în vigoare doar după acceptarea voastră.

Obținerea cheilor

1. Creați un cont pe xDomenii.ro și deschideți Cont → Integrări.
2. Completați numele firmei, site-ul și adresele de întoarcere (unde revin clienții după conectarea contului).
3. Primiți o cheie publică (xdp_...) și un secret (xds_...). Secretul se afișează o singură dată; dacă îl pierdeți, îl regenerați din aceeași pagină.
4. Echipa xDomenii verifică firma și aprobă integrarea. Până atunci API-ul funcționează complet, doar că domeniile se verifică prin DNS.

Autentificare

Fiecare cerere se semnează cu secretul (HMAC-SHA256). Secretul nu se trimite niciodată prin rețea.

Textul semnat are cinci rânduri, despărțite prin \n:

timestamp
nonce
METODA            (GET, POST, PATCH, DELETE)
calea?query       (ex. /api/v1/domains/exemplu.ro?delete=1)
sha256(corp)      (hex; pentru cereri fără corp: sha256 al șirului gol)

Exemplu în PHP:

$timestamp = time();
$nonce = bin2hex(random_bytes(12));
$body = json_encode($data);   // '' pentru GET și DELETE
$signature = hash_hmac('sha256', implode("\n", [$timestamp, $nonce, 'POST', '/api/v1/domains', hash('sha256', $body)]), $secret);

Același nonce nu este acceptat de două ori (protecție la reluarea cererilor interceptate). Limita este de 300 de cereri pe minut per partener; la depășire primiți 429 cu antetul Retry-After.

Conectarea contului unui client

Fluxul seamănă cu „Conectează-te cu Google” (OAuth cu cod de autorizare):

1. Creați cererea de conectare: POST /connect cu redirect_uri (una dintre adresele declarate), state (valoare aleatoare, păstrată în sesiunea voastră) și external_ref (ID-ul clientului în sistemul vostru). Răspunsul conține url.
2. Trimiteți clientul la url. Acolo se autentifică (sau își face cont) și aprobă accesul.
3. Clientul revine la redirect_uri cu ?code=...&state=.... Verificați că state este cel trimis. Dacă refuză, primiți ?error=access_denied.
4. Schimbați codul pe token: POST /connect/token cu code. Codul expiră în 10 minute și se folosește o singură dată. Păstrați token-ul criptat; îl trimiteți în antetul X-Xd-Client.

POST /connect
{"redirect_uri": "https://clienti.firma.ro/index.php?m=xdomenii&action=callback", "state": "f3a1...", "external_ref": "1042"}

201 {"id": "9d2c...", "url": "https://xdomenii.ro/conectare-aplicatie/9d2c...", "expires_at": "2026-10-29T10:30:00+00:00"}

POST /connect/token
{"code": "Qm9..."}

201 {"token": "xdc_...", "connection": {"user": {"name": "Maria Ionescu", "email": "maria@exemplu.ro", "payouts_ready": false}, "external_ref": "1042", "connected_at": "..."}}

payouts_ready: false înseamnă că clientul nu și-a conectat încă plățile (Stripe). Domeniile se pot lista, dar vânzările așteaptă până la conectare; afișați-i un îndemn spre connection.urls.payments.

Clientul poate retrage accesul oricând, din Cont → Integrări. După aceea, cererile cu token-ul lui primesc 401 connection_invalid.

Endpointuri

Adăugarea unui domeniu la vânzare

POST /domains
{
  "domain": "exemplu.ro",
  "sale_type": "fixed",
  "price": 1500,
  "currency": "EUR",
  "is_negotiable": true,
  "min_offer": 800,
  "category": "afaceri",
  "description": {"ro": "Domeniu scurt, ușor de reținut.", "en": "Short, memorable domain."}
}

• sale_type: fixed (preț fix; cumpărătorul poate plăti direct), offers (doar oferte) sau not_for_sale. Licitațiile se configurează din contul xDomenii.
• price este obligatoriu pentru fixed; currency: una dintre valorile din /meta.
• attest (implicit true): dacă integrarea e aprobată, confirmați proprietatea și domeniul se listează imediat.

Răspunsul (201 la adăugare, 200 dacă domeniul exista deja în contul clientului) conține domeniul și rezultatul confirmării:

{
  "domain": {
    "name": "exemplu.ro",
    "status": "verified",
    "verification": {"verified": true, "method": "partner", "txt_host": "exemplu.ro", "txt_value": "xdomenii-verify=...", "checked_at": null},
    "sale": {"type": "fixed", "price": 1500, "min_offer": 800, "currency": "EUR", "negotiable": true, "price_label": "€1.500", "category": "afaceri"},
    "listed": true,
    "offers": {"open": 0, "best": null},
    "views": 0,
    "urls": {"public": "https://xdomenii.ro/domenii/exemplu.ro", "manage": "...", "offers": "..."}
  },
  "attestation": "verified"
}

Valori posibile pentru attestation: verified, not_allowed (integrarea nu e aprobată încă), conflict (domeniul e deja verificat de alt cont; decide înregistrarea DNS), blocked (restricționat prin moderare). Dacă nu e verified, arătați clientului verification.txt_host și verification.txt_value și apelați POST /domains/{domeniu}/verify după ce adaugă înregistrarea TXT.

Reconfirmarea zilnică

O dată pe zi, trimiteți pentru fiecare client conectat lista domeniilor care sunt încă ale lui la voi:

POST /attestations
{"domains": ["exemplu.ro", "alt-domeniu.com"]}

200 {"attested": ["exemplu.ro"], "ignored": ["alt-domeniu.com"]}

Domeniile confirmate de voi și nereconfirmate timp de 3 zile (transferate, expirate, modul dezinstalat) se retrag automat de la vânzare, cu excepția celor care au între timp o înregistrare TXT validă.

Webhookuri

Dacă declarați o adresă webhook, primiți notificări POST (JSON) pentru domeniile adăugate prin voi:

{"id": "4f1c...", "event": "offer.received", "created_at": "...", "data": {"external_ref": "1042", "domain": {"name": "exemplu.ro", "...": "..."}, "offer": {"amount": 900, "currency": "EUR", "url": "..."}}}

Notificările sunt semnate cu același algoritm ca cererile voastre: antetele X-Xd-Timestamp, X-Xd-Nonce (egal cu id), X-Xd-Signature, plus X-Xd-Event. Verificați semnătura cu secretul vostru și calea adresei webhook. Răspundeți cu un cod 2xx; altfel reîncercăm de încă 4 ori (după 1, 5, 15 și 60 de minute).

Erori

Erorile au forma:

{"error": {"code": "connection_invalid", "message": "Contul xDomenii nu mai este conectat. Conectează-l din nou."}}

Erorile de validare (422) au forma standard: {"message": "...", "errors": {"price": ["..."]}}.

Modulul WHMCS

Modulul face tot ce e descris mai sus, fără programare:

1. Descărcați arhiva din Cont → Integrări (adresa API și cheia sunt deja completate).
2. Copiați modules/addons/xdomenii în rădăcina WHMCS.
3. Configurare → Module suplimentare (Addon Modules) → xDomenii → Activare, completați secretul și acordați acces grupurilor de administratori.
4. În pagina modulului (Addons → xDomenii) găsiți adresa de întoarcere și adresa webhook; declarați-le în Cont → Integrări.

Clienții găsesc „Vinde pe xDomenii” în meniul Domenii și pe pagina fiecărui domeniu. Sincronizarea zilnică rulează odată cu cronul WHMCS. Cerințe: WHMCS 8 sau mai nou, PHP 7.4 sau mai nou, extensia cURL.