aves-sdk 1.3.3 → 1.4.0

package/docs/guida-implementazione-booking-ops.md

@@ -0,0 +1,482 @@
+# Guida implementazione — Booking ops AVES SDK 1.4.0
+
+Guida pratica per le operazioni di booking aggiunte in **aves-sdk@1.4.0**, derivate dallo spike API AVES XML 1.8.0.
+
+**Escluso:** creazione/ricerca del Programma come entità master (gap Datagest — non coperto dai PDF).  
+**Incluso:** uso del Programma su pratica, update/delete costi, riassegnazione package, annullamento pratica.
+
+---
+
+## Setup client
+
+```ts
+import { AvesClient } from "aves-sdk";
+
+const client = new AvesClient({
+  baseURL: "https://<aves-host>",
+  hostID: "000000", // 6 digit
+  xtoken: "TOKEN000000",
+  languageCode: "01", // opzionale
+  timeoutMs: 30_000,
+});
+```
+
+Tutti i metodi restituiscono `Result<T, AvesError>`:
+
+```ts
+const result = await client.modBookingServices(/* ... */);
+if (!result.success) {
+  console.error(result.error.kind, result.error.message, result.error.code);
+  return;
+}
+const data = result.data; // tipizzato
+```
+
+---
+
+## Mappa task → metodo SDK
+
+| Task spike | Metodo | Endpoint |
+|---|---|---|
+| Update voci di costo | `modBookingServices` | `/interop/booking/v2/rest/ModBookingFileServices` |
+| Delete voci / overwrite | `modBookingServices` (+ opz. `setBookingServiceStatus`) | stesso / `SetBookingFileServiceStatus` |
+| Assegna / riassegna Programma | `modBookingServices` (`selectedPackageDetail`) | stesso |
+| Annulla pratica (soft) | `setBookingStatus` | `/interop/booking/v2/rest/SetBookingFileStatus` |
+| Annulla pratica (delete) | `cancelBooking` | `/interop/booking/v2/rest/CancelBookingFile` |
+| Nullify singola riga | `setBookingServiceStatus` | `/interop/booking/v2/rest/SetBookingFileServiceStatus` |
+| Header (pax/note/billing) | `modBookingHeader` | `/interop/booking/v2/rest/ModBookingFileHeader` |
+
+> **Programma** = Package AVES (`pCode` / `PackageCode`). Non esiste API SDK per create/search package.
+
+---
+
+## 1. Aggiornamento voci di costo
+
+Aggiorna una riga già presente: passa `bookedServiceRef` (RPH) e incrementa `avesSession`. Imposta costi/prezzi con `serviceFare`.
+
+```ts
+const result = await client.modBookingServices({
+  customerRecordCode: "138311",
+  bookingFileCode: "14/036654",
+  selectedServiceList: {
+    selectedServiceDetail: [
+      {
+        sCode: "HT00110840",
+        ssCode: "DL",
+        avesServiceType: "TOP",
+        toServiceType: "RESIDENCE",
+        subServiceDesc: "DOPPIA DE LUXE",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "1",
+        pax: "2",
+        paxAssociated: [{ pax: "001" }, { pax: "002" }],
+        avesSession: "2", // incrementare ad ogni modifica della stessa riga
+        bookedServiceRef: "001", // RPH servizio già in pratica
+        serviceFare: {
+          currencyCode: "EUR",
+          cost: "180.00",
+          costTax: "0.00",
+          costType: "FORFAIT",
+          price: "220.00",
+          priceTax: "0.00",
+          priceType: "FORFAIT",
+        },
+        avesServiceInfo: {
+          packageCode: "2014MDE0000010",
+          packageReference: "05",
+          priceListCode: "G",
+          costListCode: "G",
+        },
+      },
+    ],
+  },
+});
+
+if (result.success) {
+  console.log(result.data.bookingFileDetail?.bookingFileCode);
+  console.log(result.data.bookingFileDetail?.totalAmountDetail);
+}
+```
+
+### Note
+
+- `selectedServiceList.selectedServiceDetail` è un **array** (shape Mod ≠ Create).
+- `ModBookingFileHeader` **non** aggiorna costi.
+
+---
+
+## 2. Cancellazione voci + overwrite integrale
+
+Pattern: `DELETE`/`NULLIFY` delle righe esistenti → re-insert del nuovo set nello stesso (o successivo) `modBookingServices`.
+
+```ts
+const result = await client.modBookingServices({
+  customerRecordCode: "138311",
+  bookingFileCode: "14/036654",
+  cancellableBookedServiceList: {
+    cancellableBookedServiceDetail: [
+      {
+        cancelOperationType: "DELETE", // o "NULLIFY"
+        serviceRefType: "RPH",
+        serviceRefValue: "001",
+      },
+      {
+        cancelOperationType: "DELETE",
+        serviceRefType: "RPH",
+        serviceRefValue: "002",
+      },
+    ],
+  },
+  // nuovo set (obbligatorio: almeno 1 servizio nello schema SDK)
+  selectedServiceList: {
+    selectedServiceDetail: [
+      {
+        sCode: "VLGENFLEX",
+        avesServiceType: "OTHER",
+        toServiceType: "OTHER",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "2",
+        pax: "2",
+        paxAssociated: [],
+        avesSession: "1",
+        serviceFare: {
+          currencyCode: "EUR",
+          cost: "50.00",
+          price: "80.00",
+        },
+      },
+      {
+        sCode: "HT00110840",
+        ssCode: "DIN",
+        avesServiceType: "TOP",
+        toServiceType: "RESIDENCE",
+        subServiceDesc: "CENA ADULTO",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "2",
+        pax: "2",
+        paxAssociated: [{ pax: "001" }, { pax: "002" }],
+        avesSession: "1",
+        serviceFare: {
+          currencyCode: "EUR",
+          cost: "40.00",
+          price: "60.00",
+        },
+      },
+    ],
+  },
+});
+```
+
+### Alternativa: nullify di una sola riga
+
+```ts
+const result = await client.setBookingServiceStatus({
+  customerRecordCode: "000001",
+  bookingFileCode: "18/000252",
+  bookingServiceRef: "002",
+  bookingFileServiceStatus: "NULLIFIED",
+  bookingFileServiceStatusDate: "2018-11-29T12:50:00+01:00",
+});
+```
+
+| `cancelOperationType` | Uso tipico |
+|---|---|
+| `DELETE` | rimozione (wipe + re-insert) |
+| `NULLIFY` | annullamento contabile/operativo della riga |
+
+---
+
+## 3. Assegnazione / riassegnazione Programma
+
+Su pratica già esistente: `selectedPackageDetail` in `modBookingServices`.  
+Collegare i servizi al package con `avesServiceInfo.packageCode` + `packageReference`.
+
+```ts
+const result = await client.modBookingServices({
+  customerRecordCode: "138311",
+  bookingFileCode: "14/036654",
+  selectedPackageDetail: {
+    pCode: "2014MDE0000010",
+    startDate: "2015-01-22T00:00:00",
+    endDate: "2015-01-25T00:00:00",
+    getServicesFromPackage: false, // true = auto-carica solo ADV/GRP
+  },
+  selectedServiceList: {
+    selectedServiceDetail: [
+      {
+        sCode: "HT00110840",
+        ssCode: "DL",
+        avesServiceType: "TOP",
+        toServiceType: "RESIDENCE",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "1",
+        pax: "2",
+        paxAssociated: [{ pax: "001" }, { pax: "002" }],
+        avesSession: "1",
+        bookedServiceRef: "001", // se aggiorni riga esistente
+        avesServiceInfo: {
+          packageCode: "2014MDE0000010",
+          packageReference: "01",
+        },
+        serviceFare: {
+          currencyCode: "EUR",
+          cost: "100.00",
+          price: "120.00",
+        },
+      },
+    ],
+  },
+});
+
+if (result.success) {
+  // PackageCode sulla pratica (se AVES lo aggiorna)
+  console.log(result.data.bookingFileDetail?.packageCode);
+}
+```
+
+### In creazione pratica (riferimento)
+
+```ts
+await client.createBooking({
+  customerDetail: { recordCode: "138311" },
+  bookingFileStatus: { value: "QUOTATION" },
+  startDate: "2015-01-22T00:00:00",
+  endDate: "2015-01-25T00:00:00",
+  selectedPackageList: {
+    selectedPackageDetail: [
+      {
+        pCode: "2014MDE0000010",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+      },
+    ],
+  },
+  selectedServiceList: [
+    {
+      selectedServiceDetail: {
+        sCode: "HT00110840",
+        ssCode: "DL",
+        avesServiceType: "TOP",
+        toServiceType: "RESIDENCE",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "1",
+        pax: "2",
+        paxAssociated: [],
+        avesSession: "1",
+        avesServiceInfo: {
+          packageCode: "2014MDE0000010",
+          packageReference: "01",
+        },
+      },
+    },
+  ],
+  passengerList: [
+    {
+      passengerDetail: {
+        rph: "001",
+        roomRph: "001",
+        name: "ADULTI 001",
+        categoryCode: "AD", // obbligatorio in create
+        sex: "M",
+      },
+    },
+  ],
+});
+```
+
+> Shape lista servizi: **Create** = array di wrapper `{ selectedServiceDetail: one }`; **Mod** = `{ selectedServiceDetail: one[] }`.
+
+---
+
+## 4. Annullabilità pratica
+
+### Soft — cambio stato
+
+```ts
+// CANCELED
+const canceled = await client.setBookingStatus({
+  customerRecordCode: "000170",
+  bookingFileCode: "14/000081",
+  fileStatus: { value: "CANCELED" },
+  backOfficeRequest: true,
+  bookingFileDocument: {
+    printDoc: false,
+    sendDocViaEmail: false,
+  },
+});
+
+// NULLIFIED con penali
+const nullified = await client.setBookingStatus({
+  customerRecordCode: "000170",
+  bookingFileCode: "14/000081",
+  fileStatus: { value: "NULLIFIED" },
+  backOfficeRequest: true,
+  penalty: {
+    apply: true, // false = penali automatiche di sistema
+    specificCode: "ZPENAL", // Top service code penali (se apply=true)
+  },
+  simulateCancelAndGetPenaltyAmount: false,
+});
+
+// Solo simulazione penali
+const simulation = await client.setBookingStatus({
+  customerRecordCode: "000170",
+  bookingFileCode: "14/000081",
+  fileStatus: { value: "NULLIFIED" },
+  simulateCancelAndGetPenaltyAmount: true,
+});
+if (simulation.success) {
+  console.log(simulation.data.totalAmountDetailAfterCancellation);
+}
+```
+
+Stati `fileStatus.value` ammessi:  
+`QUOTATION` | `WORK_IN_PROGRESS` | `CONFIRMED` | `OPTIONED` | `NULLIFIED` | `CANCELED`
+
+### Hard — delete pratica
+
+```ts
+const result = await client.cancelBooking({
+  bookingFileCode: "14/000081",
+  customerRecordCode: "000170",
+});
+
+if (result.success) {
+  console.log(result.data.rsStatus.status); // "OK"
+}
+```
+
+| Metodo | Effetto |
+|---|---|
+| `setBookingStatus` → `CANCELED` / `NULLIFIED` | pratica resta, cambia stato |
+| `cancelBooking` | delete della pratica in AVES |
+
+---
+
+## 5. Modifica header (senza costi)
+
+```ts
+const result = await client.modBookingHeader({
+  bookingFileCode: "14/000043",
+  bookingFileStartDate: "2014-04-28",
+  customerRecordCode: "103737",
+  bookingNote: "Nota libera max 999 caratteri",
+  passengerList: {
+    passengerDetail: [
+      {
+        rph: "001",
+        name: "ADULTI 001",
+        sex: "M",
+        birthDate: "1964-09-26T00:00:00",
+        // categoryCode opzionale in Mod
+      },
+      {
+        rph: "002",
+        name: "ADULTI 002",
+        sex: "F",
+        birthDate: "1964-09-26T00:00:00",
+      },
+    ],
+  },
+  bookingFinancialInfo: {
+    customer_PaymentType: "BANK",
+  },
+});
+```
+
+---
+
+## Payload combinato tipico (Lead retroattivo + overwrite)
+
+Flusso consigliato dopo lo spike:
+
+1. Opzionale: `DELETE` voci obsolete  
+2. `selectedPackageDetail` con il Programma Lead  
+3. Nuovo `selectedServiceList` con costi e `packageCode` sui servizi  
+
+```ts
+const result = await client.modBookingServices({
+  customerRecordCode: "138311",
+  bookingFileCode: "14/036654",
+  selectedPackageDetail: {
+    pCode: "2014MDE0000010",
+    startDate: "2015-01-22T00:00:00",
+    endDate: "2015-01-25T00:00:00",
+  },
+  cancellableBookedServiceList: {
+    cancellableBookedServiceDetail: [
+      {
+        cancelOperationType: "DELETE",
+        serviceRefType: "RPH",
+        serviceRefValue: "001",
+      },
+      {
+        cancelOperationType: "DELETE",
+        serviceRefType: "RPH",
+        serviceRefValue: "002",
+      },
+    ],
+  },
+  selectedServiceList: {
+    selectedServiceDetail: [
+      {
+        sCode: "HT00110840",
+        ssCode: "DL",
+        avesServiceType: "TOP",
+        toServiceType: "RESIDENCE",
+        startDate: "2015-01-22T00:00:00",
+        endDate: "2015-01-25T00:00:00",
+        qty: "1",
+        pax: "2",
+        paxAssociated: [{ pax: "001" }, { pax: "002" }],
+        avesSession: "1",
+        avesServiceInfo: {
+          packageCode: "2014MDE0000010",
+          packageReference: "01",
+          costListCode: "G",
+          priceListCode: "G",
+        },
+        serviceFare: {
+          currencyCode: "EUR",
+          cost: "180.00",
+          price: "220.00",
+          costType: "FORFAIT",
+          priceType: "FORFAIT",
+        },
+      },
+    ],
+  },
+});
+```
+
+---
+
+## Tipi esportati (1.4.0)
+
+```ts
+import type {
+  ModFileServicesRQ,
+  ModFileHeaderRQ,
+  CancelFileRQ,
+  SetFileStatusRQ,
+  SetFileServiceStatusRQ,
+  BookingFileDetailRS, // alias di BookingFileRS
+  BookingStatusOnlyRS,
+  BookingFileRQ,
+  BookingFileRS,
+} from "aves-sdk";
+```
+
+---
+
+## Caveat operativi (da verificare live)
+
+1. `DELETE` vs `NULLIFY` — vincoli di stato pratica / documenti / pagamenti.  
+2. `selectedPackageDetail` su pratica già con package — replace vs add.  
+3. Differenza operativa `cancelBooking` vs status `CANCELED`/`NULLIFIED`.  
+4. Create/search Programma — **non disponibile** in questo SDK; serve doc Catalog/Package Datagest.

