@acteo/api 0.5.0 → 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,22 @@
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
+
3
20
  ## @acteo/api 0.5.0 (2026-11-03)
4
21
 
5
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.
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 |
@@ -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.
@@ -306,10 +338,124 @@ Răspunde imediat cu poza mașinii sau cu poza generică. `unghi` poate fi `"tre
306
338
 
307
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.
308
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
+
309
454
  ### Utilitare de validare
310
455
 
311
456
  ```ts
312
457
  import {
458
+ esteCnpValid,
313
459
  esteNumarInmatriculareValid,
314
460
  esteSerieTalonValida,
315
461
  esteVinValid,
@@ -322,6 +468,7 @@ esteVinValid("WVWZZZ1JZXW00000I") // false: litera I nu e permisă în VI
322
468
  esteSerieTalonValida("I00639603F") // true
323
469
  normalizeaza(" b-123 abc ") // "B123ABC"
324
470
  normalizeazaSerieTalon("i 00639603-f") // "I00639603F"
471
+ esteCnpValid("1900101400013") // false: cifra de control nu se potrivește
325
472
  ```
326
473
 
327
474
  Le poți folosi pentru formularele tale, ca să validezi datele înainte să ajungă la server.
@@ -359,6 +506,20 @@ app.post("/webhooks/acteo/9f3k2", express.raw({ type: "application/json" }), (re
359
506
 
360
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.
361
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
+
362
523
  ### Notificări din cont (`document.expira` și celelalte evenimente)
363
524
 
364
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:
@@ -393,10 +554,13 @@ Cu add-on-ul Webhook, la același URL vin și evenimentele celorlalte servicii d
393
554
  | `marca.schimbare` | Schimbare la o marcă urmărită (OSIM sau EUIPO) | `marca`, `schimbare`, `valoareVeche`, `valoareNoua` |
394
555
  | `marca.expira` | O marcă intră într-un prag de expirare | `marca`, `expiraLa`, `prag`, `reinnoirePanaLa` |
395
556
  | `asigurare.schimbare` | S-a schimbat statutul de asigurat la CNAS | `persoana`, `statut`, `areCard` |
396
- | `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` |
397
561
  | `webhook.test` | Butonul de test din dashboard | `mesaj` |
398
562
 
399
- 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.
400
564
 
401
565
  ## Erori
402
566
 
@@ -417,20 +581,27 @@ Toate erorile moștenesc `ActeoError`, care la rândul ei moștenește `Error`.
417
581
  | `NOT_FOUND` | `code` pe rezultatul `not_found` | Identificatorul nu există la sursa oficială |
418
582
  | `INVALID_IDENTIFIER` | `EroareVerificare`, `EroareValidare` 422 | Sursa oficială a respins identificatorul |
419
583
 
420
- Restul țin de un produs: `SOLD_INSUFICIENT`, `PLAFON_NETAXAT`, `OCUPAT`, `INDISPONIBIL`, `VIN_NEDECODAT`, `VIN_INVALID`, `ARR_NECESITA_PLAN`, `LIMIT_ATINS` (numărul de mașini din plan), `VEHICUL_EXISTENT`, `NEGASIT`, `LIMITA_FLOTA_ATINSA`.
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ă |
421
592
 
422
593
  ### Clasele de eroare
423
594
 
424
595
  | Clasă | Când apare | Câmpuri utile |
425
596
  |---|---|---|
426
597
  | `EroareConfigurare` | Cheie lipsă sau opțiuni invalide | |
427
- | `EroareValidare` | Date greșite, local sau HTTP 400; 422 când DGPCI refuză numărul (`INVALID_IDENTIFIER`) | `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` |
428
599
  | `EroareAutentificare` | 401: cheie invalidă sau dezactivată | `hint` |
429
600
  | `EroarePlanInactiv` | 402: fără abonament activ | `hint` |
430
- | `EroareInterzis` | 403: `LIMIT_ATINS`, `ARR_NECESITA_PLAN` | `cod`, `limita` |
431
- | `EroareNegasit` | 404: vehicul inexistent în cont | |
432
- | `EroareConflict` | 409: `VEHICUL_EXISTENT` | |
433
- | `EroareLimita` | 429: cotă (`DAILY_LIMIT_REACHED`, `PLAN_LIMIT_REACHED`), plafon de flotă sau polling prea des | `cod`, `retryAfterMs`, `utilizareZi`, `utilizareLuna` |
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` |
434
605
  | `EroareServer` | 5xx; sursa oficială (`UPSTREAM_*`), sau `OCUPAT`, `INDISPONIBIL` la numere disponibile | `status`, `cod`, `retryAfterMs` |
435
606
  | `EroareRetea` | Fără răspuns sau timeout | `timeout`, `neajunsa` |
436
607
  | `EroareRaspunsInvalid` | Răspuns cu formă neașteptată | `raspuns` |
@@ -457,7 +628,7 @@ Erorile trecătoare sunt reîncercate automat, cu backoff exponențial (x2) și
457
628
 
458
629
  SDK-ul nu trimite niciodată de două ori o verificare taxată.
459
630
 
460
- | Situație | GET / DELETE | POST |
631
+ | Situație | GET / DELETE | POST / PUT |
461
632
  |---|---|---|
462
633
  | Rețea căzută, timeout | se reîncearcă | nu (cererea poate să fi ajuns) |
463
634
  | DNS, conexiune refuzată | se reîncearcă | se reîncearcă (sigur nu a ajuns) |
@@ -465,7 +636,7 @@ SDK-ul nu trimite niciodată de două ori o verificare taxată.
465
636
  | 503 `OCUPAT` la numere disponibile | | se reîncearcă după `Retry-After` (netaxat) |
466
637
  | 502, 503, 504 cu alt `cod` (`UPSTREAM_*`, `INDISPONIBIL`) | | nu (netaxat, dar repetarea nu ajută imediat) |
467
638
  | 500 | se reîncearcă | nu |
468
- | 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) |
469
640
  | 429 cotă sau plafon flotă | nu | nu |
470
641
  | 4xx | nu | nu |
471
642
 
@@ -487,6 +658,8 @@ const r = await acteo.auto.rca.porneste("B123ABC")
487
658
  console.log(r.limite) // { zi: { limita: 300, ramase: 287 }, luna: { limita: 10000, ramase: 9412 } }
488
659
  ```
489
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
+
490
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).
491
664
 
492
665
  ## Exemple
@@ -565,9 +738,13 @@ Apelezi `acteo.auto.numere.verifica("BV07ABC")`. SDK-ul trimite numărul la DGPC
565
738
 
566
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.
567
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
+
568
745
  ### Există SDK pentru PHP sau Python?
569
746
 
570
- 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.
571
748
 
572
749
  ## Linkuri utile
573
750