Introduction

This documentation gathers all the integrations Dokicasa offers to partners, organized into chapters:

• Form integration — create/manage practices, either from your backend (server-to-server) or by embedding the form in your site with the JavaScript SDK.
• Market Scanner integration — real estate/cadastral data, deeds, inspections, realtime updates.

Environments

Environment	API base URL
Production	https://app.dokicasa.it
Sandbox / staging	https://staging.dokicasa.it (on request)

NOTE

The practices flow endpoints are served by app.dokicasa.it (prefix /api/v3). Market Scanner data is served by api.dokicasa.it.

Authentication

Depending on the integration, two mechanisms are used.

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

Most practice endpoints are protected by auth:api: pass the partner/user token in the Authorization header.

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

The token identifies the user: each partner operates on their own practices.

2. api_key + user_token — SDK in the browser

The <dokicasa-form> SDK runs client-side and uses a pair:

• api_key (pk_live_…) — the partner's public key, identifies the app.
• user_token — a short-lived token that your backend issues for the end user (so the real api_token never reaches the browser).

See the details in JavaScript SDK → User token.

WARNING

Never expose the secret api_token in public pages or the frontend. In the browser use only api_key + user_token.

The key concept: external_id

When you create a practice you can attach your own identifier (external_id): you'll need it to look up that practice in later reads (filter[external_id]), linking it to your system.

You create the practice  ──(external_id: "order_8842")──►  Dokicasa
                                                             │
   Read status/tasks ◄──(filter[external_id]=order_8842)─────┘

Typical end-to-end flow

1. Create the practice → POST /api/v3/form/{slug} (with external_id).
2. Read your practices → GET /api/v3/user/me/services?filter[external_id]=…
3. Status of a single practice → GET /api/v3/practices/{practice}
4. Tasks of the practice → GET /api/v3/practices/{practice}/tasks
5. React to events via webhooks (practice.*).

For AI assistants

Ready-made prompts (CLAUDE.md) describe the whole flow with end-to-end examples and a checklist — handy if you integrate via Claude Code, Cursor or Copilot.