Introduzione

Questa documentazione raccoglie tutte le integrazioni che Dokicasa mette a disposizione dei partner, organizzate in capitoli:

• Integrazione Form — crea/gestisci pratiche, sia da backend (server-to-server) sia incorporando il form nel tuo sito con l'SDK JavaScript.
• Integrazione Market Scanner — dati immobiliari/catastali, visure, ispezioni, aggiornamenti realtime.

Ambienti

Ambiente	Base URL API
Produzione	https://app.dokicasa.it
Sandbox / staging	https://staging.dokicasa.it (su richiesta)

NOTE

Gli endpoint del flusso pratiche sono serviti da app.dokicasa.it (prefisso /api/v3). I dati Market Scanner sono serviti da api.dokicasa.it.

Autenticazione

A seconda dell'integrazione si usano due meccanismi.

1. api_token (Bearer) — chiamate server-to-server

La maggior parte degli endpoint pratiche è protetta da auth:api: si passa il token del partner/utente nell'header Authorization.

curl https://app.dokicasa.it/api/v3/user/me/services \
  -H "Authorization: Bearer <api_token>" \
  -H "Accept: application/json"

Il token identifica l'utente: ogni partner opera sulle proprie pratiche.

2. api_key + user_token — SDK nel browser

L'SDK <dokicasa-form> gira lato client e usa una coppia:

• api_key (pk_live_…) — chiave pubblica del partner, identifica l'app.
• user_token — token a breve scadenza che il tuo backend emette per l'utente finale (così la api_token reale non finisce mai nel browser).

Vedi i dettagli in SDK JavaScript → User token.

WARNING

Non esporre mai la api_token segreta in pagine pubbliche o nel frontend. Nel browser si usa solo api_key + user_token.

Il concetto chiave: external_id

Quando crei una pratica puoi allegare un tuo identificativo (external_id): ti serve per ritrovare quella pratica nelle letture successive (filter[external_id]), collegandola al tuo sistema.

Tu crei la pratica  ──(external_id: "ordine_8842")──►  Dokicasa
                                                         │
   Leggi stato/task ◄──(filter[external_id]=ordine_8842)─┘

Flusso tipico end-to-end

1. Crea la pratica → POST /api/v3/form/{slug} (con external_id).
2. Leggi le tue pratiche → GET /api/v3/user/me/services?filter[external_id]=…
3. Stato della singola pratica → GET /api/v3/practices/{practice}
4. Task della pratica → GET /api/v3/practices/{practice}/tasks
5. Reagisci agli eventi via webhook (practice.*).

Per assistenti AI

Esistono prompt pronti (CLAUDE.md) che descrivono l'intero flusso con esempi end-to-end e checklist — utili se integri tramite Claude Code, Cursor o Copilot.