Sigilli su PDF

✦

Integra con un assistente AI

Scarica o copia il prompt di integrazione per Sigilli su PDF e incollalo in Claude Code, Cursor o Copilot: contiene auth, esempi end-to-end e checklist.

Apri

Appone uno o più sigilli su un PDF e ne registra la certificazione (numero, data e documento sigillato). È la stessa funzione usata dalla certificazione dei documenti a canone concordato: stesso motore, stesso risultato, esposto come chiamata API.

Ci sono due modi di chiamarla:

POST /api/partner/certifications — la chiamata che copre tutti e due i casi. Il bundle è un campo facoltativo: con user_bundle_id la certificazione resta registrata su quella pratica (e se c'è lo step di certificazione il documento finisce anche fra i suoi allegati); senza, ci mandi il documento e basta, ed è quello che ti serve quando ciò che certifichi su DokiCasa non ha nessuna pratica dietro.
POST /api/partner/user-bundle/{id}/seal — la rotta storica, solo sul bundle. Resta dov'è: se l'hai già integrata non devi cambiare niente.


Base URL	`https://api.dokicasa.it`
Auth	`Authorization: Bearer <api_token>`
Content-Type	`multipart/form-data` (con upload) o `application/json` (con `attachments`)

La chiamata è sincrona: quando risponde, il PDF sigillato è già pronto e registrato.

WARNING

Non è disponibile in sandbox: la sigillatura passa dal fornitore di firma qualificata, quindi ogni chiamata produce un documento reale e viene addebitata.

Prerequisiti

Listino attivo per il tipo SEAL_PDF sul tuo account. Senza, la chiamata risponde 403 PARTNER_PRICING_REQUIRED: contattaci per attivarlo.
Bundle (user_bundle) intestato al tuo utente, solo per la chiamata sul bundle. Non serve aver creato lo step di certificazione. L'id del bundle te lo restituisce la creazione pratica — POST /api/v3/form/{slug} — nel campo user_bundle_id. Con POST /api/partner/certifications il bundle non serve affatto.
Almeno un sigillo censito sul tuo account, su quello del tuo capogruppo, oppure appartenente all'ente certificatore (l'associazione) per cui sei abilitato a certificare — in quest'ultimo caso il sigillo può stare su un altro account.

I tuoi sigilli

GET /api/users/me/seals

Elenca i sigilli disponibili: i tuoi, quelli del capogruppo se ne hai uno, e quelli dell'ente certificatore per cui sei abilitato a certificare.

json

[
  {
    "id": 42,
    "first_name": "Mario",
    "last_name": "Rossi",
    "email": "mario.rossi@example.it",
    "image": "sigilli/mario-rossi.png",
    "is_verified": true,
    "certification_body_id": null,
    "certification_body_name": null
  },
  {
    "id": 57,
    "first_name": "Associazione",
    "last_name": "Proprietari",
    "email": "info@associazione.it",
    "image": "sigilli/associazione.png",
    "is_verified": true,
    "certification_body_id": 3,
    "certification_body_name": "Associazione Proprietari"
  }
]

L'id di questa lista è quello da passare nella chiamata di apposizione.

certification_body_id e certification_body_name dicono per conto di quale ente rilasci la certificazione con quel sigillo: il numero, il testo in calce e la posizione del timbro sulla pagina li detta l'ente. Sono null per i sigilli che non appartengono a nessun ente, che si comportano come hanno sempre fatto.

Se il tuo account è abilitato su più enti, la lista contiene i sigilli di tutti, ognuno con il proprio ente.

Apporre i sigilli

POST /api/partner/user-bundle/{user_bundle_id}/seal

Campo	Tipo	Note
`seals[].id`	integer	Uno o più sigilli, applicati nell'ordine ricevuto. Obbligatorio se non passi `seal_id`
`seal_id`	integer	Scorciatoia per il caso a un sigillo solo, alternativa a `seals[]`
`file`	file	PDF da sigillare, max 20 MB. Se lo carichi, ha la precedenza su `attachments`
`attachments[].url`	string	In alternativa al file: URL pubblici dei PDF da sigillare, uniti in un unico documento
`attachments[].name`	string	Nome dell'allegato, opzionale (compare nei messaggi di errore)

Il sigillo dev'essere tuo, del tuo capogruppo o dell'ente per cui sei abilitato a certificare, e il bundle dev'essere tuo: altrimenti 403.

Con un PDF caricato (due sigilli)

bash

curl -X POST https://api.dokicasa.it/api/partner/user-bundle/12345/seal \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@contratto.pdf" \
  -F "seals[0][id]=42" \
  -F "seals[1][id]=57"

