@acteo/api 0.4.1 → 0.6.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,42 @@
1
1
  # Changelog
2
2
 
3
+ ## @acteo/api 0.6.0 (2026-11-19)
4
+
5
+ - `acteo.casa.pad`: verificarea poliței PAD a unei locuințe, după CNP-ul proprietarului și localitate, cu răspunsul de la PADROM. Metodele sunt cele de la documentele auto: `verifica()`, `porneste()` (cu `callbackUrl` opțional), `rezultat()` și `asteapta()`. Cere abonamentul API Verificare poliță PAD și acordul proprietarului (`acord: true`).
6
+ - CNP-ul, acordul, data și `callbackUrl` sunt validate local, înainte de cerere, deci o greșeală nu consumă din cotă. Răspunsurile arată CNP-ul doar mascat (`cnpMascat`).
7
+ - `acteo.webhooks.parseazaRezultatPad()` și `parseazaWebhookRezultatPad()` citesc rezultatul trimis la `callbackUrl`.
8
+ - `esteCnpValid()` verifică local forma unui CNP: data de naștere și cifra de control.
9
+ - Tipuri noi: `CererePolitaPad`, `PolitaPadPornita`, `PolitaPadInCurs`, `PolitaPadGata`, `RezultatPolitaPad`, `ReferintaPolitaPad`, `WebhookRezultatPad`.
10
+ - `acteo.programari`: trimiți programarea unui client, iar el primește remindere pe email. Metode: `creeaza()` (POST, cu `idExtern` opțional; `creata: false` când programarea exista și a fost actualizată), `lista()` (opțiuni `din`, `pana`, `cursor`, `limita`; răspuns `{ programari, urmatorulCursor }`), `obtine()`, `actualizeaza()` (PUT, doar câmpurile trimise) și `anuleaza()` (DELETE). `incepeLa`, `din` și `pana` acceptă text ISO cu fus orar sau `Date`. Cere abonamentul API Programări.
11
+ - `creeaza()` și `actualizeaza()` nu se repetă singure după un răspuns de la API, ca o programare sau un reminder să nu plece de două ori. `obtine()`, `lista()` și `anuleaza()` se reîncearcă, inclusiv la `PREA_MULTE_CERERI` după `Retry-After`.
12
+ - Coduri de eroare noi în `CODURI_EROARE`: `CULOARE_NECUNOSCUTA`, `PROFIL_EXPEDITOR_LIPSA` și `ADRESA_AFACERII_LIPSA` (`EroareValidare`, 422), `CLIENT_INDISPONIBIL` (`EroareConflict`, 409) și `PREA_MULTE_CERERI` (`EroareLimita`, 429, netaxat).
13
+ - `verificaNotificare()` validează evenimentele `programare.confirmata`, `programare.confirmare_expirata` și `programare.client_dezabonat`.
14
+ - Programări: termen de confirmare și „văzut". `creeaza()` și `actualizeaza()` acceptă `confirmareInMaximOre` (cât timp are clientul de la primirea programării) și `confirmareCuMinimOreInainte` (cu cât timp înainte de programare trebuie să confirme), în ore, între 1 și 720, doar cu `necesitaConfirmare: true`; `null` le șterge la modificare. `Programare` are în plus `confirmareInMaximOre`, `confirmareCuMinimOreInainte`, `confirmareExpiraLa`, `confirmareExpirataLa` și `vazutLa` (`vazutLa`: când a deschis clientul programarea). Un răspuns care nu le conține se citește cu `null`. Evenimentul `programare.confirmare_expirata` (`WebhookProgramareConfirmareExpirata`) anunță că termenul a trecut fără confirmare; programarea nu se anulează singură.
15
+ - Programări: câmpul `cuCine`, la cine e programarea când afacerea are mai mulți oameni (medicul, frizerul, consultantul), cel mult 120 de caractere. Clientul îl vede în remindere și în calendar. `creeaza()` și `actualizeaza()` îl acceptă, iar `null` îl șterge la modificare. `Programare` are în plus `cuCine`; un răspuns care nu îl conține se citește cu `null`.
16
+ - Tipuri noi: `Programare`, `ProgramareTrimisa`, `CerereProgramare`, `ModificareProgramare`, `OptiuniListaProgramari`, `ListaProgramari`, `DataProgramare`, `MomentReminder`, `WebhookProgramareConfirmata`, `WebhookProgramareClientDezabonat`. Clasa nouă: `ClientProgramari`.
17
+ - Webhook-ul `termen.expira` acceptă și `prag: 7`, trimis în loc de 30 la termenele care se repetă la cel mult 3 luni. Până acum `verificaNotificare()` îl respingea ca payload invalid. `termen.categorie` poate fi și `animale`.
18
+ - API-ul de programări e gratuit: nu cere abonament și nu are limită de clienți. La `creeaza()` și `actualizeaza()`, `EroareLimita` mai vine doar cu `LIMIT_ATINS` (clienți noi fără cont invitați azi) sau `PREA_MULTE_CERERI`.
19
+
20
+ ## @acteo/api 0.5.0 (2026-11-03)
21
+
22
+ API-ul trimite acum codurile de eroare din contract. Dacă ai cod care compară `err.cod` cu valorile vechi, schimbă-l după tabelul de mai jos. Clasele de eroare și statusurile HTTP rămân aceleași.
23
+
24
+ | Situație | Cod vechi | Cod nou |
25
+ |---|---|---|
26
+ | Limita zilnică a planului atinsă (429) | `COTA_ATINSA` la verificări, `LIMIT_ATINS` la VIN, numere și poze | `DAILY_LIMIT_REACHED` |
27
+ | Limita lunară sau plafonul consumului peste plan atins (429) | `COTA_ATINSA` la verificări, `LIMIT_ATINS` la VIN, numere și poze | `PLAN_LIMIT_REACHED` |
28
+ | DGPCI refuză numărul (422) | `NUMAR_RESPINS` | `INVALID_IDENTIFIER` |
29
+ | DGPCI nu răspunde la timp (504) | `TIMEOUT` | `UPSTREAM_TIMEOUT` |
30
+ | Verificarea la DGPCI eșuează (502) | `EROARE_DGPCI` | `UPSTREAM_UNAVAILABLE` |
31
+ | Verificare încheiată cu `status: "error"` | `VERIFICARE_ESUATA` | `INVALID_IDENTIFIER`, `UPSTREAM_UNAVAILABLE`, `UPSTREAM_TIMEOUT`, `UPSTREAM_BLOCKED` sau `UPSTREAM_CHANGED` |
32
+
33
+ - `CODURI_EROARE` și tipul `CodEroare`: toate codurile pe care le trimite API-ul. `CodEsecVerificare` are motivele unei verificări eșuate.
34
+ - `EroareVerificare.cod` spune de ce a eșuat verificarea. `codSursa` rămâne și arată câmpul refuzat la `INVALID_IDENTIFIER`.
35
+ - Rezultatul `not_found` are `code: "NOT_FOUND"`, iar webhook-ul de rezultat are `code` la eroare și la `not_found`.
36
+ - Pornirea unei verificări sau a unei verificări de număr poate primi `EroareServer` 503 cu `UPSTREAM_BLOCKED` sau `UPSTREAM_CHANGED` când sursa oficială e oprită temporar. Cererea nu se taxează și nu se repetă singură; `retryAfterMs` spune când să revii.
37
+ - `DAILY_LIMIT_REACHED` vine cu `retryAfterMs` până la miezul nopții, ora României. `PLAN_LIMIT_REACHED` nu are `retryAfterMs`, pentru că nu se deblochează la miezul nopții.
38
+ - Un server mai vechi, fără coduri, dă în continuare `COTA_ATINSA` și `VERIFICARE_ESUATA`.
39
+
3
40
  ## @acteo/api 0.4.1 (2026-10-31)
