@dokicasa/sdk 0.0.0-stage → 0.1.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/LICENSE +21 -0
- package/README.md +384 -2
- package/dist/index.cjs +1089 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +880 -0
- package/dist/index.d.ts +880 -0
- package/dist/index.js +1021 -0
- package/dist/index.js.map +1 -0
- package/package.json +71 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Dokidoc S.r.l. (DokiCasa)
|
|
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,385 @@
|
|
|
1
|
-
|
|
1
|
+

|
|
2
2
|
|
|
3
|
-
|
|
3
|
+

|
|
4
|
+

|
|
5
|
+

|
|
6
|
+

|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
L'SDK ufficiale per integrare il **Market Scanner di DokiCasa** in un'applicazione JavaScript o TypeScript, nel browser o in Node.
|
|
10
|
+
Le stesse cose che fa la nostra webapp, con un'API pulita:
|
|
11
|
+
|
|
12
|
+
- **ricerche catastali e documenti** (visure, ispezioni ipotecarie, note, mappe, elaborati planimetrici, intestatari, ricerche per codice fiscale), con un solo `await`;
|
|
13
|
+
- **avanzamento in tempo reale** via WebSocket, con il **polling automatico** come riserva se il socket cade o perde un evento;
|
|
14
|
+
- **censimenti di zona**, **monitoraggi**, **wallet e crediti**, **catalogo prezzi** e **stato del servizio**;
|
|
15
|
+
- **errori tipizzati** (credito insufficiente, censimento in corso, Sister fermo, limiti...), **ritentativi intelligenti**, **timeout** e **annullamento**;
|
|
16
|
+
- **verifica della firma dei webhook**;
|
|
17
|
+
- **tutto configurabile**: ambiente, URL, socket, timeout, ritentativi, polling, header, `fetch`, logger, hook.
|
|
18
|
+
|
|
19
|
+
Documentazione completa: **[docs.dokicasa.it/market-scanner-sdk](https://docs.dokicasa.it/market-scanner-sdk)**.
|
|
20
|
+
|
|
21
|
+
[TOC]
|
|
22
|
+
|
|
23
|
+
## Installazione
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install @dokicasa/sdk
|
|
27
|
+
# solo se vuoi gli aggiornamenti in tempo reale:
|
|
28
|
+
npm install pusher-js
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Funziona con Node 18+ e con i browser moderni. Non ha dipendenze obbligatorie: `pusher-js` serve solo per il tempo reale.
|
|
32
|
+
|
|
33
|
+
## Avvio rapido
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
import { createClient } from '@dokicasa/sdk';
|
|
37
|
+
|
|
38
|
+
const dk = createClient({
|
|
39
|
+
token: process.env.DOKICASA_TOKEN, // il tuo token API
|
|
40
|
+
environment: 'sandbox', // 'production' quando sei pronto
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
// Visura catastale: lancia la ricerca, aspetta il risultato, scarica il PDF
|
|
44
|
+
const visura = await dk.scanner.run(
|
|
45
|
+
'visura-catasto',
|
|
46
|
+
{ comune: 'Roma', provincia: 'RM', foglio: '123', particella: '45', tipo_visura: 'ANALITICA' },
|
|
47
|
+
{ onProgress: (p) => console.log(`${p.status} ${p.percentage}%`) },
|
|
48
|
+
);
|
|
49
|
+
|
|
50
|
+
const pdf = await dk.scanner.downloadDocument(visura);
|
|
51
|
+
// pdf.data (ArrayBuffer), pdf.filename, pdf.contentType
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`run` lancia la ricerca e aspetta che finisca. Se ti basta lanciarla, usa `create`; per aspettarla dopo, usa `wait`.
|
|
55
|
+
|
|
56
|
+
## Configurazione
|
|
57
|
+
|
|
58
|
+
Ogni opzione ha un valore predefinito sensato: di solito basta il token.
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
const dk = createClient({
|
|
62
|
+
token: 'xxx', // oppure getToken: async () => leggiIlToken()
|
|
63
|
+
environment: 'production', // 'production' | 'sandbox'
|
|
64
|
+
baseUrl: 'https://api.dokicasa.it', // sovrascrive l'URL dell'ambiente
|
|
65
|
+
timeoutMs: 60_000, // timeout di ogni chiamata HTTP
|
|
66
|
+
retry: {
|
|
67
|
+
maxRetries: 3, // ritentativi su errori temporanei
|
|
68
|
+
baseDelayMs: 500, // attesa iniziale, poi raddoppia (con jitter)
|
|
69
|
+
maxDelayMs: 10_000,
|
|
70
|
+
methods: ['GET', 'HEAD'], // le ricerche (POST) costano: mai ritentate da sole
|
|
71
|
+
statuses: [408, 425, 429, 500, 502, 503, 504],
|
|
72
|
+
},
|
|
73
|
+
polling: {
|
|
74
|
+
intervalMs: 2_000, // primo controllo dello stato
|
|
75
|
+
maxIntervalMs: 15_000, // il polling rallenta da solo nelle attese lunghe
|
|
76
|
+
backoffFactor: 1.5,
|
|
77
|
+
},
|
|
78
|
+
realtime: {
|
|
79
|
+
// valori predefiniti presi dall'ambiente; tutti sovrascrivibili
|
|
80
|
+
key: '...', wsHost: 'socket.dokicasa.it', wsPort: 443, forceTLS: true,
|
|
81
|
+
authEndpoint: 'https://api.dokicasa.it/broadcasting/auth',
|
|
82
|
+
Pusher, // facoltativo: il costruttore di pusher-js
|
|
83
|
+
pusherOptions: {}, // opzioni extra per pusher-js
|
|
84
|
+
}, // oppure realtime: false = solo polling
|
|
85
|
+
headers: { 'X-Correlation-Id': 'abc' },
|
|
86
|
+
fetch: customFetch, // per Node < 18, proxy, test
|
|
87
|
+
logger: console, // debug / info / warn / error
|
|
88
|
+
onRequest: (req) => {}, // hook prima di ogni chiamata
|
|
89
|
+
onResponse: (res) => {}, // hook dopo ogni risposta (con durata)
|
|
90
|
+
});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
| Opzione | Default | A cosa serve |
|
|
94
|
+
|---|---|---|
|
|
95
|
+
| `token` / `getToken` | obbligatorio | Autenticazione `Bearer`. `getToken` viene chiamato a ogni richiesta: comodo se il token si rinnova. |
|
|
96
|
+
| `environment` | `production` | Sceglie URL dell'API e del socket. |
|
|
97
|
+
| `baseUrl` | dall'ambiente | Per ambienti personalizzati o un proxy. |
|
|
98
|
+
| `timeoutMs` | `60000` | Timeout della singola chiamata HTTP. |
|
|
99
|
+
| `retry` | 3 ritentativi sulle letture | `false` per spegnerli. |
|
|
100
|
+
| `polling` | 2 s, fino a 15 s | Intervalli del polling quando il socket non c'è. |
|
|
101
|
+
| `realtime` | attivo se c'è `pusher-js` | `false` per usare solo il polling. |
|
|
102
|
+
| `headers` | — | Header aggiunti a ogni chiamata. |
|
|
103
|
+
| `actingUser` / `actingUserHeader` | — | Partner SSO: chiamate per conto di un utente ([vedi sotto](#partner-sso)). |
|
|
104
|
+
| `fetch` | `globalThis.fetch` | Implementazione di `fetch`. |
|
|
105
|
+
| `logger` | silenzioso | Log di ritentativi, socket e polling. |
|
|
106
|
+
| `onRequest` / `onResponse` | — | Hook per log, metriche e tracciamento. |
|
|
107
|
+
|
|
108
|
+
### Ambienti
|
|
109
|
+
|
|
110
|
+
| Ambiente | API | Socket |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `sandbox` | `https://api-dev.dokicasa.it` | `api-dev.dokicasa.it` |
|
|
113
|
+
| `production` | `https://api.dokicasa.it` | `socket.dokicasa.it` |
|
|
114
|
+
|
|
115
|
+
> Non mischiare gli ambienti: con l'API di sandbox e il socket di produzione il canale si iscrive ma non riceve eventi. Scegliendo `environment` l'SDK li tiene allineati da solo.
|
|
116
|
+
|
|
117
|
+
## Ricerche
|
|
118
|
+
|
|
119
|
+
### Tipi di ricerca
|
|
120
|
+
|
|
121
|
+
`dk.scanner.run(tipo, parametri, opzioni)` e `dk.scanner.create(tipo, parametri, opzioni)`. I parametri sono tipizzati per ogni tipo.
|
|
122
|
+
|
|
123
|
+
| Tipo | Cosa fa | Parametri principali |
|
|
124
|
+
|---|---|---|
|
|
125
|
+
| `catasto` | Immobili di una particella | `comune`, `foglio`, `particella`, `search_catasto_type` |
|
|
126
|
+
| `intestatari-catasto` | Intestatari di un immobile | `+ provincia`, `subalterno?` |
|
|
127
|
+
| `tax-data` | Immobili di un codice fiscale o partita IVA | `tax_code`, `provincia?` |
|
|
128
|
+
| `visura-catasto` | Visura per immobile (PDF) | `+ provincia`, `tipo_visura` |
|
|
129
|
+
| `visura-tax-data` | Visura per soggetto (PDF) | `tax_code`, `provincia`, `tipo_visura` |
|
|
130
|
+
| `ispezione-catasto` / `ispezione-tax-data` | Ispezione ipotecaria (PDF) | dati catastali / `tax_code` |
|
|
131
|
+
| `nota-catasto` / `nota-tax-data` | Nota di trascrizione (PDF) | `+ numero_registro_particolare`, `anno_registro`, `tipo_nota` |
|
|
132
|
+
| `mappa-catasto` | Estratto di mappa (PDF) | `tipo_richiesta`, `tipo_foglio`, `formato` |
|
|
133
|
+
| `elaborato-planimetrico` | Elaborato planimetrico (PDF) | dati catastali, poi `elaborato_planimetrico` |
|
|
134
|
+
| `elenco-immobili` | Elenco immobili della particella (PDF) | dati catastali |
|
|
135
|
+
| `search-fiscal-code` | Codice fiscale da nome e cognome | `first_name`, `last_name`, `provincia?` |
|
|
136
|
+
| `search-company` | Società da ragione sociale | `company_name` |
|
|
137
|
+
| `list-addresses` | Immobili da indirizzo | `indirizzo`, `comune`, `provincia` |
|
|
138
|
+
|
|
139
|
+
Lo schema completo di ogni tipo è nella [documentazione delle API](https://api.dokicasa.it/api/documentation#/Scanner).
|
|
140
|
+
|
|
141
|
+
### Ricerche in più passi
|
|
142
|
+
|
|
143
|
+
Alcune ricerche (visure e ispezioni con più immobili, mappe con più sezioni, omonimi) chiedono una scelta. Si rilancia con il valore scelto:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
const primo = await dk.scanner.run('visura-catasto', { ...dati, enable_multi_step: true });
|
|
147
|
+
|
|
148
|
+
if (primo.result?.needs_selection) {
|
|
149
|
+
const scelta = primo.result.rows_immobili![0]!.value;
|
|
150
|
+
const visura = await dk.scanner.run('visura-catasto', { ...dati, selected_value: scelta });
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Risultati, documenti, export
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
const req = await dk.scanner.get(id); // richiesta completa con result
|
|
158
|
+
const stato = await dk.scanner.status(id); // { status, percentage, children? }
|
|
159
|
+
|
|
160
|
+
// tutti i risultati, pagina dopo pagina
|
|
161
|
+
for await (const immobile of dk.scanner.iterateResults(id, { filters: { categoria: ['A/2'] } })) {
|
|
162
|
+
console.log(immobile);
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
const docs = await dk.scanner.documents(id); // documenti legati alla ricerca
|
|
166
|
+
const file = await dk.scanner.downloadDocument(req); // PDF di result.pdf_path
|
|
167
|
+
await dk.scanner.exportXls(id, { comune: ['Roma'] }); // Excel via email (a pagamento)
|
|
168
|
+
await dk.scanner.monitor(id, { models: [] }); // monitora tutto (a pagamento)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Prima di lanciare: prezzi e stato del servizio
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
const catalogo = await dk.system.services(); // prezzo e crediti per ogni tipo
|
|
175
|
+
const stato = await dk.system.health(); // Sister: ok, degraded o down, anche per tipo
|
|
176
|
+
|
|
177
|
+
// oppure lascia controllare all'SDK: se il servizio è fermo non lancia (e non spende)
|
|
178
|
+
await dk.scanner.create('visura-catasto', dati, { checkHealth: true });
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
## Tempo reale
|
|
182
|
+
|
|
183
|
+
Con `pusher-js` installato, `run` e `wait` seguono l'avanzamento sul canale privato della ricerca, senza polling. Il socket è *best effort*, e l'SDK lo tratta così:
|
|
184
|
+
|
|
185
|
+
- mentre il socket si collega o è attivo, fa solo un **controllo di sicurezza lento**, per recuperare un evento perso (succede, per esempio, durante un riavvio del server);
|
|
186
|
+
- se il socket **cade** o il canale viene **negato**, passa al **polling** con intervalli crescenti;
|
|
187
|
+
- appena iscritto, **rilegge lo stato**: l'evento finale potrebbe essere arrivato prima dell'iscrizione;
|
|
188
|
+
- a fine attesa **chiude il canale**. I canali sono condivisi: si chiudono quando smette di ascoltare l'ultimo.
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
import Pusher from 'pusher-js';
|
|
192
|
+
const dk = createClient({ token, realtime: { Pusher } });
|
|
193
|
+
|
|
194
|
+
// solo ascolto, senza aspettare
|
|
195
|
+
const stop = dk.scanner.watch(id, (e) => console.log(e.status, e.percentage));
|
|
196
|
+
stop();
|
|
197
|
+
|
|
198
|
+
// eventi personali: notifiche, storia dell'immobile pronta, report AML
|
|
199
|
+
dk.realtime.user(userId, {
|
|
200
|
+
onToast: (t) => mostraNotifica(t.title, t.message),
|
|
201
|
+
onPropertyHistory: (e) => e.status === 'ready' && caricaStoria(e.resource_url),
|
|
202
|
+
});
|
|
203
|
+
|
|
204
|
+
dk.realtime.onStateChange((stato) => console.log('socket', stato));
|
|
205
|
+
dk.close(); // chiude il socket quando l'app si smonta
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
## Censimento di zona
|
|
209
|
+
|
|
210
|
+
Un censimento è una richiesta padre a cui si aggiungono le ricerche per indirizzo. Si può avere un solo censimento alla volta per utente.
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
const { scanner_request_id: padre } = await dk.census.create();
|
|
214
|
+
|
|
215
|
+
const candidati = await dk.census.findAddresses({ indirizzo: 'Via Roma', comune: 'Torino', provincia: 'TO' });
|
|
216
|
+
const [valore] = Object.keys(candidati.result!.addresses!);
|
|
217
|
+
await dk.census.addAddress(padre, { indirizzo: 'Via Roma', comune: 'Torino', provincia: 'TO', address_value: valore!, numero_civico: '10' });
|
|
218
|
+
|
|
219
|
+
await dk.census.switchToOwners(padre); // facoltativo: anche gli intestatari
|
|
220
|
+
const censimento = await dk.census.wait(padre);
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
`census.create({ searchMode: 'MULTI_ADDRESS' })` fa invece una ricerca singola su più vie, fino a 5.
|
|
224
|
+
|
|
225
|
+
## Monitoraggi, wallet e crediti
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
await dk.monitorings.fromCatasto({ comune: 'Milano', provincia: 'MI', foglio: '10', particella: '20', webhook_url: 'https://...' });
|
|
229
|
+
const lista = await dk.monitorings.list({ type: 'IMMOBILE', text: 'Rossi' });
|
|
230
|
+
await dk.monitorings.renew(id);
|
|
231
|
+
|
|
232
|
+
const { wallet } = await dk.account.wallet();
|
|
233
|
+
const crediti = await dk.account.credits();
|
|
234
|
+
const riepilogo = await dk.account.overview(); // crediti, wallet e abbonamenti in una chiamata
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
## Errori
|
|
238
|
+
|
|
239
|
+
Ogni errore estende `DokicasaError` e ha un `code`. Quelli dell'API hanno anche `status` e `body`. Per gestire un caso specifico basta `instanceof`:
|
|
240
|
+
|
|
241
|
+
| Classe | Quando | Dati utili |
|
|
242
|
+
|---|---|---|
|
|
243
|
+
| `InsufficientFundsError` | Crediti o saldo insufficienti (`AMOUNT_NOT_ENOUGH`) | `missingAmount`, `checkoutLink` |
|
|
244
|
+
| `CensusInProgressError` | C'è già un censimento in corso (`PENDING_CENSIMENTO`) | |
|
|
245
|
+
| `ServiceUnavailableError` | Sister fermo, in manutenzione o sovraccarico | |
|
|
246
|
+
| `ValidationError` | Dati non validi (422), codice fiscale non valido | `fields`, `isDuplicate` |
|
|
247
|
+
| `RateLimitError` | Troppe richieste (429) | `retryAfterSeconds` |
|
|
248
|
+
| `PartnerPricingRequiredError` | Partner senza listino per quel tipo | `scannerType` |
|
|
249
|
+
| `AuthenticationError` / `PermissionError` / `NotFoundError` | 401 / 403 / 404 | |
|
|
250
|
+
| `ScanFailedError` | La ricerca è finita in `ERROR` o `CANCELLED` | `request` |
|
|
251
|
+
| `TimeoutError` / `AbortError` / `NetworkError` | Tempo scaduto, annullata, rete giù | |
|
|
252
|
+
|
|
253
|
+
```ts
|
|
254
|
+
import { InsufficientFundsError, ServiceUnavailableError, ValidationError, ScanFailedError } from '@dokicasa/sdk';
|
|
255
|
+
|
|
256
|
+
try {
|
|
257
|
+
await dk.scanner.run('visura-catasto', dati);
|
|
258
|
+
} catch (e) {
|
|
259
|
+
if (e instanceof InsufficientFundsError) return apriCheckout(e.checkoutLink);
|
|
260
|
+
if (e instanceof ValidationError && e.isDuplicate) return avvisa('Ricerca già in corso');
|
|
261
|
+
if (e instanceof ServiceUnavailableError) return avvisa('Catasto momentaneamente non disponibile');
|
|
262
|
+
if (e instanceof ScanFailedError) return avvisa(`Ricerca non riuscita: ${e.request.details ?? ''}`);
|
|
263
|
+
throw e;
|
|
264
|
+
}
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## Attese, timeout e annullamento
|
|
268
|
+
|
|
269
|
+
```ts
|
|
270
|
+
const controller = new AbortController();
|
|
271
|
+
|
|
272
|
+
const risultato = await dk.scanner.run('ispezione-tax-data', { tax_code: 'RSSMRA80A01H501U' }, {
|
|
273
|
+
signal: controller.signal, // annulla chiamate e attesa
|
|
274
|
+
timeoutMs: 10 * 60_000, // attesa massima (default 15 minuti)
|
|
275
|
+
maxConsecutiveErrors: 5, // errori di rete tollerati durante l'attesa
|
|
276
|
+
throwOnFailure: false, // restituisce la richiesta anche se è finita in ERROR
|
|
277
|
+
realtime: false, // solo polling per questa attesa
|
|
278
|
+
});
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Le letture (`GET`) vengono ritentate da sole su rete giù, timeout, 429 e 5xx, con attesa esponenziale e rispettando `Retry-After`. **Le ricerche no**: costano crediti e un doppio lancio può far pagare due volte. Una ricerca identica entro pochi secondi viene comunque rifiutata dall'API come doppione (`ValidationError.isDuplicate`).
|
|
282
|
+
|
|
283
|
+
## Partner SSO
|
|
284
|
+
|
|
285
|
+
I partner che fanno entrare i propri utenti con l'SSO possono chiamare **per conto di un utente** con l'header `X-Dokicasa-User` (formato `wikicasa:<id>` oppure `email:<email>`):
|
|
286
|
+
|
|
287
|
+
```ts
|
|
288
|
+
const agente = dk.as({ source: 'wikicasa', id: 98765 }); // oppure dk.as({ email: 'mario@agenzia.it' })
|
|
289
|
+
await agente.account.wallet();
|
|
290
|
+
await agente.scanner.run('catasto', dati);
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
`as()` restituisce una copia del client: l'originale resta com'era, e anche l'autorizzazione dei canali in tempo reale passa l'header. Il nome dell'header si cambia con `actingUserHeader`.
|
|
294
|
+
|
|
295
|
+
> L'header va abilitato sull'account del partner da DokiCasa: chiedilo al tuo referente.
|
|
296
|
+
|
|
297
|
+
## Webhook
|
|
298
|
+
|
|
299
|
+
Per ricevere l'esito senza restare in attesa, passa `webhook` (o `callback`) alla ricerca. DokiCasa firma il corpo con HMAC-SHA256 e la chiave è il tuo token API. Verifica la firma **sul corpo grezzo**, prima di fare `JSON.parse`:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
import { parseWebhook } from '@dokicasa/sdk';
|
|
303
|
+
|
|
304
|
+
app.post('/webhook/dokicasa', express.raw({ type: '*/*' }), async (req, res) => {
|
|
305
|
+
try {
|
|
306
|
+
const evento = await parseWebhook({ body: req.body, signature: req.get('Signature'), secret: process.env.DOKICASA_TOKEN! });
|
|
307
|
+
// evento.scanner_request.status === 'SUCCESS' ...
|
|
308
|
+
res.sendStatus(200);
|
|
309
|
+
} catch {
|
|
310
|
+
res.sendStatus(401);
|
|
311
|
+
}
|
|
312
|
+
});
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
## Sicurezza
|
|
316
|
+
|
|
317
|
+
- Il token API vale come una password: **non metterlo nel codice e non pubblicarlo nel frontend**. Nel browser usa il token del singolo utente (per esempio dopo l'SSO), mai quello del partner.
|
|
318
|
+
- Per l'uso server-to-server il tuo account deve avere l'origine abilitata (`ORIGIN_NOT_ALLOWED` altrimenti): chiedilo al tuo referente.
|
|
319
|
+
|
|
320
|
+
## Demo nel browser
|
|
321
|
+
|
|
322
|
+
Una pagina per provare l'SDK senza scrivere codice: avanzamento con l'origine di ogni aggiornamento (⚡ socket, ↻ polling), scelta nelle ricerche in più passi, download dei PDF, errori spiegati, annullamento e cronologia.
|
|
323
|
+
|
|
324
|
+
```bash
|
|
325
|
+
npm install && npm run build
|
|
326
|
+
DOKICASA_TOKEN=<token di test> npm run demo # http://localhost:5174, sandbox
|
|
327
|
+
DOKICASA_ENV=production DOKICASA_TOKEN=... npm run demo
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Su `http://localhost:5174/esempi` ci sono gli stessi esempi di `examples/` da lanciare dal browser, con il codice e il registro in diretta.
|
|
331
|
+
|
|
332
|
+
Il server della demo non ha dipendenze. Inoltra `/api` e `/broadcasting/auth` all'API, perché dal browser in locale le chiamate dirette verrebbero bloccate dal CORS; il socket invece si collega direttamente a Reverb.
|
|
333
|
+
|
|
334
|
+
## Esempi
|
|
335
|
+
|
|
336
|
+
Script pronti da lanciare in `examples/` (`DOKICASA_TOKEN=... node examples/01-visura-catastale.mjs`; default sandbox, `DOKICASA_ENV=production` per la produzione):
|
|
337
|
+
|
|
338
|
+
| Esempio | Cosa mostra |
|
|
339
|
+
|---|---|
|
|
340
|
+
| `01-visura-catastale` | Visura con avanzamento in tempo reale e PDF salvato su disco |
|
|
341
|
+
| `02-immobili-da-codice-fiscale` | Immobili di un soggetto e intestatari di un immobile |
|
|
342
|
+
| `03-ricerca-in-piu-passi` | Scelta tra più immobili e rilancio con `selected_value` |
|
|
343
|
+
| `04-censimento-di-zona` | Censimento: padre, indirizzi candidati, attesa, risultati |
|
|
344
|
+
| `05-monitoraggi` | Monitoraggio da catasto, nota, elenco, rimozione |
|
|
345
|
+
| `06-gestione-errori` | Ogni errore con la sua classe e il messaggio per l'utente |
|
|
346
|
+
| `07-eventi-in-tempo-reale` | Ascolto di una ricerca, eventi personali, stato del socket |
|
|
347
|
+
| `08-webhook-server` | Server che riceve i webhook e verifica la firma |
|
|
348
|
+
| `09-partner-sso` | Chiamate per conto di un utente (`as()`) |
|
|
349
|
+
| `10-risultati-ed-export` | Filtri, risultati filtrati, documenti, export e monitoraggio |
|
|
350
|
+
| `11-prezzi-e-stato-servizio` | Catalogo prezzi, stato di Sister, saldo, `checkHealth` |
|
|
351
|
+
| `12-annullamento-e-ripresa` | Annullare un'attesa e riprenderla |
|
|
352
|
+
|
|
353
|
+
## Prove end-to-end
|
|
354
|
+
|
|
355
|
+
Oltre ai test con server finto, c'è una suite che gira contro la **sandbox vera** (`api-dev.dokicasa.it`): coda asincrona, socket Reverb, PDF, censimento, monitoraggi ed errori reali. Non consuma credito.
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
DOKICASA_E2E_TOKEN=<token di test> npm run test:e2e
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
## Sviluppo
|
|
362
|
+
|
|
363
|
+
```bash
|
|
364
|
+
npm install
|
|
365
|
+
npm test # 49 test con fetch e socket finti: nessuna chiamata vera
|
|
366
|
+
npm run test:e2e # 11 prove contro la sandbox vera (serve DOKICASA_E2E_TOKEN)
|
|
367
|
+
npm run demo # demo nel browser
|
|
368
|
+
npm run typecheck
|
|
369
|
+
npm run build # dist/ in ESM + CJS con i tipi
|
|
370
|
+
```
|
|
371
|
+
|
|
372
|
+
```
|
|
373
|
+
src/
|
|
374
|
+
├── client.ts # DokicasaClient, createClient, as()
|
|
375
|
+
├── config.ts # opzioni, ambienti, valori predefiniti
|
|
376
|
+
├── http.ts # fetch, timeout, annullamento, ritentativi, hook
|
|
377
|
+
├── errors.ts # errori tipizzati
|
|
378
|
+
├── realtime/ # socket Reverb (pusher-js), canali condivisi
|
|
379
|
+
├── resources/ # scanner, censimenti, monitoraggi, conto, sistema
|
|
380
|
+
├── webhooks.ts # verifica della firma
|
|
381
|
+
└── types.ts # tipi di richieste e risultati
|
|
382
|
+
test/ # unit (fetch e socket finti) + e2e/ contro la sandbox
|
|
383
|
+
examples/ # uno script per ogni utilizzo
|
|
384
|
+
demo/ # pagina di prova + server senza dipendenze
|
|
385
|
+
```
|