Form — Server-to-server

Crea e gestisci pratiche direttamente dal tuo backend, autenticandoti con la api_token (Bearer). Base URL: https://app.dokicasa.it.

Endpoint principali

Method	Path	Cosa fa
GET	/api/v3/catalog-forms	Tutti i form disponibili (servizi, contratti, bundle) con slug e form_url — pubblico
GET	/api/list-form/canone-concordato-{citta}	Lista degli step del flusso per una città
GET	/api/v3/form/{slug}	Schema (campi) di un form
POST	/api/v3/form/{slug}	Submit del form → crea una pratica
PUT	/api/v3/form/{bundleUserServiceId}	Aggiorna un form già inviato
GET	/api/v3/user/{id}/services	Lista pratiche (filtrabile per external_id)
GET	/api/v3/practices/{practice}	Dettaglio + stato di una pratica
GET	/api/v3/practices/{practice}/tasks	Task collegati alla pratica

0. Scopri i form disponibili

Un'unica chiamata pubblica ti dà tutti i form, ordinati per nome:

curl https://app.dokicasa.it/api/v3/catalog-forms -H "Accept: application/json"

Ogni voce ha kind (service / contract / bundle), name, slug e form_url. I bundle includono steps (un form per step):

[
  { "kind": "service", "name": "Visura catastale", "slug": "visura-catastale",
    "form_url": "/api/v3/form/visura-catastale", "steps": [] },
  { "kind": "bundle", "name": "Canone Concordato", "slug": "canone-concordato",
    "form_url": null, "steps": [
      { "step": 1, "name": "Contratto", "type": "Contract",
        "slug": "contratto-locazione", "form_url": "/api/v3/form/contratto-locazione" }
    ] }
]

La lista interattiva (con copia-slug) è anche in SDK JavaScript → Form disponibili.

1. Crea una pratica

PHP / Laravel

$res = Http::withToken(env('DOKICASA_TOKEN'))
    ->acceptJson()
    ->post('https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4', [
        'form' => [ /* ...risposte dei campi... */ ],
        'metadata' => [
            'external_id' => 'ordine_8842', // il TUO id, per ritrovarla dopo
        ],
    ])
    ->json();

// $res['id'], $res['external_id']

Node.js

const res = await fetch(
  'https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.DOKICASA_TOKEN}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      form: { /* ...risposte... */ },
      metadata: { external_id: 'ordine_8842' },
    }),
  }
).then((r) => r.json())

cURL

curl -X POST \
  https://app.dokicasa.it/api/v3/form/locazione-ad-uso-abitativo-4-4 \
  -H "Authorization: Bearer $DOKICASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"form":{},"metadata":{"external_id":"ordine_8842"}}'

WARNING

POST /api/v3/form/{slug} può scalare credito dal wallet del partner. Verifica il saldo prima di automatizzare creazioni massive.

2. Ritrova le tue pratiche

$practices = Http::withToken(env('DOKICASA_TOKEN'))
    ->acceptJson()
    ->get('https://app.dokicasa.it/api/v3/user/me/services', [
        'filter[external_id]' => 'ordine_8842',
    ])
    ->json();

3. Stato e task di una pratica

$id = 84213; // id pratica oppure uuid pubblico

$practice = Http::withToken(env('DOKICASA_TOKEN'))->acceptJson()
    ->get("https://app.dokicasa.it/api/v3/practices/{$id}")->json();
// $practice['status'] → es. WAITING / DOING / ...

$tasks = Http::withToken(env('DOKICASA_TOKEN'))->acceptJson()
    ->get("https://app.dokicasa.it/api/v3/practices/{$id}/tasks")->json();
// $tasks['tasks'] → Activity (type=TASK) con status TO_DO / DOING / DONE

TIP

Con l'uuid al posto dell'id numerico, GET /practices/{practice} e .../tasks sono pubbliche (senza Bearer): comode per un link in sola lettura. Con l'id numerico servono Bearer e proprietà della pratica.

Riferimento OpenAPI

La specifica completa (parametri, schemi, risposte) è qui sotto, generata dalla stessa spec pubblicata anche su api.dokicasa.it/api-doc/.