4
41
 
5
42
  - Documentație: fiecare verificare interoghează sursa oficială. `porneste()` întoarce o verificare în curs, iar rezultatul vine prin `asteapta()`, `rezultat()` sau webhook. `checkedAt` e descris ca momentul verificării. Codul nu se schimbă.
package/README.md CHANGED
@@ -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, `acteo.auto.vin`, `acteo.auto.numere` și `acteo.auto.imagini` pentru celelalte produse ș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, `acteo.casa.pad` pentru polița PAD a unei locuințe, `acteo.programari` pentru programările trimise clienților tăi și `acteo.webhooks` pentru notificări.
23
23
 
24
24
  ## Cuprins
25
25
 
@@ -49,6 +49,8 @@ Apelurile sunt grupate pe domeniu și pe document, deci citești din cod ce veri
49
49
  | Decodare VIN | `acteo.auto.vin.decodeaza()` | Marca, modelul, anul de fabricație și structura seriei de șasiu |
50
50
  | Număr de înmatriculare disponibil | `acteo.auto.numere.verifica()` | Dacă numărul e liber la DGPCI și poate fi rezervat |
51
51
  | Poza unei mașini | `acteo.auto.imagini.obtine()` | Link spre o poză de studio (WebP transparent) după marcă, model și an |
52
+ | Verificare poliță PAD | `acteo.casa.pad.verifica()` | Dacă o locuință are poliță PAD valabilă la o dată, după CNP-ul proprietarului și localitate, de la PADROM |
53
+ | Programări cu remindere | `acteo.programari` | Trimiți programarea unui client, iar el primește remindere pe email cu 7 zile, cu o zi și cu 3 ore înainte; o listezi, o muți sau o anulezi |
52
54
  | 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
55
  | 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
56
  | Erori tipate | | O clasă de eroare pentru fiecare situație, cu mesaj în română și `hint` de rezolvare |
