API pentru dezvoltatori

Cum începi

Autentificare

Toate cererile merg pe HTTPS și poartă tokenul într-un antet. Nu există chei în query string: un URL ajunge în logurile serverului, în istoricul browserului și în antetul Referer, iar un token ajuns acolo trebuie considerat compromis.

curl https://executat.ro/api/v1/cont \
  -H "Authorization: Bearer exec_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Dacă librăria ta face antetul Authorization incomod, acceptăm și X-API-Key cu aceeași valoare.

Fluxul direct

Doi pași, și separarea este intenționată. Ofertarea nu scrie și nu debitează nimic, deci o poți apela oricât cât timp decizi; plasarea comenzii este locul unde se mișcă banii.

Folosește-l când ai deja un birou preferat sau când vrei un preț ferm imediat. Dacă nu ai, licitația dă de regulă un preț mai bun: pentru majoritatea birourilor tariful pe care îl vezi aici este plafonul legal, nu o ofertă a biroului.

1. Cere oferte

Competența teritorială este jumătatea grea a întrebării: un executor judecătoresc nu poate instrumenta oriunde. Trimite procedura și adresele, primești birourile care pot comunica legal actul acolo, cu prețul total al fiecăruia.

curl -X POST https://executat.ro/api/v1/oferte \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "serviciu": "somatie-de-plata",
    "adrese": [
      { "lat": 44.4268, "lng": 26.1025, "eticheta": "Calea Victoriei 1, București", "detalii": "ap. 12" },
      { "text": "Strada Memorandumului 28, Cluj-Napoca" }
    ]
  }'

{
  "serviciu": { "slug": "somatie-de-plata", "nume": "Notificare / somație", … },
  "adrese": [ { "eticheta": "…", "lat": 44.4268, "judet": "București", … } ],
  "total": 37,
  "creditDisponibilBani": 100000,
  "oferte": [
    {
      "executor": { "slug": "bej-exemplu", "birou": "BEJ Exemplu", "judet": "București", … },
      "sursaPret": "tarif",
      "onorariiBani": 24000,
      "deplasareBani": 5000,
      "subtotalBani": 29000,
      "tvaProcent": 21,
      "tvaBani": 6090,
      "totalBani": 35090,
      "acoperitDinCredit": true,
      "completa": true,
      "estimativ": false,
      "linii": [ … ]
    }
  ]
}

2. Plasează comanda

Iei executor.slug din oferta aleasă și îl trimiți înapoi. Prețul se recalculează aici — dacă trimiți un total, este ignorat. O sumă venită din cererea clientului este o sumă pe care clientul o controlează, iar aceasta ajunge pe o factură. Tu alegi care birou; cât costă biroul spunem noi.

curl -X POST https://executat.ro/api/v1/comenzi \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dosar-4471-notificare-1" \
  -d '{
    "serviciu": "somatie-de-plata",
    "executor": "bej-exemplu",
    "adrese": [
      { "lat": 44.4268, "lng": 26.1025, "eticheta": "Calea Victoriei 1, București", "detalii": "ap. 12" }
    ],
    "destinatar": {
      "tip": "persoana_juridica",
      "nume": "OMV PETROM SA",
      "cui": "RO1590082",
      "regCom": "J1997008302407",
      "telefon": "0212001111",
      "email": "contact@exemplu.ro",
      "adresa": "Str. Coralilor nr. 22, (PETROM CITY)",
      "localitate": "Sector 1 Mun. București",
      "judet": "MUNICIPIUL BUCUREȘTI",
      "codPostal": "13329",
      "sursa": "anaf"
    },
    "redactare": "client",
    "document": {
      "titlu": "Somație de plată",
      "numeFisier": "somatie-4471.pdf",
      "continut": "JVBERi0xLjcKMSAwIG9iago…"
    },
    "dosar": "4471/2026",
    "referinta": "CRM-88213",
    "mentiuni": "Destinatarul lucrează în schimbul de noapte."
  }'

HTTP/1.1 201 Created

{
  "comanda": {
    "referinta": "EXR-7K2M4Q",
    "stare": "noua",
    "executor": { "slug": "bej-exemplu", "birou": "BEJ Exemplu", "telefon": "…" },
    "pret": { "totalBani": 35090, "tvaBani": 6090, "sursa": "tarif", "estimativ": false },
    "plata": "credit",
    "document": {
      "titlu": "Somație de plată",
      "url": null,
      "fisiere": [
        {
          "numeFisier": "somatie-4471.pdf",
          "octeti": 84213,
          "sha256": "a1bd19bc44bc…",
          "semnatElectronic": true,
          "tipSemnatura": "ETSI.CAdES.detached",
          "nrSemnaturi": 1
        }
      ]
    },
    "referintaClient": "CRM-88213"
  },
  "creditRamasBani": 64910
}

referinta este identificatorul comenzii peste tot mai departe. referintaClient este al tău, întors ca atare: cine trimite o mie de acte are deja un număr de dosar pentru fiecare și trebuie să-și regăsească comanda după el, nu după al nostru.

Licitație: birourile trimit prețul

Fluxul implicit al platformei, și de obicei cel mai ieftin. Deschizi o comandă fără să numești un birou; trimitem cererea celor mai apropiate 10 birouri competente pentru toate adresele din cerere, ele răspund cu prețul lor, iar tu accepți una. Licitația rămâne deschisă 3 zile.

Motivul pentru care există: majoritatea birourilor nu au tarif publicat, iar suma pe care POST /oferte o întoarce pentru ele este sursaPret: "plafon_legal" — maximul permis de lege, nu un preț pe care l-a promis cineva. O ofertă din licitație este.

1. Deschide licitația