Con allegati già online (un sigillo)

bash

curl -X POST https://api.dokicasa.it/api/partner/user-bundle/12345/seal \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "seals": [{ "id": 42 }],
        "attachments": [
          { "name": "Contratto", "url": "https://tuo-storage/contratto.pdf" },
          { "name": "Allegato A", "url": "https://tuo-storage/allegato-a.pdf" }
        ]
      }'

Risposta — `201 Created`

json

{
  "status": "READY",
  "numero_certificazione": "12/2026",
  "document": {
    "name": "certificazione_12345_12.pdf",
    "path": "https://r3-it.storage.cloud.it/storage/bundles-certifications/12345/certificazione_12345_12.pdf"
  },
  "seals": [
    {
      "id": 7,
      "certification_body_id": 3,
      "certification_body_name": "Associazione Proprietari"
    }
  ]
}

seals elenca i sigilli apposti, ognuno con il suo ente (null se il sigillo non è di nessun ente).

La certificazione resta registrata sul bundle. Se il bundle ha già lo step di certificazione, lo stesso documento finisce anche fra gli allegati della pratica di quello step, con nome Documento Certificato: lo rileggi da GET /api/user-service/{id}/attachments.

Certificare con o senza bundle

POST /api/partner/certifications

Stessa sigillatura, stessa numerazione, stesso documento in uscita. Il bundle lo scegli tu, campo per campo: se passi user_bundle_id la certificazione si registra su quella pratica esattamente come dalla rotta sui sigilli; se non lo passi, non c'è nessuna pratica DokiCasa dietro — niente step da preparare, niente bundle da creare prima.

Campo	Tipo	Note
`external_id`	string	Obbligatorio. L'identificativo della certificazione sul tuo gestionale, max 100 caratteri
`user_bundle_id`	integer	Facoltativo. Il bundle su cui registrare la certificazione. Omettilo per certificare un documento che da noi non ha nessuna pratica
`seals[].id`	integer	Uno o più sigilli, applicati nell'ordine ricevuto. Obbligatorio se non passi `seal_id`
`seal_id`	integer	Scorciatoia per il caso a un sigillo solo
`file`	file	PDF da certificare, max 20 MB. Se lo carichi, ha la precedenza su `attachments`
`attachments[].url`	string	In alternativa al file: URL pubblici dei PDF, uniti in un unico documento
`attachments[].name`	string	Nome dell'allegato, opzionale

bash

# Documento tuo, nessuna pratica da noi
curl -X POST https://api.dokicasa.it/api/partner/certifications \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "external_id=CONTRATTO-2026-0031" \
  -F "file=@contratto.pdf" \
  -F "seals[0][id]=42"

# Stessa chiamata, ma registrata su un bundle nostro
curl -X POST https://api.dokicasa.it/api/partner/certifications \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "external_id=CONTRATTO-2026-0031" \
  -F "user_bundle_id=12345" \
  -F "file=@contratto.pdf" \
  -F "seals[0][id]=42"

Con user_bundle_id la risposta riporta quel bundle, il documento viene registrato sulla pratica e — se lo step di certificazione esiste — allegato anche lì come Documento Certificato. Il bundle dev'essere tuo, altrimenti 403 BUNDLE_NOT_OWNED.

Risposta — `201 Created`

json

{
  "id": 918,
  "status": "READY",
  "external_id": "CONTRATTO-2026-0031",
  "numero_certificazione": "13/2026",
  "number": 13,
  "year": 2026,
  "certified_at": "2026-09-18 11:20:44",
  "user_bundle_id": null,
  "document": {
    "name": "certificazione_doc-918_13.pdf",
    "path": "https://r3-it.storage.cloud.it/storage/certifications/918/certificazione_doc-918_13.pdf"
  },
  "documents": [{ "name": "certificazione_doc-918_13.pdf", "path": "..." }],
  "seals": [{ "id": 42, "certification_body_id": 3, "certification_body_name": "Associazione Proprietari" }]
}

`external_id`, cioè: non certificare due volte

Ogni chiamata produce una firma qualificata reale e consuma un numero di serie. external_id è la tua garanzia contro il doppione: se richiami con la stessa chiave ti viene restituita la certificazione già emessa — 200 OK invece di 201 — senza rifirmare e senza addebitare una seconda volta.

Un timeout di rete, quindi, si ritenta senza pensarci: quello che conta è mandare la stessa chiave. Se invece una certificazione con quella chiave è ancora in lavorazione la risposta è 409 CERTIFICATION_IN_PROGRESS; se un tentativo precedente era fallito, il nuovo si tiene il numero già assegnato invece di bruciarne un altro.