@@ -116,7 +118,7 @@ const rovinieta = await acteo.auto.rovinieta.verifica({
116
118
  console.log(rovinieta.status, rovinieta.expiresAt)
117
119
  ```
118
120
 
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:
121
+ Dacă sursa respinge datele (de exemplu, numărul talonului nu corespunde mașinii), primești `EroareVerificare` cu `cod: "INVALID_IDENTIFIER"` și `codSursa: "serie_talon_invalida"`. O reîncercare cu aceleași date nu ajută; corectează întâi câmpul indicat:
120
122
 
121
123
  ```ts
122
124
  import { EroareVerificare } from "@acteo/api"
@@ -168,6 +170,36 @@ const gata = await acteo.auto.imagini.asteapta({ marca: "Volkswagen", model: "Go
168
170
 
169
171
  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
172
 
173
+ ### Trimite o programare unui client
174
+
175
+ ```ts
176
+ const p = await acteo.programari.creeaza({
177
+ idExtern: "rez-2027-0042", // id-ul din programul tău, ca un POST repetat să nu dubleze programarea
178
+ client: { email: "ana@example.com", nume: "Ana Pop" },
179
+ incepeLa: "2027-05-12T10:00:00+03:00",
180
+ titlu: "Consultație",
181
+ durataMinute: 30,
182
+ necesitaConfirmare: true,
183
+ })
184
+ console.log(p.id, p.creata, p.client.stare) // "3f2c...", true, "invitat"
185
+
186
+ await acteo.programari.actualizeaza(p.id, { incepeLa: "2027-05-13T10:00:00+03:00" })
187
+ await acteo.programari.anuleaza(p.id)
188
+ ```
189
+
190
+ Clientul primește un mesaj când programarea ajunge la el și remindere cu 7 zile, cu o zi și cu 3 ore înainte. Dacă are cont Acteo, vede programarea și acolo. API-ul de programări e gratuit: nu cere abonament și nu are limită de clienți.
191
+
192
+ #### Dacă softul tău e folosit de mai multe firme
193
+
194
+ Fiecare firmă are cheia ei API: o generează din contul ei Acteo și o pune în softul tău. După cheie știm de la ce firmă vine programarea, iar clientul primește reminderele cu numele și sigla firmei. Creezi câte un client cu cheia fiecărei firme:
195
+
196
+ ```ts
197
+ const acteo = new Acteo({ apiKey: firma.cheieActeo }) // cheia firmei, salvată în softul tău
198
+ await acteo.programari.creeaza({ client: { email: "ana@example.com" }, incepeLa: "2027-05-12T10:00:00+03:00", titlu: "Consultație" })
199
+ ```
200
+
201
+ Dacă firma șterge cheia din cont, cererile cu ea primesc `EroareAutentificare`.
202
+
171
203
  ## Ce identificator cere fiecare verificare
172
204
 
173
205
  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.
@@ -201,10 +233,20 @@ O verificare consumă din cota planului doar când sursa oficială a răspuns, i
201
233
  | `valid` | Document valabil | data expirării |
202
234
  | `warning` | Expiră curând: RCA în 14 zile, ITP în 30, rovinietă în 7, ARR în 14 | data expirării |
203
235
  | `expired` | Expirat sau inexistent, confirmat de sursă | data expirării sau `null` |
204
- | `not_found` | Sursa nu a găsit vehiculul | `null` |
236
+ | `not_found` | Sursa nu a găsit vehiculul (`code: "NOT_FOUND"`) | `null` |
205
237
  | `processing` | Verificarea e încă în curs | nu există |
206
238
 
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:
239
+ Când verificarea se încheie cu eroare, SDK-ul aruncă `EroareVerificare`, iar `cod` spune de ce:
240
+
241
+ | `cod` | Ce s-a întâmplat | Ce faci |
242
+ |---|---|---|
243
+ | `INVALID_IDENTIFIER` | Sursa a refuzat datele trimise; câmpul e în `codSursa` | corectezi câmpul, reîncercarea nu ajută |
244
+ | `UPSTREAM_UNAVAILABLE` | Sursa oficială nu răspunde sau a răspuns cu eroare | reiei mai târziu |
245
+ | `UPSTREAM_TIMEOUT` | Sursa oficială nu a răspuns în timpul maxim | reiei mai târziu |
246
+ | `UPSTREAM_BLOCKED` | Accesul la sursa oficială e restricționat temporar | reiei mai târziu |
247
+ | `UPSTREAM_CHANGED` | Sursa și-a schimbat structura, adaptăm serviciul | reiei mai târziu |
248
+
249
+ Doar `INVALID_IDENTIFIER` se taxează, pentru că sursa a răspuns. Valorile lui `codSursa`:
208
250
 
209
251
  | `codSursa` | Câmpul de corectat |
210
252
  |---|---|
@@ -286,7 +328,7 @@ Decodează o serie de șasiu. Întoarce `marca`, `model`, `anFabricatie`, `sursa
286
328
 
287
329
  ### `auto.numere.verifica(numar)`
288
330
 
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.
331
+ 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: "INVALID_IDENTIFIER"`. Când verificarea nu poate rula primești `EroareServer` cu `cod` `UPSTREAM_UNAVAILABLE`, `UPSTREAM_TIMEOUT`, `UPSTREAM_BLOCKED`, `UPSTREAM_CHANGED`, `OCUPAT` sau `INDISPONIBIL`. Niciuna nu se taxează, iar `OCUPAT` se reîncearcă singur după `Retry-After`. Cere un abonament de numere disponibile.
290
332
 
291
333
  ### `auto.imagini.obtine({ marca, model, an, unghi?, umbra? })`
292
334
 
@@ -296,10 +338,124 @@ Răspunde imediat cu poza mașinii sau cu poza generică. `unghi` poate fi `"tre
296
338
 
297
339
  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
340
 
341
+ ### `casa.pad.verifica(cerere, optiuni?)`
342
+
343
+ Verifică dacă există o poliță PAD (asigurarea obligatorie a locuinței) valabilă pentru un CNP și o localitate, la o anumită dată. Răspunsul vine de la PADROM și poate dura câteva minute, așa că `verifica()` pornește cererea și așteaptă rezultatul, ca la documentele auto. Cere abonamentul API Verificare poliță PAD, separat de cel de verificări auto.
344
+
345
+ Ai nevoie de acordul proprietarului. Prin `acord: true` confirmi că îl ai sau că ești chiar proprietarul; fără el, cererea e respinsă local.
346
+
347
+ | Câmp | Obligatoriu | Descriere |
348
+ |---|---|---|
349
+ | `cnp` | da | CNP-ul proprietarului, 13 cifre. Spațiile și liniuțele sunt acceptate. Data și cifra de control sunt verificate local. API-ul nu păstrează CNP-ul și îl arată în răspuns doar mascat (`cnpMascat`). |
350
+ | `judet` | da, dacă nu trimiți `judetId` | Numele județului, cu sau fără diacritice, sau indicativul (`"CJ"`, `"B"`) |
351
+ | `localitate` | da, în afară de București | Orașul, comuna sau satul |
352
+ | `sector` | doar la București | Sectorul, de la 1 la 6 |
353
+ | `judetId`, `localitateId` | nu | Id-urile din nomenclatorul PADROM, în locul numelor |
354
+ | `data` | nu | Data verificată, `AAAA-LL-ZZ`, cel mult 365 de zile înainte sau după azi. Implicit azi |
355
+ | `acord` | da | `true`: ai acordul proprietarului sau ești chiar proprietarul |
356
+
357
+ ```ts
358
+ const pad = await acteo.casa.pad.verifica({
359
+ cnp: "<CNP-ul proprietarului>",
360
+ judet: "Cluj",
361
+ localitate: "Cluj-Napoca",
362
+ acord: true,
363
+ })
364
+
365
+ if (pad.valabila) console.log("Poliță PAD valabilă:", pad.serieNumar, pad.distribuitor)
366
+ else console.log("PADROM nu a găsit o poliță valabilă la", pad.laData)
367
+ ```
368
+
369
+ Rezultatul are `valabila` (`true` când PADROM a găsit o poliță valabilă la data cerută), `serieNumar` și `distribuitor` (sau `null`), `verificatLa` (`Date`), plus `requestId`, `cnpMascat` (de exemplu `1*********012`), `judet`, `localitate` și `laData`, ca să legi răspunsul de cererea ta. Opțiunile de așteptare sunt aceleași ca la documentele auto: `intervalMs` (implicit 3000, minim 2000) și `timeoutMs` (implicit 5 minute).
370
+
371
+ Se taxează o unitate doar când PADROM răspunde, inclusiv când refuză datele trimise (`EroareVerificare` cu `cod: "INVALID_IDENTIFIER"`). Dacă PADROM nu răspunde, primești `EroareVerificare` cu `UPSTREAM_UNAVAILABLE`, `UPSTREAM_TIMEOUT`, `UPSTREAM_BLOCKED` sau `UPSTREAM_CHANGED` și nu se taxează nimic. Un județ sau o localitate pe care nu le găsim dau `EroareValidare` (HTTP 422) cu `hint`, tot netaxat. Prea multe verificări în curs deodată dau `EroareLimita` cu `cod: "OCUPAT"`.
372
+
373
+ ### `casa.pad.porneste(cerere)`
374
+
375
+ Pornește verificarea fără să aștepte și întoarce `status: "processing"`, cu `requestId` și `queuedAt`. Primește aceleași câmpuri ca `verifica()`, plus `callbackUrl` opțional, unde API-ul trimite rezultatul când e gata.
376
+
377
+ ```ts
378
+ const p = await acteo.casa.pad.porneste({
379
+ cnp: "<CNP-ul proprietarului>",
380
+ judet: "B",
381
+ sector: 3,
382
+ acord: true,
383
+ callbackUrl: "https://example.com/webhooks/acteo/pad-7h2m",
384
+ })
385
+ const pad = await acteo.casa.pad.asteapta(p) // sau mai târziu, cu p.requestId
386
+ ```
387
+
388
+ ### `casa.pad.rezultat(referinta)`
389
+
390
+ Interoghează o singură dată, după `requestId` sau după obiectul primit de la `porneste()`. Întoarce `status: "processing"` sau `status: "done"`; o verificare încheiată cu eroare aruncă `EroareVerificare`. CNP-ul nu apare în URL. Nu consumă din cotă. Cererile se păstrează 30 de zile; după aceea, sau pentru un id din alt cont, primești `EroareNegasit`.
391
+
392
+ ### `casa.pad.asteapta(referinta, optiuni?)`
393
+
394
+ Face polling până la răspunsul PADROM, cu aceleași opțiuni ca `verifica()`. Nu consumă din cotă.
395
+
396
+ ### `programari.creeaza(cerere)`
397
+
398
+ Trimite o programare. Răspunsul e programarea, cu `creata: true` când e nouă. Dacă trimiți un `idExtern` deja folosit, programarea existentă se actualizează și primești `creata: false`; clientul ei rămâne același.
399
+
400
+ | Câmp | Obligatoriu | Descriere |
401
+ |---|---|---|
402
+ | `client.email` | da | Emailul clientului. După el îl recunoaștem |
403
+ | `client.nume` | nu | Numele clientului, cum apare în remindere |
404
+ | `incepeLa` | da | Data și ora, cu fusul orar, în viitor: text ISO 8601 (`"2027-05-12T10:00:00+03:00"`) sau `Date` |
405
+ | `titlu` | da | Ce fel de programare e, cum o vede clientul (`"Consultație"`) |
406
+ | `idExtern` | nu | Id-ul din programul tău: litere, cifre și `._:-` |
407
+ | `durataMinute` | nu | Cât durează, între 5 și 1.440 de minute |
408
+ | `locatie` | nu | Unde are loc, dacă diferă de adresa afacerii |
409
+ | `cuCine` | nu | La cine e programarea, dacă afacerea are mai mulți oameni: medicul, frizerul, consultantul (`"Dr. Ana Ionescu"`). Clientul îl vede în remindere și în calendar. Cel mult 120 de caractere |
410
+ | `note` | nu | Ce trebuie să știe clientul înainte, de exemplu ce să aducă |
411
+ | `url` | nu | Link https primit de client în remindere, de exemplu pentru o întâlnire online |
412
+ | `necesitaConfirmare` | nu | `true`: clientul e rugat să confirme că vine. Implicit `false` |
413
+ | `confirmareInMaximOre` | nu | Cât timp are clientul de la primirea programării ca să confirme, în ore, între 1 și 720 (`72` = 3 zile). Doar cu `necesitaConfirmare: true`; `null` îl șterge la modificare |
414
+ | `confirmareCuMinimOreInainte` | nu | Cu câte ore înainte de programare trebuie să confirme clientul cel târziu, între 1 și 720. Cu ambele câmpuri trimise, contează termenul care vine primul |
415
+ | `remindere` | nu | Dintre `"7z"`, `"1z"`, `"3h"`. Implicit toate trei; o listă goală înseamnă doar mesajul la primire |
416
+ | `sms` | nu | `false`: fără SMS. Altfel SMS doar dacă planul îl include și e pornit din cont |
417
+
418
+ Programarea are `id`, `idExtern`, `status` (`programata`, `anulata`, `trecuta`), `client` (`email`, `nume`, `stare`), `incepeLa` (`Date`), `durataMinute`, `titlu`, `locatie`, `cuCine` (`null` dacă nu l-ai trimis), `note`, `url`, `necesitaConfirmare`, `confirmatLa` (`Date` sau `null`), `confirmareInMaximOre` și `confirmareCuMinimOreInainte` (număr sau `null`), `confirmareExpiraLa` (până când poate confirma clientul, `Date` sau `null`), `confirmareExpirataLa` (când a trecut termenul fără confirmare, `Date` sau `null`), `vazutLa` (când a deschis clientul programarea, `Date` sau `null`; devine `null` când modifici ce vede clientul), `remindere`, `sms`, `creatLa` și `actualizatLa`. `client.stare` e `cont` (are cont Acteo și vede programarea acolo), `invitat` (primește remindere pe email), `dezabonat` (nu mai primește programări de la tine).
419
+
420
+ O cerere refuzată nu scrie nimic. Erorile posibile:
421
+
422
+ - `EroareValidare` (422): email invalid, dată în trecut, link fără https, un `idExtern` folosit deja pentru alt client, `cod: "PROFIL_EXPEDITOR_LIPSA"` când lipsește din cont numele afacerii, care apare în remindere, sau `cod: "ADRESA_AFACERII_LIPSA"` când programarea n-are `locatie` și lipsește din cont adresa afacerii;
423
+ - `EroareConflict` cu `cod: "CLIENT_INDISPONIBIL"`: clientul a ales să nu mai primească mesaje de la tine;
424
+ - `EroareLimita`: `LIMIT_ATINS` (prea mulți clienți noi fără cont azi; `limita` spune câți poți invita pe zi) sau `PREA_MULTE_CERERI` (prea multe cereri într-un interval scurt, reia după `retryAfterMs`).
425
+
426
+ `creeaza()` nu se repetă singur după un răspuns de la API, ca o programare să nu plece de două ori. Cu `idExtern`, o repetare făcută de tine e sigură.
427
+
428
+ ### `programari.lista({ din?, pana?, cursor?, limita? })`
429
+
430
+ Întoarce o pagină de programări, în ordinea datei de început, inclusiv cele anulate sau trecute: `{ programari, urmatorulCursor }`. `din` și `pana` (text ISO cu fus orar sau `Date`) filtrează după data de început, `limita` e între 1 și 100 (implicit 50). Pentru pagina următoare trimite `urmatorulCursor` ca `cursor`; e `null` la ultima pagină.
431
+
432
+ ```ts
433
+ const din = new Date()
434
+ let cursor: string | undefined
435
+ do {
436
+ const pagina = await acteo.programari.lista({ din, cursor })
437
+ for (const p of pagina.programari) console.log(p.incepeLa, p.titlu, p.client.email)
438
+ cursor = pagina.urmatorulCursor ?? undefined
439
+ } while (cursor)
440
+ ```
441
+
442
+ ### `programari.obtine(id)`
443
+
444
+ Citește o programare după `id`. Pentru un id care nu e în contul cheii primești `EroareNegasit`.
445
+
446
+ ### `programari.actualizeaza(id, modificare)`
447
+
448
+ Modifică doar câmpurile trimise, iar `null` golește un câmp opțional. Câmpurile sunt cele de la `creeaza()`, fără `idExtern` și `client.email`: din client se schimbă doar `nume`. Pentru alt client, anulează programarea și creează una nouă. Mutarea datei cere o confirmare nouă. Dacă toate valorile sunt cele de acum, nu se schimbă nimic și nu pleacă remindere noi. O programare anulată nu se mai poate muta (`EroareConflict`).
449
+
450
+ ### `programari.anuleaza(id)`
451
+
452
+ Anulează programarea și oprește reminderele. Întoarce programarea cu `status: "anulata"`. A doua anulare întoarce aceeași programare, fără alte efecte, deci SDK-ul o reîncearcă fără grijă.
453
+
299
454
  ### Utilitare de validare
300
455
 
301
456
  ```ts
302
457
  import {
458
+ esteCnpValid,
303
459
  esteNumarInmatriculareValid,
304
460
  esteSerieTalonValida,
305
461
  esteVinValid,
@@ -312,6 +468,7 @@ esteVinValid("WVWZZZ1JZXW00000I") // false: litera I nu e permisă în VI
312
468
  esteSerieTalonValida("I00639603F") // true
313
469
  normalizeaza(" b-123 abc ") // "B123ABC"
314
470
  normalizeazaSerieTalon("i 00639603-f") // "I00639603F"
471
+ esteCnpValid("1900101400013") // false: cifra de control nu se potrivește
315
472
  ```
316
473
 
317
474
  Le poți folosi pentru formularele tale, ca să validezi datele înainte să ajungă la server.
@@ -349,6 +506,20 @@ app.post("/webhooks/acteo/9f3k2", express.raw({ type: "application/json" }), (re
349
506
 
350
507
  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
508
 
509
+ ### Rezultatul unei verificări de poliță PAD (`callbackUrl`)
510
+
511
+ Când trimiți `callbackUrl` la `casa.pad.porneste()`, primești un POST cu răspunsul PADROM: `status: "done"` cu `valabila`, `serieNumar` și `distribuitor`, sau `status: "error"` cu `code` și `error`. Corpul conține doar `cnpMascat`, niciodată CNP-ul.
512
+
513
+ ```ts
514
+ app.post("/webhooks/acteo/pad-7h2m", express.raw({ type: "application/json" }), (req, res) => {
515
+ const r = acteo.webhooks.parseazaRezultatPad(req.body)
516
+ if (r.status === "done") salveaza(r.requestId, r.valabila)
517
+ res.sendStatus(200)
518
+ })
519
+ ```
520
+
521
+ Aceleași reguli ca mai sus: URL pe HTTPS, cu un segment greu de ghicit, și `requestId` potrivit cu cel de la `porneste()`.
522
+
352
523
  ### Notificări din cont (`document.expira` și celelalte evenimente)
353
524
 
354
525
  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:
@@ -383,29 +554,58 @@ Cu add-on-ul Webhook, la același URL vin și evenimentele celorlalte servicii d
383
554
  | `marca.schimbare` | Schimbare la o marcă urmărită (OSIM sau EUIPO) | `marca`, `schimbare`, `valoareVeche`, `valoareNoua` |
384
555
  | `marca.expira` | O marcă intră într-un prag de expirare | `marca`, `expiraLa`, `prag`, `reinnoirePanaLa` |
385
556
  | `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` |
557
+ | `termen.expira` | Un termen din cont intră în pragul de 30 sau de 3 zile (7 în loc de 30 la termenele care se repetă la cel mult 3 luni) | `termen`, `zileRamase`, `prag` |
558
+ | `programare.confirmata` | Clientul a confirmat programarea din emailul primit | `programare.id`, `programare.idExtern`, `client.email`, `confirmatLa` |
559
+ | `programare.confirmare_expirata` | Clientul nu a confirmat programarea până la termenul ales de tine; programarea rămâne activă, tu decizi dacă o anulezi | `programare.id`, `programare.idExtern`, `client.email`, `confirmareExpirataLa` |
560
+ | `programare.client_dezabonat` | Clientul nu mai primește mesaje de la tine | `client.email`, `la` |
387
561
  | `webhook.test` | Butonul de test din dashboard | `mesaj` |
388
562
 
389
- Datele cu oră (`trimisLa`, `sedinta.data`, `verificatLa`) devin `Date`. Datele calendaristice `yyyy-mm-dd` (`marca.expiraLa`, `termen.expiraLa`) rămân text.
563
+ Evenimentele programărilor sunt incluse în API Programări, fără add-on-ul Webhook. Datele cu oră (`trimisLa`, `sedinta.data`, `verificatLa`, `confirmatLa`, `la`) devin `Date`. Datele calendaristice `yyyy-mm-dd` (`marca.expiraLa`, `termen.expiraLa`) rămân text.
390
564
 
391
565
  ## Erori
392
566
 
393
567
  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
568
 
569
+ ### Coduri de eroare
570
+
571
+ `cod` are o valoare stabilă, bună de tratat în program. Lista completă e exportată ca `CODURI_EROARE`, iar tipul e `CodEroare`. Primele opt sunt cele din contract:
572
+
573
+ | `cod` | Unde apare | Înseamnă |
574
+ |---|---|---|
575
+ | `UPSTREAM_UNAVAILABLE` | `EroareVerificare`, `EroareServer` 502 | Sursa oficială nu răspunde sau răspunde cu eroare |
576
+ | `UPSTREAM_TIMEOUT` | `EroareVerificare`, `EroareServer` 504 | Sursa oficială nu a răspuns în intervalul maxim |
577
+ | `UPSTREAM_BLOCKED` | `EroareVerificare`, `EroareServer` 503 | Accesul la sursa oficială e restricționat temporar |
578
+ | `UPSTREAM_CHANGED` | `EroareVerificare`, `EroareServer` 503 | Structura sursei s-a modificat, serviciul e în adaptare |
579
+ | `DAILY_LIMIT_REACHED` | `EroareLimita` 429 | Limita zilnică a planului, se resetează la miezul nopții (ora României) |
580
+ | `PLAN_LIMIT_REACHED` | `EroareLimita` 429 | Limita lunară, sau plafonul consumului peste plan |
581
+ | `NOT_FOUND` | `code` pe rezultatul `not_found` | Identificatorul nu există la sursa oficială |
582
+ | `INVALID_IDENTIFIER` | `EroareVerificare`, `EroareValidare` 422 | Sursa oficială a respins identificatorul |
583
+
584
+ Restul țin de un produs: `SOLD_INSUFICIENT`, `PLAFON_NETAXAT`, `OCUPAT`, `INDISPONIBIL`, `VIN_NEDECODAT`, `CULOARE_NECUNOSCUTA`, `VIN_INVALID`, `ARR_NECESITA_PLAN`, `LIMIT_ATINS` (numărul de mașini din plan sau, la programări, clienții noi fără cont invitați azi), `VEHICUL_EXISTENT`, `NEGASIT`, `LIMITA_FLOTA_ATINSA`. La programări mai apar:
585
+
586
+ | `cod` | Unde apare | Înseamnă |
587
+ |---|---|---|
588
+ | `PROFIL_EXPEDITOR_LIPSA` | `EroareValidare` 422 | Completează în cont datele afacerii care apar în remindere |
589
+ | `ADRESA_AFACERII_LIPSA` | `EroareValidare` 422 | Completează în cont adresa afacerii sau trimite `locatie` în programare |
590
+ | `CLIENT_INDISPONIBIL` | `EroareConflict` 409 | Clientul nu mai primește programări de la tine |
591
+ | `PREA_MULTE_CERERI` | `EroareLimita` 429 | Prea multe cereri într-un interval scurt; reia după `retryAfterMs`. Nu se taxează |
592
+
593
+ ### Clasele de eroare
594
+
395
595
  | Clasă | Când apare | Câmpuri utile |
396
596
  |---|---|---|
397
597
  | `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` |
598
+ | `EroareValidare` | Date greșite, local sau HTTP 400; 422 când DGPCI refuză numărul (`INVALID_IDENTIFIER`) sau o programare nu poate fi folosită (`PROFIL_EXPEDITOR_LIPSA`, `ADRESA_AFACERII_LIPSA`) | `camp`, `acceptate`, `cod` |
399
599
  | `EroareAutentificare` | 401: cheie invalidă sau dezactivată | `hint` |
400
600
  | `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` |
601
+ | `EroareInterzis` | 403: `LIMIT_ATINS`, `ARR_NECESITA_PLAN`, sau trimiterea de programări e oprită pentru cont | `cod`, `limita` |
602
+ | `EroareNegasit` | 404: vehicul sau programare inexistente în cont | |
603
+ | `EroareConflict` | 409: `VEHICUL_EXISTENT`, `CLIENT_INDISPONIBIL` sau o programare anulată | `cod` |
604
+ | `EroareLimita` | 429: cotă (`DAILY_LIMIT_REACHED`, `PLAN_LIMIT_REACHED`), plafon de flotă, clienți noi invitați azi (`LIMIT_ATINS`) sau prea multe cereri (`PREA_MULTE_CERERI`) | `cod`, `retryAfterMs`, `utilizareZi`, `utilizareLuna`, `limita` |
605
+ | `EroareServer` | 5xx; sursa oficială (`UPSTREAM_*`), sau `OCUPAT`, `INDISPONIBIL` la numere disponibile | `status`, `cod`, `retryAfterMs` |
406
606
  | `EroareRetea` | Fără răspuns sau timeout | `timeout`, `neajunsa` |
407
607
  | `EroareRaspunsInvalid` | Răspuns cu formă neașteptată | `raspuns` |
408
- | `EroareVerificare` | Sursa oficială nu a putut fi interogată sau a refuzat datele | `codSursa` |
608
+ | `EroareVerificare` | Sursa oficială nu a dat un răspuns sau a refuzat datele | `cod`, `codSursa` |
409
609
  | `EroareTimeoutVerificare` | `asteapta()` sau `imagini.asteapta()` a depășit `timeoutMs` | |
410
610
  | `EroareWebhook` | Cheie greșită sau payload invalid | `cod` |
411
611
 
@@ -416,7 +616,7 @@ try {
416
616
  await acteo.auto.rca.porneste(numar)
417
617
  } catch (err) {
418
618
  if (err instanceof EroareValidare) return arataUtilizatorului(err.message)
419
- if (err instanceof EroareLimita && err.cod === "COTA_ATINSA") return amanaPanaMaine()
619
+ if (err instanceof EroareLimita && err.cod === "DAILY_LIMIT_REACHED") return amanaPanaMaine()
420
620
  if (err instanceof ActeoError) logger.error(err._tag, err.message, err.hint)
421
621
  throw err
422
622
  }
@@ -428,15 +628,15 @@ Erorile trecătoare sunt reîncercate automat, cu backoff exponențial (x2) și
428
628
 
429
629
  SDK-ul nu trimite niciodată de două ori o verificare taxată.
430
630
 
431
- | Situație | GET / DELETE | POST |
631
+ | Situație | GET / DELETE | POST / PUT |
432
632
  |---|---|---|
433
633
  | Rețea căzută, timeout | se reîncearcă | nu (cererea poate să fi ajuns) |
434
634
  | 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) |
635
+ | 502, 503, 504 fără `cod` | se reîncearcă | se reîncearcă (cererea nu a ajuns la API) |
436
636
  | 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) |
637
+ | 502, 503, 504 cu alt `cod` (`UPSTREAM_*`, `INDISPONIBIL`) | | nu (netaxat, dar repetarea nu ajută imediat) |
438
638
  | 500 | se reîncearcă | nu |
439
- | 429 la polling | se reîncearcă după `Retry-After` | |
639
+ | 429 `PREA_MULTE_CERERI` | se reîncearcă după `Retry-After` | nu (netaxat, `retryAfterMs` spune cât să aștepți) |
440
640
  | 429 cotă sau plafon flotă | nu | nu |
441
641
  | 4xx | nu | nu |
442
642
 
@@ -458,6 +658,8 @@ const r = await acteo.auto.rca.porneste("B123ABC")
458
658
  console.log(r.limite) // { zi: { limita: 300, ramase: 287 }, luna: { limita: 10000, ramase: 9412 } }
459
659
  ```
460
660
 
661
+ API-ul de programări e gratuit și nu consumă din nicio cotă. Singura limită e numărul de clienți noi fără cont pe care îi poți invita într-o zi (`LIMIT_ATINS`).
662
+
461
663
  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
664
 
463
665
  ## Exemple
@@ -536,9 +738,13 @@ Apelezi `acteo.auto.numere.verifica("BV07ABC")`. SDK-ul trimite numărul la DGPC
536
738
 
537
739
  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
740
 
741
+ ### Pot verifica prin API dacă o casă are poliță PAD?
742
+
743
+ Da, cu `acteo.casa.pad.verifica()`. Trimiți CNP-ul proprietarului, județul și localitatea locuinței, iar PADROM răspunde dacă există o poliță PAD valabilă la data cerută (implicit azi). Ai nevoie de acordul proprietarului și de abonamentul API Verificare poliță PAD. Pentru o singură locuință, fără cod, folosește [verificarea PAD de pe site](https://acteo.ro/verificare-pad).
744
+
539
745
  ### Există SDK pentru PHP sau Python?
540
746
 
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.
747
+ Da, cu aceleași apeluri: [`acteo/api`](https://packagist.org/packages/acteo/api) pentru PHP și [`acteo`](https://pypi.org/project/acteo/) pentru Python. [Documentația API](https://acteo.ro/api-acces) are și exemple pentru cURL.
542
748
 
543
749
  ## Linkuri utile
544
750