package/docs/spike-api-aves-analisi.md

@@ -0,0 +1,196 @@
+# Spike tecnico — Verifica API AVES
+
+**Data:** 29 luglio 2026  
+**Fonti (AVES XML 1.8.0):**
+
+- `Aves Xml 1.8.0 Eng - Booking CPX.pdf` (Booking Lite) — fonte principale
+- `Aves Xml 1.8.0 Eng - MasterRecord.pdf` — anagrafiche
+- `Aves Xml 1.8.0 Eng - Doc (1).pdf` (Booking Document) — documenti
+- `Aves Xml 1.8.0 Eng - CRM (2).pdf` (CRM) — anagrafiche CRM / ToDo
+
+---
+
+## Contesto
+
+Obiettivo: verificare le API necessarie per:
+
+1. creazione e ricerca del **Programma**
+2. aggiornamento delle **voci di costo** su una pratica esistente
+3. cancellazione di voci di costo (overwrite integrale della pratica)
+4. assegnazione / riassegnazione del Programma a una pratica già caricata (collegamento retroattivo Lead)
+5. annullabilità di una pratica
+
+Il **Programma** è la proprietà che raggruppa più pratiche sotto lo stesso cappello.
+
+---
+
+## Cos’è il Programma in AVES
+
+Nei documenti inglesi il Programma corrisponde a **Package / Program**:
+
+| Nome in doc | Uso |
+|---|---|
+| `pCode` / `PackageCode` | codice package su booking e servizi |
+| `SelectedPackageList` / `SelectedPackageDetail` | collegamento package → pratica |
+| `ProgramCode` | filtro stampa (Rooming List, Doc PDF) |
+| `DocumentType = PACKAGE` | archivio/ricerca documenti legati al package |
+
+Sulla pratica compare in `BookingFileDetail.PackageCode`; sui servizi in `AvesServiceInfo.PackageCode` + `PackageReference`.
+
+---
+
+## Esito per requisito
+
+### 1. Creazione e ricerca del Programma
+
+**Non coperto** dai quattro PDF disponibili.
+
+- Booking CPX **usa** il package (`SelectedPackageList`) ma non documenta create/search.
+- MasterRecord, Doc e CRM non espongono CRUD Package.
+- Nel Booking CPX compaiono riferimenti a `GetPackageDetail`, `CommitPackage`, `Search`/`GetDetail` sulle common structure Package, **senza endpoint**.
+
+**Azione:** richiedere a Datagest la documentazione Catalog/Package.
+
+---
+
+### 2. Aggiornamento voci di costo su pratica esistente
+
+**Coperto** — `ModBookingFileServices`
+
+```
+POST /interop/booking/v2/rest/ModBookingFileServices
+```
+
+- Obbligatori: `CustomerRecordCode`, `BookingFileCode`, `SelectedServiceList`
+- Per aggiornare una riga esistente: `BookedServiceRef` (RPH, es. `001`) + incrementare `AvesSession`
+- Costi/prezzi: `ServiceFare` (`Cost`, `CostTax`, `Price`, `PriceTax`, `CurrencyCode`, …) e/o `CostListCode` / `PriceListCode` in `AvesServiceInfo`
+
+`ModBookingFileHeader` gestisce solo header (cliente, pax, note, billing) — **non** i costi.
+
+---
+
+### 3. Cancellazione voci di costo (overwrite)
+
+**Coperto** — stesso endpoint `ModBookingFileServices`, via:
+
+```
+CancellableBookedServiceList / CancellableBookedServiceDetail
+  @CancelOperationType = NULLIFY | DELETE
+  @ServiceRefType      = RPH | FILE
+  @ServiceRefValue     = RPH del servizio
+```
+
+| Operazione | Significato tipico |
+|---|---|
+| `DELETE` | rimozione della voce (utile a wipe + re-insert) |
+| `NULLIFY` | annullamento della riga |
+
+Alternativa per singola riga: `SetBookingFileServiceStatus` → solo `NULLIFIED`  
+`POST /interop/booking/v2/rest/SetBookingFileServiceStatus`
+
+**Pattern overwrite proposto:** cancellare/nullificare tutte le voci → reinserire il nuovo set con `SelectedServiceList` (+ eventuale `SelectedPackageDetail`).
+
+Da verificare in test: vincoli di stato pratica / documenti / pagamenti su `DELETE`.
+
+---
+
+### 4. Assegnazione / riassegnazione Programma
+
+**Parzialmente coperto**
+
+| API | Cambia Package? |
+|---|---|
+| `CreateBookingFile` + `SelectedPackageList` | Sì (in creazione) |
+| `ModBookingFileServices` + `SelectedPackageDetail` | Sì — *“NEW program that need to be added to booked file”* |
+| `ModBookingFileHeader` | No |
+
+Endpoint: `POST /interop/booking/v2/rest/ModBookingFileServices`
+
+Campi `SelectedPackageDetail`: `pCode`, `StartDate`, `EndDate`, `GetServicesFromPackage` (solo ADV/GRP).
+
+**Da verificare in test:** se l’operazione **sostituisce** o **aggiunge** il package; impatto su `PackageCode` della pratica e sui servizi già presenti (necessario per Lead retroattivi).
+
+**Nota Lead / CRM:** il PDF CRM non collega Lead ↔ Programma. Espone solo:
+
+- `InsertToDo` — richiesta libera (es. preventivo) associata a un master CRM  
+  `POST /interop/cmr/v2/rest/InsertToDo`
+- insert/update/search master CRM (`/interop/cmr/v2/rest/InsertMasterRecord`, `SearchMasterRecords`)
+- in search: `BookingInfo` in sola lettura (ultima prenotazione / totali per anno), senza package né modifica pratica
+
+Il collegamento retroattivo Lead ↔ Programma resta da fare lato booking (`SelectedPackageDetail`), non via API CRM.
+
+---
+
+### 5. Annullabilità di una pratica
+
+**Coperto** — due modalità distinte:
+
+| API | Endpoint | Effetto |
+|---|---|---|
+| `CancelBookingFile` | `/interop/booking/v2/rest/CancelBookingFile` | delete della pratica |
+| `SetBookingFileStatus` | `/interop/booking/v2/rest/SetBookingFileStatus` | stato `CANCELED` o `NULLIFIED` |
+
+Per `NULLIFIED`: supporto penali (`Penalty`, `SimulateCancelAndGetPenaltyAmount`).
+
+**Da verificare in test:** differenza operativa tra delete e cambio stato, e stati ammessi.
+
+---
+
+## Matrice copertura documenti
+
+| Requisito | MasterRecord | Booking CPX | Doc | CRM |
+|---|---|---|---|---|
+| Create/search Programma | ❌ | ❌ (solo uso) | ❌ | ❌ |
+| Update costi | ❌ | ✅ | ❌ | ❌ |
+| Delete voci (overwrite) | ❌ | ✅ | ❌ | ❌ |
+| Riassegna Programma | ❌ | ✅ (da testare) | ❌ (solo filtro `ProgramCode`) | ❌ (ToDo/Lead senza package) |
+| Annulla pratica | ❌ | ✅ | ❌ | ❌ |
+
+---
+
+## Endpoint rilevanti (Booking)
+
+| Interfaccia | Endpoint |
+|---|---|
+| CreateBookingFile | `/interop/booking/v2/rest/CreateBookingFile` |
+| ModBookingFileHeader | `/interop/booking/v2/rest/ModBookingFileHeader` |
+| ModBookingFileServices | `/interop/booking/v2/rest/ModBookingFileServices` |
+| SetBookingFileStatus | `/interop/booking/v2/rest/SetBookingFileStatus` |
+| SetBookingFileServiceStatus | `/interop/booking/v2/rest/SetBookingFileServiceStatus` |
+| CancelBookingFile | `/interop/booking/v2/rest/CancelBookingFile` |
+
+Protocollo: REST XML, method `POST`, auth via `RqHeader` (`HostID`, `Xtoken`, …).
+
+---
+
+## PDF CRM — cosa contiene (fuori scope operativo)
+
+| Interfaccia | Endpoint | Scopo |
+|---|---|---|
+| InsertToDo | `/interop/cmr/v2/rest/InsertToDo` | richiesta libera (quotation) su CRM |
+| InsertMasterRecord | `/interop/cmr/v2/rest/InsertMasterRecord` | crea anagrafica CRM |
+| UpdateMasterRecord | (stesso schema ManageCrm) | aggiorna anagrafica CRM |
+| SearchMasterRecords | `/interop/cmr/v2/rest/SearchMasterRecords` | cerca anagrafiche CRM (+ `BookingInfo` read-only) |
+
+Nessun riferimento a Package/Programma, voci di costo, overwrite pratica o cancel booking.
+
+---
+
+## Gap aperti
+
+1. Documentazione API **CRUD/search Package (Programma)** — assente nei quattro PDF attuali.
+2. Semantica esatta **DELETE vs NULLIFY** e vincoli di stato.
+3. Comportamento **riassegnazione package** (replace vs add) per Lead retroattivi.
+4. Differenza **CancelBookingFile** vs status `CANCELED` / `NULLIFIED`.
+
+---
+
+## Prossimo passo consigliato
+
+Spike live sull’ambiente AVES, in ordine:
+
+1. create pratica con `SelectedPackageList`
+2. update costi (`ModBookingFileServices` + `ServiceFare` / `BookedServiceRef`)
+3. delete/nullify voci + re-insert (overwrite)
+4. riassegna package su pratica esistente
+5. cancel / set status `CANCELED`–`NULLIFIED`