Aceleași câmpuri ca la comanda directă, fără executor. Nu se debitează nimic aici și nu se verifică soldul — o licitație nu costă nimic până accepți.

curl -X POST https://executat.ro/api/v1/licitatii \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: dosar-4471-licitatie" \
  -d '{
    "serviciu": "somatie-de-plata",
    "adrese": [
      { "lat": 44.4268, "lng": 26.1025, "eticheta": "Calea Victoriei 1, București", "detalii": "ap. 12" }
    ],
    "destinatar": { "tip": "persoana_juridica", "nume": "OMV PETROM SA", "cui": "RO1590082", … },
    "redactare": "client",
    "document": { "titlu": "Somație", "numeFisier": "somatie.pdf", "continut": "JVBERi0xLjcK…" },
    "referinta": "CRM-88213"
  }'

HTTP/1.1 201 Created

{
  "comanda": {
    "referinta": "EXR-7K2M4Q",
    "stare": "licitatie",
    "mod": "licitatie",
    "executor": null,
    "nrPagini": 3,
    "pret": { "totalBani": 0, "sursa": "licitatie" },
    "plata": "in_asteptare",
    "licitatie": { "expiraLa": "2026-09-06T12:00:00.000Z", "nrInvitatii": 10, "nrOferte": 0 }
  },
  "invitate": 10,
  "maxInvitatii": 10,
  "zileLicitatie": 3,
  "avertisment": null
}

executor este null până accepți o ofertă, iar pret.totalBani este 0 — nu pentru că ar fi gratis, ci pentru că încă nu există un preț. Dacă invitate este 0, avertisment spune de ce: niciun birou nu e competent pentru toate adresele, deci comanda nu va primi oferte oricât ai aștepta.

La licitație, redactare: "client" cere actul ca document.continut, nu ca URL: birourile ofertează pe numărul de pagini, iar dintr-un link nu îl putem citi. Vezi actul.

2. Citește ofertele

Cele mai ieftine întâi. Ofertele retrase nu apar — nu mai pot fi acceptate, deci a le lista ar produce doar un 409 mai târziu.

curl https://executat.ro/api/v1/comenzi/EXR-7K2M4Q/oferte -H "Authorization: Bearer $TOKEN"

{
  "referinta": "EXR-7K2M4Q",
  "stare": "licitatie",
  "expiraLa": "2026-09-06T12:00:00.000Z",
  "invitate": 10,
  "oferte": [
    {
      "ofertaId": "6f1c…-…-…",
      "totalBani": 28500,
      "pretBani": 23554,
      "tvaProcent": 21,
      "termenZile": 3,
      "mesaj": "Comunicăm în 48h dacă destinatarul e la adresă.",
      "creatLa": "2026-09-04T08:11:02.000Z",
      "executor": { "slug": "bej-exemplu", "birou": "BEJ Exemplu", "judet": "București", "distantaKm": 2.4 }
    }
  ]
}

3. Acceptă o ofertă

Aici se mișcă banii. Într-o singură tranzacție comanda primește preț, birou și plată, iar actul ajunge la biroul câștigător — și numai la el. Celelalte birouri află doar că licitația s-a încheiat.

curl -X POST https://executat.ro/api/v1/comenzi/EXR-7K2M4Q/accepta \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "ofertaId": "6f1c…-…-…" }'

{
  "comanda": { "referinta": "EXR-7K2M4Q", "stare": "acceptata", "executor": { "birou": "BEJ Exemplu", … },
               "pret": { "totalBani": 28500, "sursa": "oferta" }, "plata": "credit" },
  "birou": "BEJ Exemplu",
  "totalBani": 28500,
  "creditRamasBani": 71500
}

Nu are nevoie de Idempotency-Key: oferta acceptată este înregistrată pe comandă, deci o a doua încercare cade pe o comandă care nu mai este în licitatie și primește 409, nu o a doua debitare.

Destinatarul actului

Un obiect, nu o linie de text. Executorul trebuie să identifice partea, să o poată contacta și să găsească ușa, iar un nume singur lăsa restul în seama biroului. Toate câmpurile de mai jos sunt obligatorii, în afară de judet, codPostal și — la persoană fizică — cui / regCom.

{
  "ok": true,
  "firma": {
    "cui": "1590082",
    "denumire": "OMV PETROM SA",
    "nrRegCom": "J1997008302407",
    "formaJuridica": "SOCIETATE COMERCIALĂ PE ACŢIUNI",
    "stareInregistrare": "INREGISTRAT din data 23.10.1997",
    "radiata": false,
    "adresa": "Str. Coralilor, nr. 22, (PETROM CITY)",
    "localitate": "Sector 1 Mun. Bucureşti",
    "judet": "MUNICIPIUL BUCUREŞTI",
    "codPostal": "13329",
    "platitorTva": true
  }
}

Actul semnat electronic

Când trimiți redactare: "client", actul trebuie să vină odată cu comanda. Două forme, ambele valide:

Idempotență

Credit, prețuri și anulări

Alimentarea creditului nu se face din API, intenționat: banii intră prin portal, unde se încasează cardul și se emite factura. Un endpoint care ar putea credita un sold ar fi un motiv mult mai interesant să furi un token.

Endpointuri

Baza: https://executat.ro/api/v1

Erori

Toate erorile au aceeași formă. Ramifică pe cod, nu pe mesaj: textul este scris pentru om și se poate schimba, codul nu.

{
  "eroare": {
    "cod": "credit_insuficient",
    "mesaj": "Creditul din cont nu acoperă această comandă. Alimentează contul și reia cererea.",
    "detalii": { "necesarBani": 35090, "disponibilBani": 12000, "lipsaBani": 23090 }
  }
}

Limite