API pentru dezvoltatori
Trimite documentele din ERP și primește codul UIT înapoi. Pe Pro și Enterprise.
Începe în cinci pași
- În aplicație, la Setări → API și webhook, creează o cheie de test (
rk_test_…). Cheia apare o singură dată. - Trimite documentele unui transport la
POST /v1/dossiers. Le citim în fundal. - Când transportul are întrebări, primești webhookul
dossier.needs_review. Răspunzi cuPOST /v1/dossiers/{id}/checks/{checkId}/resolve. - Pregătești declarația cu
POST /v1/dossiers/{id}/declarationsși o trimiți cuPOST /v1/declarations/{id}/submit. - Codul vine în webhookul
declaration.acceptedsau cuGET /v1/uit/{uit}.
curl https://api.larampa.ro/v1/dossiers \ -H "Authorization: Bearer rk_test_…" \ -H "Idempotency-Key: 4f7d2c1e-erp-00144" \ -F "externalRef=ERP-00144" \ -F "files=@dvi-144.pdf" \ -F "files=@factura-2026-0912.pdf" \ -F "files=@cmr-0047781.pdf"
Chei și medii
- Trimite cheia în antet:
Authorization: Bearer rk_live_…. Nu o pune în aplicații mobile sau în pagini web. - Cheile
rk_test_trimit declarațiile la mediul TEST ANAF: codurile primite nu sunt valabile pe drum și nu se numără în plan. - Fiecare cheie are drepturi (de exemplu
dossiers:write,declarations:submit,uit:read,webhooks:manage) și poate fi limitată la anumite firme. - O cheie limitată la firme nu administrează webhookuri: ele primesc evenimentele tuturor firmelor.
- O cheie
rk_test_lucrează doar cu transporturile create cu o cheie de test. - „Rotește” face o cheie nouă cu aceleași drepturi; cea veche mai merge 24 de ore. „Revocă” o oprește în cel mult 5 secunde.
- Tot ce face o cheie intră în jurnalul contului, pe numele cheii.
Idempotență
- Orice POST care creează sau trimite cere antetul
Idempotency-Key(de exemplu un UUID). - Aceeași cheie și același corp întorc același răspuns timp de 24 de ore, cu antetul
Idempotent-Replayed: true. - Aceeași cheie cu alt corp primește 422 IDEMPOTENCY_KEY_REUSED.
- Dacă prima cerere încă rulează, a doua primește 409 IDEMPOTENCY_IN_PROGRESS: reîncearcă după câteva secunde.
Limite
Pro: 120 de cereri pe minut pentru fiecare cheie; Enterprise: după contract. Fiecare răspuns are RateLimit-Limit, RateLimit-Remaining și RateLimit-Reset; peste limită primești 429 cu Retry-After.
Erori
- Erorile au forma
{ "error": { "code": "…", "message_ro": "…" }, "requestId": "…" }. - Codul (de exemplu INVALID_API_KEY, INSUFFICIENT_SCOPE, VALIDATION_ERROR, UIT_EXISTS) rămâne același; mesajul e pentru oameni.
- Trimite-ne requestId când ceri ajutor.
Webhookuri
Adaugă o adresă https publică (nu acceptăm localhost sau rețele interne) și alege evenimentele. Secretul de semnare apare o singură dată.
- Evenimente: dossier.needs_review, dossier.ready, declaration.submitted, declaration.accepted, declaration.rejected, uit.expired, partner.inactive.
- Răspunde cu un cod 2xx în 10 secunde. Altfel reîncercăm după 1 minut, 5 minute, 30 de minute, 2 ore, 6 ore și 15 ore (aproape 24 de ore).
- După 50 de livrări eșuate la rând oprim webhookul și anunțăm administratorii. Îl pornești din Setări; livrările ratate le retrimiți din jurnal.
- Câmpul id (și antetul
LaRampa-Event-Id) e același la retrimitere: folosește-l ca să nu procesezi de două ori.
Semnătura
Antetul LaRampa-Signature: t=<secunde>,v1=<hex> conține HMAC-SHA256 cu secretul webhookului, peste t + "." + corpul cererii. Respinge o semnătură mai veche de 5 minute.
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: corpul cererii exact cum a sosit (nu JSON-ul reparsat)
function verify(secret, rawBody, header) {
const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')))
const t = Number(parts.t)
if (Math.abs(Date.now() / 1000 - t) > 300) return false // mai vechi de 5 minute
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest()
const given = Buffer.from(parts.v1, 'hex')
return given.length === expected.length && timingSafeEqual(given, expected)
}import hmac, hashlib, time
def verify(secret: str, raw_body: bytes, header: str) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
t = int(parts["t"])
if abs(time.time() - t) > 300:
return False
mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(mac, parts["v1"])Exemplu de eveniment
{
"id": "0196f1b2-…",
"type": "declaration.accepted",
"created": "2026-11-12T08:14:05.120Z",
"livemode": true,
"data": {
"declaration": { "id": "…", "dossierId": "…", "environment": "prod" },
"uit": { "id": "…", "uit": "4T8KZ2MQ9XR7BL3W", "validFrom": "2026-11-12", "expiresAt": "2026-11-16T22:00:00.000Z", "vehiclePlate": "B123RMP" }
}
}Referință
Specificația completă OpenAPI 3: /v1/openapi.json (pe api.larampa.ro). Toate rutele de mai jos cer cheia, în afară de lista drepturilor.
Transporturi
GET/v1/dossiers
Lista transporturilor, cele mai noi primele
POST/v1/dossiers
Creează un transport din documente
multipart/form-data: files (1 – 20 fișiere PDF, JPG, PNG, HEIC, XML; 20 MB fiecare), firmId (opțional: firma; implicit prima firmă a cheii), externalRef (opțional: numărul din programul tău, unic în cont). Documentele se citesc în fundal; urmărește transportul cu GET sau cu webhookul dossier.needs_review. Cere Idempotency-Key.
GET/v1/dossiers/{id}
Un transport, cu documentele și verificările deschise
Verificări
GET/v1/dossiers/{id}/checks
Verificările unui transport (deschise; toate cu all=true)
POST/v1/dossiers/{id}/checks/{checkId}/resolve
Răspunde la o verificare
Alege una din options (câmpul id); pentru „Alt număr / Alt cod” trimite și value. Verificările rulează din nou; transportul devine ready când nu mai are întrebări.
PATCH/v1/dossiers/{id}/fields/{key}
Corectează un câmp al transportului
Cheile câmpurilor sunt cele din catalogul de câmpuri (de exemplu transport.date în formatul ZZ.LL.AAAA, transport.plate). Modificarea intră în jurnal ca făcută de cheia API.
Declarații
GET/v1/declarations/{id}
O declarație: starea, erorile de validare
POST/v1/declarations/{id}/submit
Trimite declarația la ANAF
Cere Idempotency-Key: aceeași cheie nu trimite de două ori. Răspunsul 202 are trimiterea în pending; codul UIT vine prin webhookul declaration.accepted sau cu GET /v1/submissions/{id}. 409 UIT_EXISTS cât timp declarația are un cod valabil. 402 FREE_LIMIT_REACHED când un cont gratuit și-a folosit transporturile lunii (cheia e eliberată: după alegerea unui plan, aceeași cerere cu aceeași cheie trece). 409 FREE_TIER_CUI_TAKEN când firma folosește gratuitul în alt cont; 409 FREE_TIER_OVER_CAPS când contul gratuit are mai multe firme sau persoane decât include gratuitul.
POST/v1/dossiers/{id}/declarations
Pregătește și validează declarația unui transport gata
Construiește declarația e-Transport (XML v2 implicit, v1 dacă firma o cere) și o validează. Cu o cheie rk_test_ declarația merge la mediul TEST ANAF, doar pentru transporturile create cu o cheie de test (altfel 409 ENVIRONMENT_MISMATCH). Se poate repeta: o declarație trimisă nu se mai schimbă.
GET/v1/submissions/{id}
Starea unei trimiteri (codul UIT doar după ok)
Coduri UIT
GET/v1/uit
Codurile UIT, cele mai noi primele (mediul cheii)
GET/v1/uit/{uit}
Un cod UIT: valabilitatea, vehiculul, transportul
POST/v1/uit/{uit}/driver-sms
Trimite codul șoferului prin SMS
Un SMS cu codul și linkul paginii șoferului (fără cont). Cere Idempotency-Key.
Parteneri și produse
GET/v1/partners
Partenerii, cu starea ANAF și VIES
POST/v1/partners
Adaugă un partener (verificat la ANAF / VIES)
GET/v1/partners/{id}
Un partener
PATCH/v1/partners/{id}
Modifică un partener
GET/v1/products
Produsele cu codurile NC
POST/v1/products
Adaugă un produs cu codul NC confirmat
PATCH/v1/products/{id}
Modifică un produs
Calculator
POST/v1/calculator
Trebuie cod UIT? Același motor ca în aplicație
Webhookuri
POST/v1/webhook-deliveries/{id}/redeliver
Retrimite o livrare (același id de eveniment)
GET/v1/webhooks
Webhookurile contului
POST/v1/webhooks
Adaugă un webhook
Adresa trebuie să fie https și publică (nu acceptăm localhost sau rețele interne). Secretul de semnare apare o singură dată, în răspuns.
PATCH/v1/webhooks/{id}
Modifică un webhook (status active îl pornește din nou)
DELETE/v1/webhooks/{id}
Șterge un webhook
GET/v1/webhooks/{id}/deliveries
Jurnalul livrărilor unui webhook (ultimele 50)
POST/v1/webhooks/{id}/test
Trimite un eveniment de test (webhook.test)
Chei API
GET/v1/scopes
Drepturile pe care le poate avea o cheie