# Créer des tickets depuis d’autres systèmes avec l’API de Todomator

> Authentifiez-vous avec le jeton de Todomator et créez un ticket en un appel JSON, depuis un script, un e-mail ou un formulaire web, avec dossiers, personnes, étiquettes, pièces jointes et un callback.

Framework: todomator
Product: Todomator (todomator@1.7)
Language: fr
Content-SHA256: 53163645c248d42404b4371bd659ee4bbc32f8a1cdb6fe6dc4380c9f585a62bb
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Todomator expose ses actions par un seul point d’accès API : `POST /api/` avec un corps JSON `{ "schema": "<name>", "data": { ... } }` (les routes API de Total.js ; voir la recette [routes API](/en/total5/api-routes/)). L’adresse `/api/` vient de la ligne `$api` du fichier `config`.

## S’authentifier avec le jeton

En plus de la session d’une personne connectée, l’API accepte un **jeton** : envoyez-le dans l’en-tête `x-token` ou dans le paramètre de requête `token`. S’il est égal au réglage `token` (voir [réglages](/en/todomator/settings-and-database/)), la requête s’exécute comme un utilisateur intégré appelé *Bot*, un administrateur avec la permission `bot` ; tout autre jeton est refusé. Utilisez un long jeton aléatoire, gardez-le sur votre serveur et envoyez-le uniquement en HTTPS.

## Créer un ticket

L’appel s’appelle `tickets_create`. Seul `name` est obligatoire ; le reste est facultatif :

| Champ | Remarques |
|---|---|
| `name` | le titre |
| `folder` ou `folderid` | le dossier, par **nom** (Todomator le cherche) ou par id ; le ticket prend l’indicateur facturable du dossier |
| `users` | les personnes à assigner, par **nom ou e-mail** ; une personne inconnue est une erreur (`User "..." not found`) |
| `watcherid` | les personnes qui le suivent, par **id** (contrairement à `users`, le schéma de cette version ne les accepte pas par nom) |
| `statusid` | `pending` (par défaut), `open`, `review`, `postponed`, `note` ou `closed` |
| `markdown`, `html` | le contenu |
| `tags`, `ispriority`, `isbillable`, `ispublic` | étiquettes et indicateurs |
| `date`, `deadline`, `worked` | le jour, une échéance et les minutes déjà travaillées |
| `attachments` | une liste de `{ name, data }` où `data` est le fichier en Base64 |
| `reference`, `source`, `attrs` | champs libres pour relier le ticket à votre système |
| `callback` | une adresse qui reçoit le 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 réponse est l’id du nouveau ticket. Les personnes assignées sont notifiées et les sessions ouvertes des personnes qui peuvent le voir sont rafraîchies.

## Le callback

Quand `callback` est défini, Todomator envoie un `POST` à cette adresse avec les données du ticket lorsque le ticket est créé, mis à jour ou cloné, et lorsqu’un commentaire est ajouté (à la création et à la mise à jour, il envoie aussi la liste des champs fournis, `keys`). Votre système peut l’utiliser pour refléter l’état d’un ticket.

## Autres appels

Le même point d’accès sert le reste des actions, avec les noms de `controllers/api.js` : `tickets` (liste), `tickets_detail/{id}`, `tickets_update/{id}`, `tickets_clone/{id}`, `tickets_remove/{id}`, `logwork_create`, `folders`, `tags` et d’autres. La documentation officielle de l’API se trouve sur [docs.totaljs.com/todomator](https://docs.totaljs.com/todomator/).