API reference · v1

Wattson API

REST API per leggere gli invii contratto, scaricare i documenti protetti e aggiornare lo stato del contratto dal tuo gestionale esterno.

Base URLhttps://api.getwattson.it/v1AuthBearer API keyFormatoJSON

Gestisci API key

Autenticazione

Le API key si creano e revocano da Wattson App, in Admin → Impostazioni → API key aziendali. In v1 non esistono scope: ogni chiave valida può leggere e aggiornare tutti i contratti della propria azienda.

Passa la chiave in ogni richiesta con l'header Authorization: Bearer wattson_sk_..., oppure in alternativa con x-wattson-api-key.

cURL

curl 'https://api.getwattson.it/v1/contracts?contract_status=in_corso&limit=50' \
  -H 'Authorization: Bearer wattson_sk_...'

Modello dati

Lo stato di invio (status) e lo stato del contratto (contract_status) sono due campi distinti: il primo è tecnico, il secondo è operativo.

Campo	Valori	Uso
`status`	pending, sent, failed	Audit tecnico: dice se Wattson ha consegnato il webhook al gestionale.
`contract_status`	in_corso, accettato, rifiutato	Stato operativo mostrato in Wattson ad admin e agenti.
`external_contract_id`	stringa libera	ID del contratto nel gestionale esterno, utile per riconciliazione.
`contract_status_note`	testo	Nota leggibile dagli utenti Wattson, ad esempio motivo rifiuto.

Endpoint contratti

GET/contracts

Lista gli invii contratto della company associata alla API key.

limit: numero righe, default 50, massimo 100
offset: paginazione a offset
contract_status: in_corso, accettato, rifiutato
status: pending, sent, failed
external_contract_id: filtro esatto

GET/contracts/{id}

Restituisce un singolo invio con righe fornitura, snapshot contrattuali, documenti e stato.

PATCH/contracts/{id}/status

Aggiorna lo stato operativo del contratto. Se non passi una fornitura specifica, aggiorna tutto l'invio.

status / contract_status: obbligatorio
note / contract_status_note: nota visibile in Wattson
external_contract_id: ID gestionale
payload / external_contract_payload: JSON tecnico del gestionale
submission_supply_id, supply_opportunity_id, supply_id: aggiornamento di una sola fornitura
sync_deal_status: false per non sincronizzare opportunità CRM

cURL · aggiorna stato

curl -X PATCH 'https://api.getwattson.it/v1/contracts/00000000-0000-0000-0000-000000000000/status' \
  -H 'Authorization: Bearer wattson_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "accettato",
    "external_contract_id": "CRM-12345",
    "note": "Accettato dal gestionale",
    "payload": {
      "provider_status": "accepted",
      "signed_at": "2026-05-19T10:30:00Z"
    }
  }'

cURL · singola fornitura

curl -X PATCH 'https://api.getwattson.it/v1/contracts/00000000-0000-0000-0000-000000000000/status' \
  -H 'Authorization: Bearer wattson_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "rifiutato",
    "supply_opportunity_id": "11111111-1111-1111-1111-111111111111",
    "note": "Cliente non interessato alla fornitura gas"
  }'

JSON · risposta

{
  "contract": {
    "id": "00000000-0000-0000-0000-000000000000",
    "status": "sent",
    "contract_status": "accettato",
    "contract_status_updated_at": "2026-05-19T10:30:00.000Z",
    "external_contract_id": "CRM-12345",
    "contract_submission_supplies": [
      {
        "id": "22222222-2222-2222-2222-222222222222",
        "service_type": "luce",
        "contract_status": "accettato",
        "documents_snapshot": {
          "identity_front": {
            "url": "https://.../contract-document?document_id=..."
          }
        }
      }
    ]
  }
}

Documenti

Gli URL documento presenti nel webhook o in documents_snapshot puntano al download protetto. Usa sempre la stessa API key nel bearer token: non esistono signed URL pubblici.

cURL

curl 'https://tprnhlgqbrxkvycpmzlj.supabase.co/functions/v1/contract-document?document_id=...' \
  -H 'Authorization: Bearer wattson_sk_...'

Errori

L'API usa i codici di stato HTTP standard. Gli errori restituiscono un corpo JSON con il campo error.

`400`	Payload, status o ID non valido.
`401`	API key mancante o non valida.
`404`	Contratto o documento non trovato nel tenant.
`405`	Metodo non supportato dall'endpoint.
`410`	Documento non più disponibile perché eliminato.
`500`	Errore interno o verifica API key non riuscita.