@acteo/api 0.0.0-stage → 0.3.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 +34 -0
- package/LICENSE +21 -0
- package/README.md +492 -2
- package/dist/index.cjs +1249 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1058 -0
- package/dist/index.d.ts +1058 -0
- package/dist/index.js +1211 -0
- package/dist/index.js.map +1 -0
- package/package.json +105 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## @acteo/api 0.3.0 (2026-10-29)
|
|
4
|
+
|
|
5
|
+
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.
|
|
6
|
+
|
|
7
|
+
- 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.
|
|
8
|
+
- La RCA, un text de 17 caractere fără I, O și Q e tratat ca VIN. Cu ambele date: `{ numar, vin }`.
|
|
9
|
+
- `acteo.auto.flota` pentru vehiculele din cont și `acteo.webhooks` pentru webhook-uri.
|
|
10
|
+
- Adresa implicită este `https://api.acteo.ro`. Cheia se citește din `ACTEO_API_KEY`, apoi din `VERIFICRCA_API_KEY`.
|
|
11
|
+
- `ActeoError`, clasa de bază a erorilor (aceeași cu `VerificRcaError`).
|
|
12
|
+
- Clientul `VerificRca` și apelurile de până acum funcționează în continuare, cu aceeași adresă implicită.
|
|
13
|
+
|
|
14
|
+
## 0.2.0 (2026-10-09)
|
|
15
|
+
|
|
16
|
+
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ă.
|
|
17
|
+
|
|
18
|
+
- `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.
|
|
19
|
+
- `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ă.
|
|
20
|
+
- `Vehicul` are câmpurile noi `serieTalon` (`string | null`) și `serieTalonRespinsa` (`boolean`).
|
|
21
|
+
- `vehicule.adauga` acceptă `serieTalon`, necesar pentru monitorizarea automată a rovinietei.
|
|
22
|
+
- Utilitare noi: `esteSerieTalonValida` și `normalizeazaSerieTalon`.
|
|
23
|
+
- `VERSIUNE_SDK` (trimisă în `User-Agent`) urmează din nou versiunea pachetului.
|
|
24
|
+
|
|
25
|
+
## 0.1.0 (2026-09-29)
|
|
26
|
+
|
|
27
|
+
Prima versiune.
|
|
28
|
+
|
|
29
|
+
- Client `VerificRca` cu `verificari.porneste`, `rezultat`, `asteapta` si `verificaSiAsteapta` pentru RCA, ITP, rovinieta si ARR.
|
|
30
|
+
- Gestionarea flotei: `vehicule.lista`, `adauga`, `sterge`.
|
|
31
|
+
- Webhook-uri: `parseazaWebhookRezultat` si `verificaWebhookNotificare` (cheie comparata in timp constant).
|
|
32
|
+
- Validare locala a numarului de inmatriculare si a VIN-ului, cu aceleasi reguli ca API-ul.
|
|
33
|
+
- Erori tipate, retry cu backoff exponential si jitter, `Retry-After` respectat, niciun POST taxat repetat.
|
|
34
|
+
- 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,493 @@
|
|
|
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 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 ș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
|
+
| Webhook-uri | `acteo.webhooks` | Rezultatul verificării la URL-ul tău, alerte `document.expira` la 30, 14 și 3 zile |
|
|
50
|
+
| 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
|
+
| Erori tipate | | O clasă de eroare pentru fiecare situație, cu mesaj în română și `hint` de rezolvare |
|
|
52
|
+
| Reîncercări sigure | | Backoff exponențial cu jitter, `Retry-After` respectat, niciun POST taxat de două ori |
|
|
53
|
+
|
|
54
|
+
## Instalare
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install @acteo/api
|
|
58
|
+
# sau
|
|
59
|
+
pnpm add @acteo/api
|
|
60
|
+
# sau
|
|
61
|
+
yarn add @acteo/api
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Cheia API o poți da direct în constructor sau prin variabila de mediu `ACTEO_API_KEY`:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
export ACTEO_API_KEY=cheia_ta_api
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
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.
|
|
71
|
+
|
|
72
|
+
## Pornire rapidă
|
|
73
|
+
|
|
74
|
+
### Verificare RCA după număr de înmatriculare
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { Acteo } from "@acteo/api"
|
|
78
|
+
|
|
79
|
+
const acteo = new Acteo() // citește ACTEO_API_KEY
|
|
80
|
+
|
|
81
|
+
const rca = await acteo.auto.rca.verifica("B 123 ABC")
|
|
82
|
+
|
|
83
|
+
if (rca.status === "expired") {
|
|
84
|
+
console.log("Mașina nu are RCA valabil.")
|
|
85
|
+
} else if (rca.status === "warning") {
|
|
86
|
+
console.log(`RCA-ul expiră curând, pe ${rca.expiresAt?.toLocaleDateString("ro-RO")}`)
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
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:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
await acteo.auto.rca.verifica({ numar: "B123ABC", vin: "WVWZZZ1JZXW000001" })
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### Verificare ITP după serie de șasiu
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
const itp = await acteo.auto.itp.verifica("WVWZZZ1JZXW000001")
|
|
100
|
+
console.log(`ITP valabil până la ${itp.expiresAt?.toLocaleDateString("ro-RO")}`)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Verificare rovinietă
|
|
104
|
+
|
|
105
|
+
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ă.
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
const rovinieta = await acteo.auto.rovinieta.verifica({
|
|
109
|
+
numar: "B123ABC",
|
|
110
|
+
vin: "WVWZZZ1JZXW000001",
|
|
111
|
+
serieTalon: "I00639603F",
|
|
112
|
+
})
|
|
113
|
+
console.log(rovinieta.status, rovinieta.expiresAt)
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
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:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { EroareVerificare } from "@acteo/api"
|
|
120
|
+
|
|
121
|
+
try {
|
|
122
|
+
await acteo.auto.rovinieta.verifica({ numar: "B123ABC", vin, serieTalon: talon })
|
|
123
|
+
} catch (err) {
|
|
124
|
+
if (err instanceof EroareVerificare && err.codSursa === "serie_talon_invalida") {
|
|
125
|
+
return cereUtilizatoruluiNumarulTalonului()
|
|
126
|
+
}
|
|
127
|
+
throw err
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Verificare copie conformă ARR
|
|
132
|
+
|
|
133
|
+
```ts
|
|
134
|
+
const arr = await acteo.auto.arr.verifica("CJ45XYZ")
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Ce identificator cere fiecare verificare
|
|
138
|
+
|
|
139
|
+
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.
|
|
140
|
+
|
|
141
|
+
| Apel | Ce primește | Sursa |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| `auto.rca.verifica(x)` | număr de înmatriculare **sau** VIN, ori `{ numar, vin }` (recomandat) | AIDA / BAAR |
|
|
144
|
+
| `auto.itp.verifica(vin)` | VIN (17 caractere) | RAR |
|
|
145
|
+
| `auto.rovinieta.verifica({ numar, vin, serieTalon })` | toate trei, **obligatorii** | CNAIR |
|
|
146
|
+
| `auto.arr.verifica(numar)` | număr de înmatriculare | ARR |
|
|
147
|
+
|
|
148
|
+
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).
|
|
149
|
+
|
|
150
|
+
`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.
|
|
151
|
+
|
|
152
|
+
## Cum decurge o verificare
|
|
153
|
+
|
|
154
|
+
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"`.
|
|
155
|
+
2. **Interogarea sursei.** Sursa oficială e consultată în fundal. Dacă nu răspunde în 4 minute, verificarea se încheie cu eroare.
|
|
156
|
+
3. **Rezultatul** ajunge la tine pe una din trei căi:
|
|
157
|
+
- `verifica()` face tot drumul și întoarce direct rezultatul final;
|
|
158
|
+
- `rezultat()` sau `asteapta()` fac polling, fără să consume din cotă;
|
|
159
|
+
- webhook: dacă trimiți `callbackUrl` la `porneste()`, API-ul face POST cu rezultatul la adresa ta.
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
### Statusuri
|
|
164
|
+
|
|
165
|
+
| `status` | Înseamnă | `expiresAt` |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `valid` | Document valabil | data expirării |
|
|
168
|
+
| `warning` | Expiră curând: RCA în 14 zile, ITP în 30, rovinietă în 7, ARR în 14 | data expirării |
|
|
169
|
+
| `expired` | Expirat sau inexistent, confirmat de sursă | data expirării sau `null` |
|
|
170
|
+
| `not_found` | Sursa nu a găsit vehiculul | `null` |
|
|
171
|
+
| `processing` | Verificarea e încă în curs | nu există |
|
|
172
|
+
|
|
173
|
+
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:
|
|
174
|
+
|
|
175
|
+
| `codSursa` | Câmpul de corectat |
|
|
176
|
+
|---|---|
|
|
177
|
+
| `serie_talon_invalida` | `serieTalon`, numărul certificatului de înmatriculare |
|
|
178
|
+
| `vin_invalid` | `vin` |
|
|
179
|
+
| `numar_invalid` | numărul de înmatriculare |
|
|
180
|
+
|
|
181
|
+
## Referință API
|
|
182
|
+
|
|
183
|
+
### `new Acteo(optiuni?)`
|
|
184
|
+
|
|
185
|
+
| Opțiune | Tip | Implicit | Descriere |
|
|
186
|
+
|---|---|---|---|
|
|
187
|
+
| `apiKey` | `string` | `process.env.ACTEO_API_KEY` | Cheia API |
|
|
188
|
+
| `baseUrl` | `string` | `https://api.acteo.ro` | Adresa API-ului |
|
|
189
|
+
| `timeoutMs` | `number` | `30000` | Timeout pe fiecare cerere HTTP |
|
|
190
|
+
| `retry` | `object \| false` | `{ incercari: 3, intarziereInitialaMs: 500, intarziereMaximaMs: 10000 }` | Politica de reîncercare; `false` o oprește |
|
|
191
|
+
| `fetch` | `typeof fetch` | `globalThis.fetch` | Alt `fetch` (proxy, agent HTTP, teste) |
|
|
192
|
+
| `userAgent` | `string` | | Adăugat la `User-Agent`, util în loguri |
|
|
193
|
+
|
|
194
|
+
Constructorul aruncă `EroareConfigurare` dacă lipsește cheia sau dacă o opțiune e invalidă.
|
|
195
|
+
|
|
196
|
+
Toate metodele primesc ca ultim argument `{ signal?: AbortSignal }`. Cu el poți anula cererea împreună cu reîncercările și așteptarea ei.
|
|
197
|
+
|
|
198
|
+
### `auto.<document>.verifica(identificator, optiuni?)`
|
|
199
|
+
|
|
200
|
+
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"`.
|
|
201
|
+
|
|
202
|
+
### `auto.<document>.porneste(identificator, { callbackUrl? })`
|
|
203
|
+
|
|
204
|
+
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()`.
|
|
205
|
+
|
|
206
|
+
```ts
|
|
207
|
+
const r = await acteo.auto.itp.porneste("WVWZZZ1JZXW000001", {
|
|
208
|
+
callbackUrl: "https://example.com/webhooks/acteo/9f3k2", // opțional
|
|
209
|
+
})
|
|
210
|
+
|
|
211
|
+
if (r.status === "processing") {
|
|
212
|
+
console.log("În coadă, requestId:", r.requestId)
|
|
213
|
+
const final = await acteo.auto.itp.asteapta(r)
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### `auto.<document>.rezultat(referinta)`
|
|
218
|
+
|
|
219
|
+
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")`.
|
|
220
|
+
|
|
221
|
+
### `auto.<document>.asteapta(referinta, optiuni?)`
|
|
222
|
+
|
|
223
|
+
Face polling până la rezultatul final, cu aceleași opțiuni ca `verifica()`. Nu consumă din cotă.
|
|
224
|
+
|
|
225
|
+
### `auto.flota.lista()`
|
|
226
|
+
|
|
227
|
+
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.
|
|
228
|
+
|
|
229
|
+
### `auto.flota.adauga({ numarInmatriculare?, serieSasiu?, serieTalon?, arrMonitorizat? })`
|
|
230
|
+
|
|
231
|
+
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ă.
|
|
232
|
+
|
|
233
|
+
```ts
|
|
234
|
+
const v = await acteo.auto.flota.adauga({
|
|
235
|
+
numarInmatriculare: "B123ABC",
|
|
236
|
+
serieSasiu: "WVWZZZ1JZXW000001",
|
|
237
|
+
serieTalon: "I00639603F",
|
|
238
|
+
})
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
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.
|
|
242
|
+
|
|
243
|
+
### `auto.flota.sterge(id)`
|
|
244
|
+
|
|
245
|
+
Scoate vehiculul din cont. Aruncă `EroareNegasit` dacă ID-ul nu există în contul cheii.
|
|
246
|
+
|
|
247
|
+
Operațiile pe flotă nu consumă din cota de verificări, dar cer un plan activ.
|
|
248
|
+
|
|
249
|
+
### Utilitare de validare
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
import {
|
|
253
|
+
esteNumarInmatriculareValid,
|
|
254
|
+
esteSerieTalonValida,
|
|
255
|
+
esteVinValid,
|
|
256
|
+
normalizeaza,
|
|
257
|
+
normalizeazaSerieTalon,
|
|
258
|
+
} from "@acteo/api"
|
|
259
|
+
|
|
260
|
+
esteNumarInmatriculareValid("CJ 45 XYZ") // true
|
|
261
|
+
esteVinValid("WVWZZZ1JZXW00000I") // false: litera I nu e permisă în VIN
|
|
262
|
+
esteSerieTalonValida("I00639603F") // true
|
|
263
|
+
normalizeaza(" b-123 abc ") // "B123ABC"
|
|
264
|
+
normalizeazaSerieTalon("i 00639603-f") // "I00639603F"
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Le poți folosi pentru formularele tale, ca să validezi datele înainte să ajungă la server.
|
|
268
|
+
|
|
269
|
+
### Constante exportate
|
|
270
|
+
|
|
271
|
+
| Constantă | Valoare |
|
|
272
|
+
|---|---|
|
|
273
|
+
| `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 |
|
|
276
|
+
| `URL_IMPLICIT` | `"https://api.acteo.ro"` |
|
|
277
|
+
| `VERSIUNE_SDK` | versiunea pachetului, trimisă în `User-Agent` |
|
|
278
|
+
|
|
279
|
+
### Documentația completă a tipurilor
|
|
280
|
+
|
|
281
|
+
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/`.
|
|
282
|
+
|
|
283
|
+
## Webhook-uri
|
|
284
|
+
|
|
285
|
+
API-ul trimite două feluri de webhook. SDK-ul le validează cu scheme stricte și îți dă obiecte tipate, cu datele ca `Date`.
|
|
286
|
+
|
|
287
|
+
### Rezultatul unei verificări (`callbackUrl`)
|
|
288
|
+
|
|
289
|
+
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"`.
|
|
290
|
+
|
|
291
|
+
```ts
|
|
292
|
+
app.post("/webhooks/acteo/9f3k2", express.raw({ type: "application/json" }), (req, res) => {
|
|
293
|
+
const r = acteo.webhooks.parseazaRezultat(req.body) // string, Buffer sau obiect
|
|
294
|
+
if (r.status !== "error") salveaza(r.requestId, r.result?.expiresAt)
|
|
295
|
+
res.sendStatus(200)
|
|
296
|
+
})
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
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
|
+
|
|
301
|
+
### Notificări de expirare (`document.expira`)
|
|
302
|
+
|
|
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:
|
|
304
|
+
|
|
305
|
+
```ts
|
|
306
|
+
import { EroareWebhook } from "@acteo/api"
|
|
307
|
+
|
|
308
|
+
app.post("/webhooks/acteo", express.raw({ type: "application/json" }), (req, res) => {
|
|
309
|
+
try {
|
|
310
|
+
const ev = acteo.webhooks.verificaNotificare(req.body, req.headers, { cheie: process.env.ACTEO_WEBHOOK_KEY! })
|
|
311
|
+
if (ev.event === "document.expira") {
|
|
312
|
+
trimiteAlerta(`${ev.vehicul.numarInmatriculare}: ${ev.document} expiră în ${ev.zileRamase} zile`)
|
|
313
|
+
}
|
|
314
|
+
res.sendStatus(200)
|
|
315
|
+
} catch (err) {
|
|
316
|
+
res.sendStatus(err instanceof EroareWebhook ? 401 : 500)
|
|
317
|
+
}
|
|
318
|
+
})
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
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
|
+
|
|
323
|
+
## Erori
|
|
324
|
+
|
|
325
|
+
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.
|
|
326
|
+
|
|
327
|
+
| Clasă | Când apare | Câmpuri utile |
|
|
328
|
+
|---|---|---|
|
|
329
|
+
| `EroareConfigurare` | Cheie lipsă sau opțiuni invalide | |
|
|
330
|
+
| `EroareValidare` | Date greșite, local sau HTTP 400 | `camp`, `acceptate` |
|
|
331
|
+
| `EroareAutentificare` | 401: cheie invalidă sau dezactivată | `hint` |
|
|
332
|
+
| `EroarePlanInactiv` | 402: fără abonament activ | `hint` |
|
|
333
|
+
| `EroareInterzis` | 403: `LIMIT_ATINS`, `ARR_NECESITA_PLAN` | `cod`, `limita` |
|
|
334
|
+
| `EroareNegasit` | 404: vehicul inexistent în cont | |
|
|
335
|
+
| `EroareConflict` | 409: `VEHICUL_EXISTENT` | |
|
|
336
|
+
| `EroareLimita` | 429: cotă, plafon de flotă sau polling prea des | `cod`, `retryAfterMs`, `utilizareZi`, `utilizareLuna` |
|
|
337
|
+
| `EroareServer` | 5xx | `status` |
|
|
338
|
+
| `EroareRetea` | Fără răspuns sau timeout | `timeout`, `neajunsa` |
|
|
339
|
+
| `EroareRaspunsInvalid` | Răspuns cu formă neașteptată | `raspuns` |
|
|
340
|
+
| `EroareVerificare` | Sursa oficială nu a putut fi interogată sau a refuzat datele | `codSursa` |
|
|
341
|
+
| `EroareTimeoutVerificare` | `asteapta()` a depășit `timeoutMs` | |
|
|
342
|
+
| `EroareWebhook` | Cheie greșită sau payload invalid | `cod` |
|
|
343
|
+
|
|
344
|
+
```ts
|
|
345
|
+
import { ActeoError, EroareLimita, EroareValidare } from "@acteo/api"
|
|
346
|
+
|
|
347
|
+
try {
|
|
348
|
+
await acteo.auto.rca.porneste(numar)
|
|
349
|
+
} catch (err) {
|
|
350
|
+
if (err instanceof EroareValidare) return arataUtilizatorului(err.message)
|
|
351
|
+
if (err instanceof EroareLimita && err.cod === "COTA_ATINSA") return amanaPanaMaine()
|
|
352
|
+
if (err instanceof ActeoError) logger.error(err._tag, err.message, err.hint)
|
|
353
|
+
throw err
|
|
354
|
+
}
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
## Reîncercări, backoff și timeout
|
|
358
|
+
|
|
359
|
+
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ă.
|
|
360
|
+
|
|
361
|
+
SDK-ul nu trimite niciodată de două ori o verificare taxată.
|
|
362
|
+
|
|
363
|
+
| Situație | GET / DELETE | POST |
|
|
364
|
+
|---|---|---|
|
|
365
|
+
| Rețea căzută, timeout | se reîncearcă | nu (cererea poate să fi ajuns) |
|
|
366
|
+
| 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) |
|
|
368
|
+
| 500 | se reîncearcă | nu |
|
|
369
|
+
| 429 la polling | se reîncearcă după `Retry-After` | |
|
|
370
|
+
| 429 cotă sau plafon flotă | nu | nu |
|
|
371
|
+
| 4xx | nu | nu |
|
|
372
|
+
|
|
373
|
+
```ts
|
|
374
|
+
const acteo = new Acteo({
|
|
375
|
+
timeoutMs: 15_000,
|
|
376
|
+
retry: { incercari: 5, intarziereInitialaMs: 250, intarziereMaximaMs: 8_000 },
|
|
377
|
+
})
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
## Cotă și limite
|
|
381
|
+
|
|
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.
|
|
383
|
+
|
|
384
|
+
Rezultatele au câmpul `limite`, completat din headerele `X-RateLimit-*`:
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
const r = await acteo.auto.rca.porneste("B123ABC")
|
|
388
|
+
console.log(r.limite) // { zi: { limita: 300, ramase: 287 }, luna: { limita: 10000, ramase: 9412 } }
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
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).
|
|
392
|
+
|
|
393
|
+
## Exemple
|
|
394
|
+
|
|
395
|
+
Folderul [`examples/`](./examples) conține scripturi gata de rulat:
|
|
396
|
+
|
|
397
|
+
- [`verificare-rca.ts`](./examples/verificare-rca.ts): verificare RCA cu număr și VIN, tratarea erorilor;
|
|
398
|
+
- [`flota.ts`](./examples/flota.ts): raport cu RCA, ITP, rovinietă și ARR care expiră în 30 de zile, pentru toată flota;
|
|
399
|
+
- [`webhook-server.ts`](./examples/webhook-server.ts): server `node:http` care primește ambele tipuri de webhook.
|
|
400
|
+
|
|
401
|
+
### Verificare în masă
|
|
402
|
+
|
|
403
|
+
```ts
|
|
404
|
+
const numere = ["B123ABC", "CJ45XYZ", "IS08BCD"]
|
|
405
|
+
|
|
406
|
+
const rezultate = await Promise.allSettled(
|
|
407
|
+
numere.map((numar) => acteo.auto.rca.verifica(numar)),
|
|
408
|
+
)
|
|
409
|
+
```
|
|
410
|
+
|
|
411
|
+
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.
|
|
412
|
+
|
|
413
|
+
## Vii de la @verificrca/sdk?
|
|
414
|
+
|
|
415
|
+
Pachetul `@verificrca/sdk` s-a mutat la `@acteo/api`. Instalezi pachetul nou și schimbi apelurile:
|
|
416
|
+
|
|
417
|
+
| Înainte | Acum |
|
|
418
|
+
|---|---|
|
|
419
|
+
| `new VerificRca()` | `new Acteo()` |
|
|
420
|
+
| `VERIFICRCA_API_KEY` | `ACTEO_API_KEY` (cea veche e citită în continuare, dacă lipsește cea nouă) |
|
|
421
|
+
| `verificari.verificaSiAsteapta({ tip: "rca", query })` | `auto.rca.verifica(query)` |
|
|
422
|
+
| `verificari.verificaSiAsteapta({ tip: "itp", query: vin })` | `auto.itp.verifica(vin)` |
|
|
423
|
+
| `verificari.verificaSiAsteapta({ tip: "rovinieta", query, serieSasiu, serieTalon })` | `auto.rovinieta.verifica({ numar, vin, serieTalon })` |
|
|
424
|
+
| `verificari.porneste(...)` / `rezultat(...)` / `asteapta(...)` | `auto.<document>.porneste` / `rezultat` / `asteapta` |
|
|
425
|
+
| `vehicule.lista()` / `adauga()` / `sterge()` | `auto.flota.lista()` / `adauga()` / `sterge()` |
|
|
426
|
+
| `parseazaWebhookRezultat()` / `verificaWebhookNotificare()` | `webhooks.parseazaRezultat()` / `webhooks.verificaNotificare()` |
|
|
427
|
+
| `VerificRcaError` | `ActeoError` |
|
|
428
|
+
|
|
429
|
+
Erorile, tipurile rezultatelor și utilitarele de validare au rămas aceleași.
|
|
430
|
+
|
|
431
|
+
## Întrebări frecvente
|
|
432
|
+
|
|
433
|
+
### Cum verific RCA-ul unei mașini din Node.js?
|
|
434
|
+
|
|
435
|
+
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.
|
|
436
|
+
|
|
437
|
+
### Pot verifica ITP-ul după numărul de înmatriculare?
|
|
438
|
+
|
|
439
|
+
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.
|
|
440
|
+
|
|
441
|
+
### Unde găsesc numărul certificatului de înmatriculare?
|
|
442
|
+
|
|
443
|
+
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ă.
|
|
444
|
+
|
|
445
|
+
### De ce verificarea rovinietei cere numărul talonului?
|
|
446
|
+
|
|
447
|
+
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ă.
|
|
448
|
+
|
|
449
|
+
### De unde vin datele?
|
|
450
|
+
|
|
451
|
+
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.
|
|
452
|
+
|
|
453
|
+
### De ce o poliță RCA nouă apare ca expirată?
|
|
454
|
+
|
|
455
|
+
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).
|
|
456
|
+
|
|
457
|
+
### Merge în browser?
|
|
458
|
+
|
|
459
|
+
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
|
+
|
|
461
|
+
### Există SDK pentru PHP sau Python?
|
|
462
|
+
|
|
463
|
+
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.
|
|
464
|
+
|
|
465
|
+
## Linkuri utile
|
|
466
|
+
|
|
467
|
+
- [Documentația API Acteo](https://acteo.ro/api-acces)
|
|
468
|
+
- [Verificare RCA online](https://acteo.ro/verificare-rca)
|
|
469
|
+
- [Verificare ITP online](https://acteo.ro/verificare-itp)
|
|
470
|
+
- [Verificare rovinietă online](https://acteo.ro/verificare-rovinieta)
|
|
471
|
+
- [Verificare copie conformă ARR](https://acteo.ro/verificare-arr)
|
|
472
|
+
- [Monitorizare flote auto](https://acteo.ro/flote)
|
|
473
|
+
- [Changelog](./CHANGELOG.md)
|
|
474
|
+
|
|
475
|
+
## Dezvoltare
|
|
476
|
+
|
|
477
|
+
```bash
|
|
478
|
+
pnpm install
|
|
479
|
+
pnpm test # teste unitare, fără rețea
|
|
480
|
+
pnpm test:e2e # teste pe API-ul real
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
Testele e2e citesc configurarea din `.env.e2e`, fișier ignorat de git. Pornești de la șablon:
|
|
484
|
+
|
|
485
|
+
```bash
|
|
486
|
+
cp .env.e2e.example .env.e2e
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
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.
|
|
490
|
+
|
|
491
|
+
## Licență
|
|
492
|
+
|
|
493
|
+
[MIT](./LICENSE), © Acteo.ro
|