@acteo/api 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## @acteo/api 0.4.0 (2026-10-31)
4
+
5
+ - Corectură: `verificaNotificare()` (și `verificaWebhookNotificare()`) citește cheia din headerul `X-Acteo-Key`, cel trimis acum de API. Până acum căuta doar `X-Verificrca-Key`, așa că notificările reale erau respinse cu `CHEIE_INVALIDA`. Headerul vechi e citit în continuare când lipsește cel nou. `HEADER_CHEIE_WEBHOOK` e acum `"x-acteo-key"`, iar `HEADER_EVENIMENT_WEBHOOK` e `"x-acteo-event"`.
6
+ - `verificaNotificare()` acceptă și evenimentele celorlalte servicii: `dosar.eveniment`, `dosar.termen`, `firma.schimbare`, `firma.dosar`, `marca.schimbare`, `marca.expira`, `asigurare.schimbare` și `termen.expira`, fiecare cu tipul lui.
7
+ - `acteo.auto.vin.decodeaza(vin)`: decodarea VIN.
8
+ - `acteo.auto.numere.verifica(numar)`: dacă un număr de înmatriculare e liber la DGPCI, cu un timeout de cel puțin 150 de secunde pentru această cerere.
9
+ - `acteo.auto.imagini.obtine()` și `asteapta()`: poza de studio a unei mașini.
10
+ - Răspunsurile 422 devin `EroareValidare`. `EroareServer` are `retryAfterMs`. Un 503 `OCUPAT` se reîncearcă după `Retry-After`. Un 5xx cu alt cod din partea API-ului nu se mai repetă la POST.
11
+
3
12
  ## @acteo/api 0.3.0 (2026-10-29)
4
13
 
5
14
  Pachetul `@verificrca/sdk` continuă sub numele `@acteo/api`, cu apelurile grupate pe domeniu și pe document. Vezi secțiunea „Vii de la @verificrca/sdk?” din README.
