Sari la conținut
e-Transport

API pentru dezvoltatori

Trimite documentele din ERP și primește codul UIT înapoi. Pe Pro și Enterprise.

Începe în cinci pași

  1. În aplicație, la Setări → API și webhook, creează o cheie de test (rk_test_…). Cheia apare o singură dată.
  2. Trimite documentele unui transport la POST /v1/dossiers. Le citim în fundal.
  3. Când transportul are întrebări, primești webhookul dossier.needs_review. Răspunzi cu POST /v1/dossiers/{id}/checks/{checkId}/resolve.
  4. Pregătești declarația cu POST /v1/dossiers/{id}/declarations și o trimiți cu POST /v1/declarations/{id}/submit.
  5. Codul vine în webhookul declaration.accepted sau cu GET /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

Idempotență

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

Webhookuri

Adaugă o adresă https publică (nu acceptăm localhost sau rețele interne) și alege evenimentele. Secretul de semnare apare o singură dată.

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