# Creare ticket da altri sistemi con l’API di Todomator

> Autenticati con il token di Todomator e crea un ticket con una chiamata JSON, da uno script, un’e-mail o un modulo web, con cartelle, persone, tag, allegati e un callback.

Framework: todomator
Product: Todomator (todomator@1.7)
Language: it
Content-SHA256: 14c05b0c2155e46eebf70d0374b25a87e20f0a64bce692df91163727c7eeefa1
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Todomator espone le sue azioni tramite un solo endpoint API: `POST /api/` con un corpo JSON `{ "schema": "<name>", "data": { ... } }` (le rotte API di Total.js; vedi la ricetta [rotte API](/en/total5/api-routes/)). L’indirizzo `/api/` deriva dalla riga `$api` del file `config`.

## Autenticarsi con il token

Oltre alla sessione di una persona con accesso, l’API accetta un **token**: invialo nell’intestazione `x-token` o nel parametro di query `token`. Se è uguale all’impostazione `token` (vedi [impostazioni](/en/todomator/settings-and-database/)), la richiesta viene eseguita come un utente integrato chiamato *Bot*, un amministratore con il permesso `bot`; qualsiasi altro token viene rifiutato. Usa un token lungo e casuale, tienilo sul tuo server e invialo solo via HTTPS.

## Creare un ticket

La chiamata si chiama `tickets_create`. Solo `name` è obbligatorio; il resto è facoltativo:

| Campo | Note |
|---|---|
| `name` | il titolo |
| `folder` o `folderid` | la cartella, per **nome** (Todomator la cerca) o per id; il ticket prende il flag di fatturabilità della cartella |
| `users` | le persone da assegnare, per **nome o e-mail**; una persona sconosciuta è un errore (`User "..." not found`) |
| `watcherid` | le persone che lo seguono, per **id** (a differenza di `users`, lo schema di questa versione non le accetta per nome) |
| `statusid` | `pending` (predefinito), `open`, `review`, `postponed`, `note` o `closed` |
| `markdown`, `html` | il contenuto |
| `tags`, `ispriority`, `isbillable`, `ispublic` | tag e flag |
| `date`, `deadline`, `worked` | il giorno, una scadenza e i minuti già lavorati |
| `attachments` | un elenco di `{ name, data }` dove `data` è il file in Base64 |
| `reference`, `source`, `attrs` | campi liberi per collegare il ticket al tuo sistema |
| `callback` | un indirizzo che riceve il ticket |

```json
{
	"schema": "tickets_create",
	"data": {
		"name": "The invoice page fails with a 500",
		"folder": "Customer support",
		"users": ["jane@example.com"],
		"markdown": "Reported by the contact form.\n\nSteps: open the invoice and click *Print*.",
		"tags": ["bug"],
		"source": "website",
		"reference": "form-2041"
	}
}
```

La risposta è l’id del nuovo ticket. Le persone assegnate vengono notificate e le sessioni aperte delle persone che possono vederlo vengono aggiornate.

## Il callback

Quando `callback` è impostato, Todomator invia un `POST` a quell’indirizzo con i dati del ticket quando il ticket viene creato, aggiornato o clonato, e quando viene aggiunto un commento (alla creazione e all’aggiornamento invia anche l’elenco dei campi forniti, `keys`). Il tuo sistema può usarlo per rispecchiare lo stato di un ticket.

## Altre chiamate

Lo stesso endpoint serve le altre azioni, con i nomi di `controllers/api.js`: `tickets` (elenco), `tickets_detail/{id}`, `tickets_update/{id}`, `tickets_clone/{id}`, `tickets_remove/{id}`, `logwork_create`, `folders`, `tags` e altro. La documentazione ufficiale dell’API è su [docs.totaljs.com/todomator](https://docs.totaljs.com/todomator/).