package/README.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  SDK-ul oficial Node.js și TypeScript pentru [API-ul Acteo](https://acteo.ro/api-acces). Cu el verifici din cod dacă o mașină are RCA valabil, ITP la zi, rovinietă plătită sau copie conformă ARR, după numărul de înmatriculare sau seria de șasiu (VIN). Datele vin din sursele oficiale: baza AIDA pentru asigurarea RCA, RAR pentru inspecția tehnică periodică, CNAIR pentru rovinietă și ARR pentru transportul rutier.
8
8
 
9
- Pe lângă verificările la cerere, SDK-ul gestionează vehiculele monitorizate din cont și citește webhook-urile trimise când un document se apropie de expirare. Dacă ai o firmă de leasing, rent-a-car sau curierat, un service auto ori pur și simplu o flotă, afli din timp ce RCA, ITP sau rovinietă expiră, înainte să vină amenda.
9
+ Pe lângă verificările la cerere, SDK-ul decodează serii de șasiu, verifică la DGPCI dacă un număr de înmatriculare e liber, aduce poze de studio ale mașinilor, gestionează vehiculele monitorizate din cont și citește webhook-urile trimise când un document se apropie de expirare. Dacă ai o firmă de leasing, rent-a-car sau curierat, un service auto ori pur și simplu o flotă, afli din timp ce RCA, ITP sau rovinietă expiră, înainte să vină amenda.
10
10
 
11
11
  > Ai nevoie de o cheie API. O generezi din [contul tău Acteo](https://app.acteo.ro/api/chei), după ce alegi un plan de pe [pagina API](https://acteo.ro/api-acces).
12
12
 
@@ -19,7 +19,7 @@ const rca = await acteo.auto.rca.verifica("B123ABC")
19
19
  console.log(rca.status, rca.expiresAt) // "valid" 2027-03-01T00:00:00.000Z
20
20
  ```
21
21
 
22
- Apelurile sunt grupate pe domeniu și pe document, deci citești din cod ce verifici: `acteo.auto.rca`, `acteo.auto.itp`, `acteo.auto.rovinieta`, `acteo.auto.arr`, plus `acteo.auto.flota` pentru vehiculele din cont și `acteo.webhooks` pentru notificări.
22
+ Apelurile sunt grupate pe domeniu și pe document, deci citești din cod ce verifici: `acteo.auto.rca`, `acteo.auto.itp`, `acteo.auto.rovinieta`, `acteo.auto.arr`, plus `acteo.auto.flota` pentru vehiculele din cont, `acteo.auto.vin`, `acteo.auto.numere` și `acteo.auto.imagini` pentru celelalte produse și `acteo.webhooks` pentru notificări.
23
23
 
24
24
  ## Cuprins
25
25
 
@@ -46,7 +46,10 @@ Apelurile sunt grupate pe domeniu și pe document, deci citești din cod ce veri
46
46
  | Verificare rovinietă | `acteo.auto.rovinieta.verifica()` | Dacă rovinieta e plătită și până când, din CNAIR |
47
47
  | Verificare copie conformă ARR | `acteo.auto.arr.verifica()` | Valabilitatea copiei conforme pentru transportatori |
48
48
  | Gestionare flotă | `acteo.auto.flota` | Adaugi, listezi și ștergi vehiculele monitorizate automat |
49
- | Webhook-uri | `acteo.webhooks` | Rezultatul verificării la URL-ul tău, alerte `document.expira` la 30, 14 și 3 zile |
49
+ | Decodare VIN | `acteo.auto.vin.decodeaza()` | Marca, modelul, anul de fabricație și structura seriei de șasiu |
50
+ | Număr de înmatriculare disponibil | `acteo.auto.numere.verifica()` | Dacă numărul e liber la DGPCI și poate fi rezervat |
51
+ | Poza unei mașini | `acteo.auto.imagini.obtine()` | Link spre o poză de studio (WebP transparent) după marcă, model și an |
52
+ | Webhook-uri | `acteo.webhooks` | Rezultatul verificării la URL-ul tău, alerte `document.expira` la 30, 14 și 3 zile, plus evenimentele celorlalte servicii din cont |
50
53
  | Validare locală | | Numărul de înmatriculare și VIN-ul sunt verificate înainte de cerere, deci o greșeală de tastare nu consumă din cotă |
51
54
  | Erori tipate | | O clasă de eroare pentru fiecare situație, cu mesaj în română și `hint` de rezolvare |
52
55
  | Reîncercări sigure | | Backoff exponențial cu jitter, `Retry-After` respectat, niciun POST taxat de două ori |
@@ -134,6 +137,37 @@ try {
134
137
  const arr = await acteo.auto.arr.verifica("CJ45XYZ")
135
138
  ```
136
139
 
140
+ ### Decodare VIN
141
+
142
+ ```ts
143
+ const d = await acteo.auto.vin.decodeaza("WVWZZZ1KZBW000000")
144
+ console.log(d.marca, d.model, d.anFabricatie) // "Volkswagen" "Golf" 2011
145
+ console.log(d.structura.wmi, d.structura.cifraControl) // "WVW" "neaplicabila"
146
+ ```
147
+
148
+ Decodarea consumă din cotă doar când găsește marca și modelul (`taxat: true`). Fără ele primești totuși structura VIN-ului (WMI, VDS, VIS, țara, cifra de control, anii posibili), calculată din cele 17 caractere.
149
+
150
+ ### Verifică dacă un număr de înmatriculare e liber
151
+
152
+ ```ts
153
+ const r = await acteo.auto.numere.verifica("BV 07 ABC")
154
+ if (r.disponibil) console.log(`${r.numar} e liber`)
155
+ ```
156
+
157
+ Răspunsul vine direct de la DGPCI, în aceeași cerere, și poate dura până la două minute. SDK-ul dă acestei cereri un timeout de cel puțin 150 de secunde, oricât de mic e `timeoutMs` din client. Consumă din cotă doar când DGPCI dă un verdict.
158
+
159
+ ### Poza unei mașini
160
+
161
+ ```ts
162
+ const p = await acteo.auto.imagini.obtine({ marca: "Volkswagen", model: "Golf", an: 2015, unghi: "fata" })
163
+ if (p.status === "gata") afiseaza(p.url) // link valabil până la p.expiraLa
164
+
165
+ // sau așteaptă cât timp poza e încă în lucru:
166
+ const gata = await acteo.auto.imagini.asteapta({ marca: "Volkswagen", model: "Golf", an: 2015 })
167
+ ```
168
+
169
+ Cu `status: "gata"` primești poza mașinii cerute și cererea se taxează. Altfel primești poza generică (mașina sub husă), netaxată: `in-lucru` înseamnă că poza se generează acum, `necunoscut` că marca sau modelul nu au fost identificate, iar `indisponibil` că generarea a eșuat.
170
+
137
171
  ## Ce identificator cere fiecare verificare
138
172
 
139
173
  Fiecare sursă oficială caută după alt identificator, așa că fiecare document își cere exact datele lui. SDK-ul aplică aceleași reguli ca API-ul și te oprește înainte de cerere dacă lipsește ceva.
@@ -246,6 +280,22 @@ Scoate vehiculul din cont. Aruncă `EroareNegasit` dacă ID-ul nu există în co
246
280
 
247
281
  Operațiile pe flotă nu consumă din cota de verificări, dar cer un plan activ.
248
282
 
283
+ ### `auto.vin.decodeaza(vin)`
284
+
285
+ Decodează o serie de șasiu. Întoarce `marca`, `model`, `anFabricatie`, `sursaAn` (`"pozitia-10"`, `"generatie"` sau `"anunturi"`), `modelePosibile` și `structura` (`wmi`, `vds`, `vis`, `regiune`, `tara`, `cifraControl`, `cifraControlAsteptata`, `aniPosibili`). `gasit` spune dacă marca e cunoscută, iar `taxat` dacă cererea s-a consumat din cotă. VIN-ul e validat local înainte de cerere. Cere un abonament de decodare VIN.
286
+
287
+ ### `auto.numere.verifica(numar)`
288
+
289
+ Verifică la DGPCI un singur număr complet: indicativul județului, cifrele și trei litere (`BV07ABC`, `B123ABC`). Numerele incomplete sau cu `?` și `*` sunt respinse local. Întoarce `numar` (normalizat), `disponibil` și `mesaj` (textul DGPCI, sau `null`). Dacă DGPCI nu acceptă numărul primești `EroareValidare` cu `cod: "NUMAR_RESPINS"`. Când verificarea nu poate rula primești `EroareServer` cu `cod` `OCUPAT`, `INDISPONIBIL`, `EROARE_DGPCI` sau `TIMEOUT`. Niciuna nu se taxează, iar `OCUPAT` se reîncearcă singur după `Retry-After`. Cere un abonament de numere disponibile.
290
+
291
+ ### `auto.imagini.obtine({ marca, model, an, unghi?, umbra? })`
292
+
293
+ Răspunde imediat cu poza mașinii sau cu poza generică. `unghi` poate fi `"trei-sferturi"` (implicit), `"fata"`, `"profil"`, `"spate"`, `"trei-sferturi-dreapta"` sau `"profil-dreapta"`, iar `umbra` e implicit `true`. Câmpuri: `gata`, `status`, `taxat`, `url`, `expiraLa` (`Date`), `latime`, `inaltime`, `marca` și `model` (forma canonică) și `generatie` (`eticheta`, `anDe`, `anPana`, `caroserie`, sau `null`). La `in-lucru`, `retryAfterMs` spune când să ceri din nou. Linkul expiră după 24 de ore. Fiecare cerere a unei poze gata se taxează, deci păstrează linkul până la `expiraLa`. Cere un abonament de imagini mașini.
294
+
295
+ ### `auto.imagini.asteapta({ marca, model, an, unghi?, umbra? }, { timeoutMs? })`
296
+
297
+ Ca `obtine()`, dar cât timp poza e `in-lucru` o cere din nou, cu pauzele din `Retry-After` (cel puțin 10 secunde). Întoarce primul răspuns care nu mai e `in-lucru`. După `timeoutMs` (implicit 2 minute) aruncă `EroareTimeoutVerificare`. Cererile intermediare nu se taxează, dar intră în plafonul zilnic de poze generice.
298
+
249
299
  ### Utilitare de validare
250
300
 
251
301
  ```ts
@@ -271,8 +321,9 @@ Le poți folosi pentru formularele tale, ca să validezi datele înainte să aju
271
321
  | Constantă | Valoare |
272
322
  |---|---|
273
323
  | `TIPURI_VERIFICARE` | `["rca", "itp", "rovinieta", "arr"]`, util pentru dropdown-uri și validare |
274
- | `HEADER_CHEIE_WEBHOOK` | `"x-verificrca-key"`, headerul cu cheia de webhook |
275
- | `HEADER_EVENIMENT_WEBHOOK` | `"x-verificrca-event"`, headerul cu numele evenimentului |
324
+ | `UNGHIURI_IMAGINE` | unghiurile acceptate de `auto.imagini` |
325
+ | `HEADER_CHEIE_WEBHOOK` | `"x-acteo-key"`, headerul cu cheia de webhook |
326
+ | `HEADER_EVENIMENT_WEBHOOK` | `"x-acteo-event"`, headerul cu numele evenimentului |
276
327
  | `URL_IMPLICIT` | `"https://api.acteo.ro"` |
277
328
  | `VERSIUNE_SDK` | versiunea pachetului, trimisă în `User-Agent` |
278
329
 
@@ -298,9 +349,9 @@ app.post("/webhooks/acteo/9f3k2", express.raw({ type: "application/json" }), (re
298
349
 
299
350
  Pune un segment greu de ghicit în URL, păstrează-l pe HTTPS și verifică dacă `requestId`-ul primit corespunde celui întors de `porneste()` înainte să te bazezi pe conținut.
300
351
 
301
- ### Notificări de expirare (`document.expira`)
352
+ ### Notificări din cont (`document.expira` și celelalte evenimente)
302
353
 
303
- Pe planurile care includ webhook-uri, configurezi un URL în dashboard și primești câte un eveniment când un document al unui vehicul monitorizat intră într-un prag de expirare. Pentru RCA, ITP și rovinietă pragurile sunt 30, 14 și 3 zile, iar pentru ARR 60, 50 și 45 de zile. Fiecare cerere vine cu cheia contului în headerul `X-Verificrca-Key`. SDK-ul o compară în timp constant, ca să nu dezvăluie nimic prin durata comparației:
354
+ Pe planurile care includ webhook-uri, configurezi un URL în dashboard și primești câte un eveniment când un document al unui vehicul monitorizat intră într-un prag de expirare. Pentru RCA, ITP și rovinietă pragurile sunt 30, 14 și 3 zile, iar pentru ARR 60, 50 și 45 de zile. Fiecare cerere vine cu cheia contului în headerul `X-Acteo-Key` și cu numele evenimentului în `X-Acteo-Event`. SDK-ul o compară în timp constant, ca să nu dezvăluie nimic prin durata comparației:
304
355
 
305
356
  ```ts
306
357
  import { EroareWebhook } from "@acteo/api"
@@ -320,6 +371,23 @@ app.post("/webhooks/acteo", express.raw({ type: "application/json" }), (req, res
320
371
 
321
372
  Folosește `ev.id` pentru deduplicare. Un eveniment poate ajunge de mai multe ori dacă serverul tău nu răspunde cu 2xx. Butonul de test din dashboard trimite `event: "webhook.test"`.
322
373
 
374
+ Cu add-on-ul Webhook, la același URL vin și evenimentele celorlalte servicii din cont. `verificaNotificare()` le validează pe toate și le distingi după `event`:
375
+
376
+ | `event` | Când vine | Câmpuri principale |
377
+ |---|---|---|
378
+ | `document.expira` | Un document al unui vehicul intră într-un prag de expirare | `vehicul`, `document`, `expiraLa`, `zileRamase`, `prag` |
379
+ | `dosar.eveniment` | Noutate într-un dosar monitorizat | `dosar`, `eveniment.tip`, `eveniment.descriere` |
380
+ | `dosar.termen` | Se apropie o ședință, cu 3 zile și cu o zi înainte | `dosar`, `sedinta`, `zileRamase` |
381
+ | `firma.schimbare` | ANAF a schimbat starea unei firme monitorizate | `firma`, `schimbari` |
382
+ | `firma.dosar` | Dosar nou în instanță pe numele unei firme | `firma`, `dosar.insolventa` |
383
+ | `marca.schimbare` | Schimbare la o marcă urmărită (OSIM sau EUIPO) | `marca`, `schimbare`, `valoareVeche`, `valoareNoua` |
384
+ | `marca.expira` | O marcă intră într-un prag de expirare | `marca`, `expiraLa`, `prag`, `reinnoirePanaLa` |
385
+ | `asigurare.schimbare` | S-a schimbat statutul de asigurat la CNAS | `persoana`, `statut`, `areCard` |
386
+ | `termen.expira` | Un termen din cont intră în pragul de 30 sau de 3 zile | `termen`, `zileRamase`, `prag` |
387
+ | `webhook.test` | Butonul de test din dashboard | `mesaj` |
388
+
389
+ Datele cu oră (`trimisLa`, `sedinta.data`, `verificatLa`) devin `Date`. Datele calendaristice `yyyy-mm-dd` (`marca.expiraLa`, `termen.expiraLa`) rămân text.
390
+
323
391
  ## Erori
324
392
 
325
393
  Toate erorile moștenesc `ActeoError`, care la rândul ei moștenește `Error`. Fiecare are `_tag`, `message` (în română), plus `status`, `cod`, `hint` și `raspuns` când vin de la API.
@@ -327,18 +395,18 @@ Toate erorile moștenesc `ActeoError`, care la rândul ei moștenește `Error`.
327
395
  | Clasă | Când apare | Câmpuri utile |
328
396
  |---|---|---|
329
397
  | `EroareConfigurare` | Cheie lipsă sau opțiuni invalide | |
330
- | `EroareValidare` | Date greșite, local sau HTTP 400 | `camp`, `acceptate` |
398
+ | `EroareValidare` | Date greșite, local sau HTTP 400; 422 când DGPCI refuză numărul (`NUMAR_RESPINS`) | `camp`, `acceptate`, `cod` |
331
399
  | `EroareAutentificare` | 401: cheie invalidă sau dezactivată | `hint` |
332
400
  | `EroarePlanInactiv` | 402: fără abonament activ | `hint` |
333
401
  | `EroareInterzis` | 403: `LIMIT_ATINS`, `ARR_NECESITA_PLAN` | `cod`, `limita` |
334
402
  | `EroareNegasit` | 404: vehicul inexistent în cont | |
335
403
  | `EroareConflict` | 409: `VEHICUL_EXISTENT` | |
336
404
  | `EroareLimita` | 429: cotă, plafon de flotă sau polling prea des | `cod`, `retryAfterMs`, `utilizareZi`, `utilizareLuna` |
337
- | `EroareServer` | 5xx | `status` |
405
+ | `EroareServer` | 5xx; la numere disponibile `OCUPAT`, `INDISPONIBIL`, `EROARE_DGPCI`, `TIMEOUT` | `status`, `cod`, `retryAfterMs` |
338
406
  | `EroareRetea` | Fără răspuns sau timeout | `timeout`, `neajunsa` |
339
407
  | `EroareRaspunsInvalid` | Răspuns cu formă neașteptată | `raspuns` |
340
408
  | `EroareVerificare` | Sursa oficială nu a putut fi interogată sau a refuzat datele | `codSursa` |
341
- | `EroareTimeoutVerificare` | `asteapta()` a depășit `timeoutMs` | |
409
+ | `EroareTimeoutVerificare` | `asteapta()` sau `imagini.asteapta()` a depășit `timeoutMs` | |
342
410
  | `EroareWebhook` | Cheie greșită sau payload invalid | `cod` |
343
411
 
344
412
  ```ts
@@ -364,7 +432,9 @@ SDK-ul nu trimite niciodată de două ori o verificare taxată.
364
432
  |---|---|---|
365
433
  | Rețea căzută, timeout | se reîncearcă | nu (cererea poate să fi ajuns) |
366
434
  | DNS, conexiune refuzată | se reîncearcă | se reîncearcă (sigur nu a ajuns) |
367
- | 502, 503, 504 | se reîncearcă | se reîncearcă (proxy, nu aplicația) |
435
+ | 502, 503, 504 fără `cod` | se reîncearcă | se reîncearcă (proxy, nu aplicația) |
436
+ | 503 `OCUPAT` la numere disponibile | | se reîncearcă după `Retry-After` (netaxat) |
437
+ | 502, 503, 504 cu alt `cod` | | nu (netaxat, dar repetarea nu ajută imediat) |
368
438
  | 500 | se reîncearcă | nu |
369
439
  | 429 la polling | se reîncearcă după `Retry-After` | |
370
440
  | 429 cotă sau plafon flotă | nu | nu |
@@ -379,9 +449,9 @@ const acteo = new Acteo({
379
449
 
380
450
  ## Cotă și limite
381
451
 
382
- Fiecare verificare consumă o unitate din cota zilnică și lunară a planului, dar numai când sursa oficială a răspuns. Dacă mașina a fost verificată de curând, primești imediat rezultatul existent, iar cererea consumă din cotă. Dacă sursa nu răspunde, nu consumi nimic. Verificările încă în curs ocupă cota până la răspuns, ca să nu treci de limită cu cereri trimise în paralel.
452
+ Fiecare verificare consumă o unitate din cota zilnică și lunară a planului, dar numai când sursa oficială a răspuns. Decodarea VIN, numerele disponibile și pozele au fiecare abonamentul și cota lor: decodarea se taxează doar cu marcă și model găsite, numărul doar când DGPCI dă un verdict, iar poza doar când e gata. Decodările fără rezultat și pozele generice au un plafon zilnic separat. Dacă mașina a fost verificată de curând, primești imediat rezultatul existent, iar cererea consumă din cotă. Dacă sursa nu răspunde, nu consumi nimic. Verificările încă în curs ocupă cota până la răspuns, ca să nu treci de limită cu cereri trimise în paralel.
383
453
 
384
- Rezultatele au câmpul `limite`, completat din headerele `X-RateLimit-*`:
454
+ Rezultatele (inclusiv decodările, numerele și pozele) au câmpul `limite`, completat din headerele `X-RateLimit-*`:
385
455
 
386
456
  ```ts
387
457
  const r = await acteo.auto.rca.porneste("B123ABC")
@@ -458,6 +528,14 @@ Asigurătorul are nevoie de timp ca să înregistreze polița nouă în AIDA, de
458
528
 
459
529
  Tehnic da, dar nu trebuie să-l folosești acolo, pentru că ar expune cheia API. Folosește-l pe server (Node.js, Next.js route handlers, funcții serverless) și trimite spre browser doar rezultatul.
460
530
 
531
+ ### Cum verific dacă un număr de înmatriculare e liber?
532
+
533
+ Apelezi `acteo.auto.numere.verifica("BV07ABC")`. SDK-ul trimite numărul la DGPCI și îți întoarce `disponibil: true` dacă e liber și poate fi rezervat. Trimite numărul complet, cu județ, cifre și trei litere; căutările cu `?` sau `*` nu sunt acceptate.
534
+
535
+ ### Ce aflu dintr-o serie de șasiu (VIN)?
536
+
537
+ Cu `acteo.auto.vin.decodeaza(vin)` afli marca, modelul și anul de fabricație, plus structura VIN-ului: producătorul (WMI), țara, cifra de control și anii posibili. Câmpul `sursaAn` spune de unde vine anul, iar `modelePosibile` apare când datele nu indică un singur model.
538
+
461
539
  ### Există SDK pentru PHP sau Python?
462
540
 
463
541
  Da, cu aceleași apeluri: [`acteo/api`](https://github.com/acteoro/sdk_php) pentru PHP și [`acteo`](https://github.com/acteoro/sdk_python) pentru Python. [Documentația API](https://acteo.ro/api-acces) are și exemple pentru cURL.