@acteo/api 0.0.0-stage → 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 +43 -0
- package/LICENSE +21 -0
- package/README.md +570 -2
- package/dist/index.cjs +1794 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1751 -0
- package/dist/index.d.ts +1751 -0
- package/dist/index.js +1752 -0
- package/dist/index.js.map +1 -0
- package/package.json +112 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Changelog
|
|
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
|
+
|
|
12
|
+
## @acteo/api 0.3.0 (2026-10-29)
|
|
13
|
+
|
|
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.
|
|
15
|
+
|
|
16
|
+
- Client nou `Acteo`: `acteo.auto.rca`, `acteo.auto.itp`, `acteo.auto.rovinieta` și `acteo.auto.arr`, fiecare cu `verifica`, `porneste`, `rezultat` și `asteapta`. Fiecare document își cere exact identificatorii lui, iar rezultatul are tipul documentului.
|
|
17
|
+
- La RCA, un text de 17 caractere fără I, O și Q e tratat ca VIN. Cu ambele date: `{ numar, vin }`.
|
|
18
|
+
- `acteo.auto.flota` pentru vehiculele din cont și `acteo.webhooks` pentru webhook-uri.
|
|
19
|
+
- Adresa implicită este `https://api.acteo.ro`. Cheia se citește din `ACTEO_API_KEY`, apoi din `VERIFICRCA_API_KEY`.
|
|
20
|
+
- `ActeoError`, clasa de bază a erorilor (aceeași cu `VerificRcaError`).
|
|
21
|
+
- Clientul `VerificRca` și apelurile de până acum funcționează în continuare, cu aceeași adresă implicită.
|
|
22
|
+
|
|
23
|
+
## 0.2.0 (2026-10-09)
|
|
24
|
+
|
|
25
|
+
Verificarea rovinietei cere acum numărul certificatului de înmatriculare. Este o cerință nouă a sursei oficiale, care validează împreună numărul de înmatriculare, VIN-ul și numărul talonului. Codul care verifică rovinieta fără `serieTalon` trebuie actualizat: cererea e respinsă local cu `EroareValidare` (`camp: "serieTalon"`), fără să consume din cotă.
|
|
26
|
+
|
|
27
|
+
- `verificari.porneste` și `verificaSiAsteapta` primesc `serieTalon` (ex: `I00639603F`), obligatoriu la `tip: "rovinieta"`. Numărul e normalizat la litere și cifre mari și validat local (6-20 caractere, cel puțin o cifră). Interogarea rezultatului nu îl cere.
|
|
28
|
+
- `EroareVerificare` are câmpul nou `codSursa` când sursa oficială refuză datele trimise: `serie_talon_invalida`, `vin_invalid` sau `numar_invalid`. În aceste cazuri o reîncercare cu aceleași date nu ajută.
|
|
29
|
+
- `Vehicul` are câmpurile noi `serieTalon` (`string | null`) și `serieTalonRespinsa` (`boolean`).
|
|
30
|
+
- `vehicule.adauga` acceptă `serieTalon`, necesar pentru monitorizarea automată a rovinietei.
|
|
31
|
+
- Utilitare noi: `esteSerieTalonValida` și `normalizeazaSerieTalon`.
|
|
32
|
+
- `VERSIUNE_SDK` (trimisă în `User-Agent`) urmează din nou versiunea pachetului.
|
|
33
|
+
|
|
34
|
+
## 0.1.0 (2026-09-29)
|
|
35
|
+
|
|
36
|
+
Prima versiune.
|
|
37
|
+
|
|
38
|
+
- Client `VerificRca` cu `verificari.porneste`, `rezultat`, `asteapta` si `verificaSiAsteapta` pentru RCA, ITP, rovinieta si ARR.
|
|
39
|
+
- Gestionarea flotei: `vehicule.lista`, `adauga`, `sterge`.
|
|
40
|
+
- Webhook-uri: `parseazaWebhookRezultat` si `verificaWebhookNotificare` (cheie comparata in timp constant).
|
|
41
|
+
- Validare locala a numarului de inmatriculare si a VIN-ului, cu aceleasi reguli ca API-ul.
|
|
42
|
+
- Erori tipate, retry cu backoff exponential si jitter, `Retry-After` respectat, niciun POST taxat repetat.
|
|
43
|
+
- ESM si CommonJS, tipuri TypeScript complete, Node.js 18.17+.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Acteo.ro
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,571 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @acteo/api: API verificare RCA, ITP, rovinietă și ARR pentru Node.js
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@acteo/api)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
[](https://www.npmjs.com/package/@acteo/api)
|
|
6
|
+
|
|
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
|
+
|
|
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
|
+
|
|
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
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { Acteo } from "@acteo/api"
|
|
15
|
+
|
|
16
|
+
const acteo = new Acteo({ apiKey: process.env.ACTEO_API_KEY })
|
|
17
|
+
|
|
18
|
+
const rca = await acteo.auto.rca.verifica("B123ABC")
|
|
19
|
+
console.log(rca.status, rca.expiresAt) // "valid" 2027-03-01T00:00:00.000Z
|
|
20
|
+
```
|
|
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, `acteo.auto.vin`, `acteo.auto.numere` și `acteo.auto.imagini` pentru celelalte produse și `acteo.webhooks` pentru notificări.
|
|
23
|
+
|
|
24
|
+
## Cuprins
|
|
25
|
+
|
|
26
|
+
- [Ce face SDK-ul](#ce-face-sdk-ul)
|
|
27
|
+
- [Instalare](#instalare)
|
|
28
|
+
- [Pornire rapidă](#pornire-rapidă)
|
|
29
|
+
- [Ce identificator cere fiecare verificare](#ce-identificator-cere-fiecare-verificare)
|
|
30
|
+
- [Cum decurge o verificare](#cum-decurge-o-verificare)
|
|
31
|
+
- [Referință API](#referință-api)
|
|
32
|
+
- [Webhook-uri](#webhook-uri)
|
|
33
|
+
- [Erori](#erori)
|
|
34
|
+
- [Reîncercări, backoff și timeout](#reîncercări-backoff-și-timeout)
|
|
35
|
+
- [Cotă și limite](#cotă-și-limite)
|
|
36
|
+
- [Exemple](#exemple)
|
|
37
|
+
- [Vii de la @verificrca/sdk?](#vii-de-la-verificrcasdk)
|
|
38
|
+
- [Întrebări frecvente](#întrebări-frecvente)
|
|
39
|
+
|
|
40
|
+
## Ce face SDK-ul
|
|
41
|
+
|
|
42
|
+
| Funcție | Apel | Ce primești |
|
|
43
|
+
|---|---|---|
|
|
44
|
+
| Verificare RCA după număr sau VIN | `acteo.auto.rca.verifica()` | Starea poliței RCA și data expirării, din baza AIDA |
|
|
45
|
+
| Verificare ITP după VIN | `acteo.auto.itp.verifica()` | Data până la care e valabilă inspecția tehnică, din RAR |
|
|
46
|
+
| Verificare rovinietă | `acteo.auto.rovinieta.verifica()` | Dacă rovinieta e plătită și până când, din CNAIR |
|
|
47
|
+
| Verificare copie conformă ARR | `acteo.auto.arr.verifica()` | Valabilitatea copiei conforme pentru transportatori |
|
|
48
|
+
| Gestionare flotă | `acteo.auto.flota` | Adaugi, listezi și ștergi vehiculele monitorizate automat |
|
|
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 |
|
|
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ă |
|
|
54
|
+
| Erori tipate | | O clasă de eroare pentru fiecare situație, cu mesaj în română și `hint` de rezolvare |
|
|
55
|
+
| Reîncercări sigure | | Backoff exponențial cu jitter, `Retry-After` respectat, niciun POST taxat de două ori |
|
|
56
|
+
|
|
57
|
+
## Instalare
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm install @acteo/api
|
|
61
|
+
# sau
|
|
62
|
+
pnpm add @acteo/api
|
|
63
|
+
# sau
|
|
64
|
+
yarn add @acteo/api
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Cheia API o poți da direct în constructor sau prin variabila de mediu `ACTEO_API_KEY`:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
export ACTEO_API_KEY=cheia_ta_api
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Nu pune cheia în cod care ajunge în browser. Cheia dă acces la cota contului tău și la vehiculele din el, deci o folosești doar pe server.
|
|
74
|
+
|
|
75
|
+
## Pornire rapidă
|
|
76
|
+
|
|
77
|
+
### Verificare RCA după număr de înmatriculare
|
|
78
|
+
|
|
79
|
+
```ts
|
|
80
|
+
import { Acteo } from "@acteo/api"
|
|
81
|
+
|
|
82
|
+
const acteo = new Acteo() // citește ACTEO_API_KEY
|
|
83
|
+
|
|
84
|
+
const rca = await acteo.auto.rca.verifica("B 123 ABC")
|
|
85
|
+
|
|
86
|
+
if (rca.status === "expired") {
|
|
87
|
+
console.log("Mașina nu are RCA valabil.")
|
|
88
|
+
} else if (rca.status === "warning") {
|
|
89
|
+
console.log(`RCA-ul expiră curând, pe ${rca.expiresAt?.toLocaleDateString("ro-RO")}`)
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Un text de 17 caractere fără literele I, O și Q e tratat ca VIN, orice altceva ca număr de înmatriculare. Pentru RCA îți recomandăm să trimiți ambele. Baza AIDA găsește polița mai sigur după seria de șasiu, iar uneori o poliță emisă pe VIN nu apare la căutarea după număr:
|
|
94
|
+
|
|
95
|
+
```ts
|
|
96
|
+
await acteo.auto.rca.verifica({ numar: "B123ABC", vin: "WVWZZZ1JZXW000001" })
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Verificare ITP după serie de șasiu
|
|
100
|
+
|
|
101
|
+
```ts
|
|
102
|
+
const itp = await acteo.auto.itp.verifica("WVWZZZ1JZXW000001")
|
|
103
|
+
console.log(`ITP valabil până la ${itp.expiresAt?.toLocaleDateString("ro-RO")}`)
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### Verificare rovinietă
|
|
107
|
+
|
|
108
|
+
Rovinieta cere trei date: numărul de înmatriculare, seria de șasiu (VIN) și numărul certificatului de înmatriculare (`serieTalon`), tipărit jos pe talon. Sursa oficială le validează pe toate trei împreună.
|
|
109
|
+
|
|
110
|
+
```ts
|
|
111
|
+
const rovinieta = await acteo.auto.rovinieta.verifica({
|
|
112
|
+
numar: "B123ABC",
|
|
113
|
+
vin: "WVWZZZ1JZXW000001",
|
|
114
|
+
serieTalon: "I00639603F",
|
|
115
|
+
})
|
|
116
|
+
console.log(rovinieta.status, rovinieta.expiresAt)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Dacă sursa respinge datele (de exemplu, numărul talonului nu corespunde mașinii), primești `EroareVerificare` cu `codSursa: "serie_talon_invalida"`. O reîncercare cu aceleași date nu ajută; corectează întâi câmpul indicat:
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { EroareVerificare } from "@acteo/api"
|
|
123
|
+
|
|
124
|
+
try {
|
|
125
|
+
await acteo.auto.rovinieta.verifica({ numar: "B123ABC", vin, serieTalon: talon })
|
|
126
|
+
} catch (err) {
|
|
127
|
+
if (err instanceof EroareVerificare && err.codSursa === "serie_talon_invalida") {
|
|
128
|
+
return cereUtilizatoruluiNumarulTalonului()
|
|
129
|
+
}
|
|
130
|
+
throw err
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Verificare copie conformă ARR
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
const arr = await acteo.auto.arr.verifica("CJ45XYZ")
|
|
138
|
+
```
|
|
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
|
+
|
|
171
|
+
## Ce identificator cere fiecare verificare
|
|
172
|
+
|
|
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.
|
|
174
|
+
|
|
175
|
+
| Apel | Ce primește | Sursa |
|
|
176
|
+
|---|---|---|
|
|
177
|
+
| `auto.rca.verifica(x)` | număr de înmatriculare **sau** VIN, ori `{ numar, vin }` (recomandat) | AIDA / BAAR |
|
|
178
|
+
| `auto.itp.verifica(vin)` | VIN (17 caractere) | RAR |
|
|
179
|
+
| `auto.rovinieta.verifica({ numar, vin, serieTalon })` | toate trei, **obligatorii** | CNAIR |
|
|
180
|
+
| `auto.arr.verifica(numar)` | număr de înmatriculare | ARR |
|
|
181
|
+
|
|
182
|
+
Formatele de număr acceptate: București (`B123ABC`, `B12ABC`), județe (`CJ45XYZ`, `IS08BCD`), corp diplomatic (`CD123A`) și numere temporare (`TC1234AB`). Spațiile și cratimele sunt eliminate automat, deci `b-123 abc` devine `B123ABC`. VIN-ul trebuie să aibă exact 17 caractere, fără literele I, O și Q (standardul ISO 3779).
|
|
183
|
+
|
|
184
|
+
`serieTalon` este numărul certificatului de înmatriculare, de forma `I00639603F`. SDK-ul păstrează doar literele și cifrele, cu majuscule, și cere între 6 și 20 de caractere, cu cel puțin o cifră. Doar sursa oficială poate confirma că numărul aparține mașinii.
|
|
185
|
+
|
|
186
|
+
## Cum decurge o verificare
|
|
187
|
+
|
|
188
|
+
1. **Cerere** (`porneste`). Dacă există un rezultat recent pentru mașina respectivă, îl primești imediat. Altfel verificarea intră în coadă și primești `status: "processing"`.
|
|
189
|
+
2. **Interogarea sursei.** Sursa oficială e consultată în fundal. Dacă nu răspunde în 4 minute, verificarea se încheie cu eroare.
|
|
190
|
+
3. **Rezultatul** ajunge la tine pe una din trei căi:
|
|
191
|
+
- `verifica()` face tot drumul și întoarce direct rezultatul final;
|
|
192
|
+
- `rezultat()` sau `asteapta()` fac polling, fără să consume din cotă;
|
|
193
|
+
- webhook: dacă trimiți `callbackUrl` la `porneste()`, API-ul face POST cu rezultatul la adresa ta.
|
|
194
|
+
|
|
195
|
+
O verificare consumă din cota planului doar când sursa oficială a răspuns, inclusiv atunci când refuză datele trimise. Dacă sursa nu răspunde, nu consumi nimic. Interogările de rezultat sunt gratuite.
|
|
196
|
+
|
|
197
|
+
### Statusuri
|
|
198
|
+
|
|
199
|
+
| `status` | Înseamnă | `expiresAt` |
|
|
200
|
+
|---|---|---|
|
|
201
|
+
| `valid` | Document valabil | data expirării |
|
|
202
|
+
| `warning` | Expiră curând: RCA în 14 zile, ITP în 30, rovinietă în 7, ARR în 14 | data expirării |
|
|
203
|
+
| `expired` | Expirat sau inexistent, confirmat de sursă | data expirării sau `null` |
|
|
204
|
+
| `not_found` | Sursa nu a găsit vehiculul | `null` |
|
|
205
|
+
| `processing` | Verificarea e încă în curs | nu există |
|
|
206
|
+
|
|
207
|
+
Când verificarea se încheie cu eroare, SDK-ul aruncă `EroareVerificare`. Dacă sursa oficială doar nu a răspuns, `codSursa` lipsește și poți relua cererea. Dacă sursa a refuzat datele trimise, `codSursa` spune ce e greșit și reîncercarea nu ajută până nu corectezi câmpul:
|
|
208
|
+
|
|
209
|
+
| `codSursa` | Câmpul de corectat |
|
|
210
|
+
|---|---|
|
|
211
|
+
| `serie_talon_invalida` | `serieTalon`, numărul certificatului de înmatriculare |
|
|
212
|
+
| `vin_invalid` | `vin` |
|
|
213
|
+
| `numar_invalid` | numărul de înmatriculare |
|
|
214
|
+
|
|
215
|
+
## Referință API
|
|
216
|
+
|
|
217
|
+
### `new Acteo(optiuni?)`
|
|
218
|
+
|
|
219
|
+
| Opțiune | Tip | Implicit | Descriere |
|
|
220
|
+
|---|---|---|---|
|
|
221
|
+
| `apiKey` | `string` | `process.env.ACTEO_API_KEY` | Cheia API |
|
|
222
|
+
| `baseUrl` | `string` | `https://api.acteo.ro` | Adresa API-ului |
|
|
223
|
+
| `timeoutMs` | `number` | `30000` | Timeout pe fiecare cerere HTTP |
|
|
224
|
+
| `retry` | `object \| false` | `{ incercari: 3, intarziereInitialaMs: 500, intarziereMaximaMs: 10000 }` | Politica de reîncercare; `false` o oprește |
|
|
225
|
+
| `fetch` | `typeof fetch` | `globalThis.fetch` | Alt `fetch` (proxy, agent HTTP, teste) |
|
|
226
|
+
| `userAgent` | `string` | | Adăugat la `User-Agent`, util în loguri |
|
|
227
|
+
|
|
228
|
+
Constructorul aruncă `EroareConfigurare` dacă lipsește cheia sau dacă o opțiune e invalidă.
|
|
229
|
+
|
|
230
|
+
Toate metodele primesc ca ultim argument `{ signal?: AbortSignal }`. Cu el poți anula cererea împreună cu reîncercările și așteptarea ei.
|
|
231
|
+
|
|
232
|
+
### `auto.<document>.verifica(identificator, optiuni?)`
|
|
233
|
+
|
|
234
|
+
Disponibil pe `auto.rca`, `auto.itp`, `auto.rovinieta` și `auto.arr`. Pornește verificarea și așteaptă rezultatul final. E calea cea mai simplă pentru scripturi și joburi cron. Opțiuni: `intervalMs` (implicit 3000, minim 2000) și `timeoutMs` (implicit 5 minute). La depășire aruncă `EroareTimeoutVerificare`. Rezultatul are tipul documentului: `auto.rca.verifica()` întoarce un rezultat cu `tip: "rca"`.
|
|
235
|
+
|
|
236
|
+
### `auto.<document>.porneste(identificator, { callbackUrl? })`
|
|
237
|
+
|
|
238
|
+
Pornește verificarea fără să aștepte. Întoarce fie rezultatul final (dacă există unul recent), fie un obiect `VerificareInCurs` pe care îl dai mai departe la `rezultat()` sau `asteapta()`.
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
const r = await acteo.auto.itp.porneste("WVWZZZ1JZXW000001", {
|
|
242
|
+
callbackUrl: "https://example.com/webhooks/acteo/9f3k2", // opțional
|
|
243
|
+
})
|
|
244
|
+
|
|
245
|
+
if (r.status === "processing") {
|
|
246
|
+
console.log("În coadă, requestId:", r.requestId)
|
|
247
|
+
const final = await acteo.auto.itp.asteapta(r)
|
|
248
|
+
}
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### `auto.<document>.rezultat(referinta)`
|
|
252
|
+
|
|
253
|
+
Interoghează o singură dată. Nu consumă din cotă. Primește obiectul întors de `porneste()` sau direct identificatorul documentului, de exemplu `acteo.auto.rca.rezultat("B123ABC")`.
|
|
254
|
+
|
|
255
|
+
### `auto.<document>.asteapta(referinta, optiuni?)`
|
|
256
|
+
|
|
257
|
+
Face polling până la rezultatul final, cu aceleași opțiuni ca `verifica()`. Nu consumă din cotă.
|
|
258
|
+
|
|
259
|
+
### `auto.flota.lista()`
|
|
260
|
+
|
|
261
|
+
Toate vehiculele din cont, cu datele de expirare `rcaExpiraLa`, `itpExpiraLa`, `rovinietaExpiraLa` și `arrExpiraLa` (ca `Date` sau `null`). Câmpul `activ` e `true` cât timp vehiculul e verificat automat și primește notificări de expirare. `serieTalon` e numărul certificatului de înmatriculare (sau `null`), iar `serieTalonRespinsa` devine `true` când sursa oficială l-a respins; rovinieta nu se mai verifică până nu e corectat. Vehiculele din cont sunt verificate automat și periodic, deci lista îți dă o imagine la zi a flotei fără să consume din cota de verificări.
|
|
262
|
+
|
|
263
|
+
### `auto.flota.adauga({ numarInmatriculare?, serieSasiu?, serieTalon?, arrMonitorizat? })`
|
|
264
|
+
|
|
265
|
+
Adaugă un vehicul în monitorizare. Trimite cel puțin un identificator. ITP-ul se monitorizează doar cu VIN, iar rovinieta cere numărul, VIN-ul și `serieTalon`; fără numărul talonului, rovinieta nu se verifică.
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
const v = await acteo.auto.flota.adauga({
|
|
269
|
+
numarInmatriculare: "B123ABC",
|
|
270
|
+
serieSasiu: "WVWZZZ1JZXW000001",
|
|
271
|
+
serieTalon: "I00639603F",
|
|
272
|
+
})
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
Poți primi `EroareInterzis` cu `cod: "LIMIT_ATINS"` când ai atins numărul de mașini din plan, sau `EroareConflict` când vehiculul există deja.
|
|
276
|
+
|
|
277
|
+
### `auto.flota.sterge(id)`
|
|
278
|
+
|
|
279
|
+
Scoate vehiculul din cont. Aruncă `EroareNegasit` dacă ID-ul nu există în contul cheii.
|
|
280
|
+
|
|
281
|
+
Operațiile pe flotă nu consumă din cota de verificări, dar cer un plan activ.
|
|
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
|
+
|
|
299
|
+
### Utilitare de validare
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
import {
|
|
303
|
+
esteNumarInmatriculareValid,
|
|
304
|
+
esteSerieTalonValida,
|
|
305
|
+
esteVinValid,
|
|
306
|
+
normalizeaza,
|
|
307
|
+
normalizeazaSerieTalon,
|
|
308
|
+
} from "@acteo/api"
|
|
309
|
+
|
|
310
|
+
esteNumarInmatriculareValid("CJ 45 XYZ") // true
|
|
311
|
+
esteVinValid("WVWZZZ1JZXW00000I") // false: litera I nu e permisă în VIN
|
|
312
|
+
esteSerieTalonValida("I00639603F") // true
|
|
313
|
+
normalizeaza(" b-123 abc ") // "B123ABC"
|
|
314
|
+
normalizeazaSerieTalon("i 00639603-f") // "I00639603F"
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
Le poți folosi pentru formularele tale, ca să validezi datele înainte să ajungă la server.
|
|
318
|
+
|
|
319
|
+
### Constante exportate
|
|
320
|
+
|
|
321
|
+
| Constantă | Valoare |
|
|
322
|
+
|---|---|
|
|
323
|
+
| `TIPURI_VERIFICARE` | `["rca", "itp", "rovinieta", "arr"]`, util pentru dropdown-uri și validare |
|
|
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 |
|
|
327
|
+
| `URL_IMPLICIT` | `"https://api.acteo.ro"` |
|
|
328
|
+
| `VERSIUNE_SDK` | versiunea pachetului, trimisă în `User-Agent` |
|
|
329
|
+
|
|
330
|
+
### Documentația completă a tipurilor
|
|
331
|
+
|
|
332
|
+
Fiecare metodă, câmp și clasă de eroare are documentație JSDoc, cu parametri, valoare întoarsă, erorile posibile și un exemplu. O vezi direct în editor, la hover. Ca s-o generezi ca site HTML, rulează `pnpm docs` în repo; rezultatul ajunge în `docs/`.
|
|
333
|
+
|
|
334
|
+
## Webhook-uri
|
|
335
|
+
|
|
336
|
+
API-ul trimite două feluri de webhook. SDK-ul le validează cu scheme stricte și îți dă obiecte tipate, cu datele ca `Date`.
|
|
337
|
+
|
|
338
|
+
### Rezultatul unei verificări (`callbackUrl`)
|
|
339
|
+
|
|
340
|
+
Când trimiți `callbackUrl` la `porneste()`, primești un POST cu rezultatul imediat ce e gata. Dacă sursa nu răspunde, primești `status: "error"`.
|
|
341
|
+
|
|
342
|
+
```ts
|
|
343
|
+
app.post("/webhooks/acteo/9f3k2", express.raw({ type: "application/json" }), (req, res) => {
|
|
344
|
+
const r = acteo.webhooks.parseazaRezultat(req.body) // string, Buffer sau obiect
|
|
345
|
+
if (r.status !== "error") salveaza(r.requestId, r.result?.expiresAt)
|
|
346
|
+
res.sendStatus(200)
|
|
347
|
+
})
|
|
348
|
+
```
|
|
349
|
+
|
|
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.
|
|
351
|
+
|
|
352
|
+
### Notificări din cont (`document.expira` și celelalte evenimente)
|
|
353
|
+
|
|
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:
|
|
355
|
+
|
|
356
|
+
```ts
|
|
357
|
+
import { EroareWebhook } from "@acteo/api"
|
|
358
|
+
|
|
359
|
+
app.post("/webhooks/acteo", express.raw({ type: "application/json" }), (req, res) => {
|
|
360
|
+
try {
|
|
361
|
+
const ev = acteo.webhooks.verificaNotificare(req.body, req.headers, { cheie: process.env.ACTEO_WEBHOOK_KEY! })
|
|
362
|
+
if (ev.event === "document.expira") {
|
|
363
|
+
trimiteAlerta(`${ev.vehicul.numarInmatriculare}: ${ev.document} expiră în ${ev.zileRamase} zile`)
|
|
364
|
+
}
|
|
365
|
+
res.sendStatus(200)
|
|
366
|
+
} catch (err) {
|
|
367
|
+
res.sendStatus(err instanceof EroareWebhook ? 401 : 500)
|
|
368
|
+
}
|
|
369
|
+
})
|
|
370
|
+
```
|
|
371
|
+
|
|
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"`.
|
|
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
|
+
|
|
391
|
+
## Erori
|
|
392
|
+
|
|
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.
|
|
394
|
+
|
|
395
|
+
| Clasă | Când apare | Câmpuri utile |
|
|
396
|
+
|---|---|---|
|
|
397
|
+
| `EroareConfigurare` | Cheie lipsă sau opțiuni invalide | |
|
|
398
|
+
| `EroareValidare` | Date greșite, local sau HTTP 400; 422 când DGPCI refuză numărul (`NUMAR_RESPINS`) | `camp`, `acceptate`, `cod` |
|
|
399
|
+
| `EroareAutentificare` | 401: cheie invalidă sau dezactivată | `hint` |
|
|
400
|
+
| `EroarePlanInactiv` | 402: fără abonament activ | `hint` |
|
|
401
|
+
| `EroareInterzis` | 403: `LIMIT_ATINS`, `ARR_NECESITA_PLAN` | `cod`, `limita` |
|
|
402
|
+
| `EroareNegasit` | 404: vehicul inexistent în cont | |
|
|
403
|
+
| `EroareConflict` | 409: `VEHICUL_EXISTENT` | |
|
|
404
|
+
| `EroareLimita` | 429: cotă, plafon de flotă sau polling prea des | `cod`, `retryAfterMs`, `utilizareZi`, `utilizareLuna` |
|
|
405
|
+
| `EroareServer` | 5xx; la numere disponibile `OCUPAT`, `INDISPONIBIL`, `EROARE_DGPCI`, `TIMEOUT` | `status`, `cod`, `retryAfterMs` |
|
|
406
|
+
| `EroareRetea` | Fără răspuns sau timeout | `timeout`, `neajunsa` |
|
|
407
|
+
| `EroareRaspunsInvalid` | Răspuns cu formă neașteptată | `raspuns` |
|
|
408
|
+
| `EroareVerificare` | Sursa oficială nu a putut fi interogată sau a refuzat datele | `codSursa` |
|
|
409
|
+
| `EroareTimeoutVerificare` | `asteapta()` sau `imagini.asteapta()` a depășit `timeoutMs` | |
|
|
410
|
+
| `EroareWebhook` | Cheie greșită sau payload invalid | `cod` |
|
|
411
|
+
|
|
412
|
+
```ts
|
|
413
|
+
import { ActeoError, EroareLimita, EroareValidare } from "@acteo/api"
|
|
414
|
+
|
|
415
|
+
try {
|
|
416
|
+
await acteo.auto.rca.porneste(numar)
|
|
417
|
+
} catch (err) {
|
|
418
|
+
if (err instanceof EroareValidare) return arataUtilizatorului(err.message)
|
|
419
|
+
if (err instanceof EroareLimita && err.cod === "COTA_ATINSA") return amanaPanaMaine()
|
|
420
|
+
if (err instanceof ActeoError) logger.error(err._tag, err.message, err.hint)
|
|
421
|
+
throw err
|
|
422
|
+
}
|
|
423
|
+
```
|
|
424
|
+
|
|
425
|
+
## Reîncercări, backoff și timeout
|
|
426
|
+
|
|
427
|
+
Erorile trecătoare sunt reîncercate automat, cu backoff exponențial (x2) și jitter, plafonat la `intarziereMaximaMs`. Când serverul trimite `Retry-After`, pauza nu coboară sub valoarea cerută.
|
|
428
|
+
|
|
429
|
+
SDK-ul nu trimite niciodată de două ori o verificare taxată.
|
|
430
|
+
|
|
431
|
+
| Situație | GET / DELETE | POST |
|
|
432
|
+
|---|---|---|
|
|
433
|
+
| Rețea căzută, timeout | se reîncearcă | nu (cererea poate să fi ajuns) |
|
|
434
|
+
| DNS, conexiune refuzată | se reîncearcă | se reîncearcă (sigur nu a ajuns) |
|
|
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) |
|
|
438
|
+
| 500 | se reîncearcă | nu |
|
|
439
|
+
| 429 la polling | se reîncearcă după `Retry-After` | |
|
|
440
|
+
| 429 cotă sau plafon flotă | nu | nu |
|
|
441
|
+
| 4xx | nu | nu |
|
|
442
|
+
|
|
443
|
+
```ts
|
|
444
|
+
const acteo = new Acteo({
|
|
445
|
+
timeoutMs: 15_000,
|
|
446
|
+
retry: { incercari: 5, intarziereInitialaMs: 250, intarziereMaximaMs: 8_000 },
|
|
447
|
+
})
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
## Cotă și limite
|
|
451
|
+
|
|
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.
|
|
453
|
+
|
|
454
|
+
Rezultatele (inclusiv decodările, numerele și pozele) au câmpul `limite`, completat din headerele `X-RateLimit-*`:
|
|
455
|
+
|
|
456
|
+
```ts
|
|
457
|
+
const r = await acteo.auto.rca.porneste("B123ABC")
|
|
458
|
+
console.log(r.limite) // { zi: { limita: 300, ramase: 287 }, luna: { limita: 10000, ramase: 9412 } }
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
Cota zilnică se resetează la miezul nopții, ora României. Limitele fiecărui plan le găsești pe [pagina API](https://acteo.ro/api-acces).
|
|
462
|
+
|
|
463
|
+
## Exemple
|
|
464
|
+
|
|
465
|
+
Folderul [`examples/`](./examples) conține scripturi gata de rulat:
|
|
466
|
+
|
|
467
|
+
- [`verificare-rca.ts`](./examples/verificare-rca.ts): verificare RCA cu număr și VIN, tratarea erorilor;
|
|
468
|
+
- [`flota.ts`](./examples/flota.ts): raport cu RCA, ITP, rovinietă și ARR care expiră în 30 de zile, pentru toată flota;
|
|
469
|
+
- [`webhook-server.ts`](./examples/webhook-server.ts): server `node:http` care primește ambele tipuri de webhook.
|
|
470
|
+
|
|
471
|
+
### Verificare în masă
|
|
472
|
+
|
|
473
|
+
```ts
|
|
474
|
+
const numere = ["B123ABC", "CJ45XYZ", "IS08BCD"]
|
|
475
|
+
|
|
476
|
+
const rezultate = await Promise.allSettled(
|
|
477
|
+
numere.map((numar) => acteo.auto.rca.verifica(numar)),
|
|
478
|
+
)
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Pentru liste mari, adaugă vehiculele în cont cu `auto.flota.adauga()`. Sunt monitorizate automat și primești notificările de expirare, fără să consumi din cota de verificări.
|
|
482
|
+
|
|
483
|
+
## Vii de la @verificrca/sdk?
|
|
484
|
+
|
|
485
|
+
Pachetul `@verificrca/sdk` s-a mutat la `@acteo/api`. Instalezi pachetul nou și schimbi apelurile:
|
|
486
|
+
|
|
487
|
+
| Înainte | Acum |
|
|
488
|
+
|---|---|
|
|
489
|
+
| `new VerificRca()` | `new Acteo()` |
|
|
490
|
+
| `VERIFICRCA_API_KEY` | `ACTEO_API_KEY` (cea veche e citită în continuare, dacă lipsește cea nouă) |
|
|
491
|
+
| `verificari.verificaSiAsteapta({ tip: "rca", query })` | `auto.rca.verifica(query)` |
|
|
492
|
+
| `verificari.verificaSiAsteapta({ tip: "itp", query: vin })` | `auto.itp.verifica(vin)` |
|
|
493
|
+
| `verificari.verificaSiAsteapta({ tip: "rovinieta", query, serieSasiu, serieTalon })` | `auto.rovinieta.verifica({ numar, vin, serieTalon })` |
|
|
494
|
+
| `verificari.porneste(...)` / `rezultat(...)` / `asteapta(...)` | `auto.<document>.porneste` / `rezultat` / `asteapta` |
|
|
495
|
+
| `vehicule.lista()` / `adauga()` / `sterge()` | `auto.flota.lista()` / `adauga()` / `sterge()` |
|
|
496
|
+
| `parseazaWebhookRezultat()` / `verificaWebhookNotificare()` | `webhooks.parseazaRezultat()` / `webhooks.verificaNotificare()` |
|
|
497
|
+
| `VerificRcaError` | `ActeoError` |
|
|
498
|
+
|
|
499
|
+
Erorile, tipurile rezultatelor și utilitarele de validare au rămas aceleași.
|
|
500
|
+
|
|
501
|
+
## Întrebări frecvente
|
|
502
|
+
|
|
503
|
+
### Cum verific RCA-ul unei mașini din Node.js?
|
|
504
|
+
|
|
505
|
+
Instalezi `@acteo/api`, creezi un client cu cheia API și apelezi `acteo.auto.rca.verifica("B123ABC")`. Primești statusul poliței și data expirării, din baza de date AIDA.
|
|
506
|
+
|
|
507
|
+
### Pot verifica ITP-ul după numărul de înmatriculare?
|
|
508
|
+
|
|
509
|
+
Nu. RAR caută inspecția tehnică periodică doar după seria de șasiu (VIN), așa că SDK-ul respinge cererea înainte să plece, fără să consume din cotă. VIN-ul îl găsești în talon, la rubrica E.
|
|
510
|
+
|
|
511
|
+
### Unde găsesc numărul certificatului de înmatriculare?
|
|
512
|
+
|
|
513
|
+
Pe talon (certificatul de înmatriculare), jos, la rubrica „Numărul certificatului”. Conține litere și cifre, de exemplu `I00639603F`. Nu îl confunda cu seria de șasiu (VIN), care e la rubrica E și are 17 caractere. SDK-ul acceptă numărul și cu spații sau cu litere mici și îl aduce singur la forma corectă.
|
|
514
|
+
|
|
515
|
+
### De ce verificarea rovinietei cere numărul talonului?
|
|
516
|
+
|
|
517
|
+
Pentru că așa cere sursa oficială: interogarea rovinietei validează împreună numărul de înmatriculare, VIN-ul și numărul certificatului de înmatriculare. Fără el, cererea e respinsă înainte să plece, fără să consume din cotă. Pentru vehiculele din cont, adaugă `serieTalon` la `auto.flota.adauga()`, altfel rovinieta lor nu se monitorizează.
|
|
518
|
+
|
|
519
|
+
### De unde vin datele?
|
|
520
|
+
|
|
521
|
+
Din sursele oficiale: AIDA (baza de date a asigurărilor RCA administrată de BAAR), Registrul Auto Român pentru ITP, CNAIR pentru rovinietă și Autoritatea Rutieră Română pentru copia conformă. Nu estimăm nimic: fiecare rezultat e exact ce a răspuns sursa.
|
|
522
|
+
|
|
523
|
+
### De ce o poliță RCA nouă apare ca expirată?
|
|
524
|
+
|
|
525
|
+
Asigurătorul are nevoie de timp ca să înregistreze polița nouă în AIDA, de obicei între 1 și 7 zile. În acest interval verificarea poate arăta polița veche. Detalii despre [amenzile pentru RCA expirat](https://acteo.ro/amenzi/rca).
|
|
526
|
+
|
|
527
|
+
### Merge în browser?
|
|
528
|
+
|
|
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.
|
|
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
|
+
|
|
539
|
+
### Există SDK pentru PHP sau Python?
|
|
540
|
+
|
|
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.
|
|
542
|
+
|
|
543
|
+
## Linkuri utile
|
|
544
|
+
|
|
545
|
+
- [Documentația API Acteo](https://acteo.ro/api-acces)
|
|
546
|
+
- [Verificare RCA online](https://acteo.ro/verificare-rca)
|
|
547
|
+
- [Verificare ITP online](https://acteo.ro/verificare-itp)
|
|
548
|
+
- [Verificare rovinietă online](https://acteo.ro/verificare-rovinieta)
|
|
549
|
+
- [Verificare copie conformă ARR](https://acteo.ro/verificare-arr)
|
|
550
|
+
- [Monitorizare flote auto](https://acteo.ro/flote)
|
|
551
|
+
- [Changelog](./CHANGELOG.md)
|
|
552
|
+
|
|
553
|
+
## Dezvoltare
|
|
554
|
+
|
|
555
|
+
```bash
|
|
556
|
+
pnpm install
|
|
557
|
+
pnpm test # teste unitare, fără rețea
|
|
558
|
+
pnpm test:e2e # teste pe API-ul real
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
Testele e2e citesc configurarea din `.env.e2e`, fișier ignorat de git. Pornești de la șablon:
|
|
562
|
+
|
|
563
|
+
```bash
|
|
564
|
+
cp .env.e2e.example .env.e2e
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Fără cheie rulează doar testul de autentificare. Cu `ACTEO_API_KEY` se adaugă listarea vehiculelor, care e gratuită. Verificările reale (`ACTEO_E2E_VERIFICARI=1`) consumă din cotă, iar testul de flotă (`ACTEO_E2E_FLOTA=1`) adaugă și șterge un vehicul. Amândouă pornesc doar dacă le activezi explicit.
|
|
568
|
+
|
|
569
|
+
## Licență
|
|
570
|
+
|
|
571
|
+
[MIT](./LICENSE), © Acteo.ro
|