Rileggere le certificazioni

GET /api/partner/certifications/{id}
GET /api/partner/certifications?external_id=...&status=READY&per_page=25

L'elenco è il tuo registro, dalla più recente, con data e meta (current_page, last_page, per_page, total). Valgono anche per le certificazioni fatte sul bundle: la risposta di .../seal contiene certification_id, che è l'id da usare qui.

Come esce il documento

Più allegati vengono uniti in un unico PDF, nell'ordine in cui li passi.
Ogni pagina riceve l'etichetta Certificazione N/AAAA in alto a sinistra, con sotto il testo dell'ente che certifica (per le associazioni firmatarie dell'accordo territoriale è la dicitura di sempre).
I sigilli vanno su tutte le pagine, in fondo, da sinistra a destra: due sigilli escono affiancati, non uno sopra l'altro.
Un sigillo da solo può andare a destra, se è il timbro di un'associazione inquilini: è così che due associazioni certificano lo stesso documento, una per volta, ognuna dal suo lato.
Lo stesso sigillo passato due volte viene applicato una volta sola.

Numerazione

Il numero di certificazione è progressivo per anno. La serie è quella dell'ente, se i sigilli usati appartengono a un ente certificatore; altrimenti è quella del capogruppo, o la tua se non ne hai uno. Ogni serie parte da 1.

Un bundle che ha già un numero se lo tiene: risigillare lo stesso bundle (per esempio dopo aver corretto un allegato) aggiorna il documento senza bruciare un numero nuovo e senza lasciare buchi nella serie. Senza bundle lo stesso vale per external_id: è quella la chiave che tiene insieme i tentativi.

Requisiti del PDF

Tutte le pagine devono essere in formato A4 verticale: i sigilli sono posizionati a misure fisse, su un formato diverso finirebbero fuori posto. I documenti in orizzontale o in A3 vengono rifiutati con 422 NOT_A4, indicando quale allegato è fuori formato e le dimensioni rilevate.

Errori

HTTP	`error`	Quando
`403`	`PARTNER_PRICING_REQUIRED`	Nessun listino `SEAL_PDF` configurato per il tuo account
`403`	`BUNDLE_NOT_OWNED`	Il bundle non è intestato al tuo utente
`403`	`CERTIFICATION_NOT_OWNED`	La certificazione che stai rileggendo non è tua
`409`	`CERTIFICATION_IN_PROGRESS`	Una certificazione con lo stesso `external_id` è in lavorazione
`403`	`SEAL_NOT_OWNED`	Uno dei sigilli non è tuo, né del tuo capogruppo, né del tuo ente
`400`	`AMOUNT_NOT_ENOUGH`	Saldo wallet insufficiente. La risposta include `missing_amount` e `checkout_link`
`422`	`NO_DOCUMENT`	Né `file` né `attachments`: non c'è niente da sigillare
`422`	`NOT_A4`	Un allegato non è in A4 verticale

Oltre a questi, la chiamata risponde 422 con message e errors (formato standard di validazione) quando l'input non è accettabile prima ancora di provarci:

attachments[].url dev'essere http o https verso un indirizzo pubblico: gli URL interni, privati o con altri schemi vengono rifiutati;
al massimo 10 sigilli e 20 allegati per chiamata;
external_id obbligatorio e non più lungo di 100 caratteri;
user_bundle_id, se lo passi, dev'essere un bundle esistente e non cancellato.

NOTE

L'addebito avviene solo a documento prodotto: se la sigillatura fallisce, la chiamata esce in errore e non ti viene scalato nulla.

Sigilli su PDF ​

Prerequisiti ​

I tuoi sigilli ​

Apporre i sigilli ​

Con un PDF caricato (due sigilli) ​

Con allegati già online (un sigillo) ​

Risposta — 201 Created ​

Certificare con o senza bundle ​

Risposta — 201 Created ​

external_id, cioè: non certificare due volte ​

Rileggere le certificazioni ​

Come esce il documento ​

Numerazione ​

Requisiti del PDF ​

Errori ​

Sigilli su PDF

Prerequisiti

I tuoi sigilli

Apporre i sigilli

Con un PDF caricato (due sigilli)

Con allegati già online (un sigillo)

Risposta — `201 Created`

Certificare con o senza bundle

Risposta — `201 Created`

`external_id`, cioè: non certificare due volte

Rileggere le certificazioni

Come esce il documento

Numerazione

Requisiti del PDF

Errori