# Criar tickets a partir de outros sistemas com a API do Todomator

> Autentique-se com o token do Todomator e crie um ticket com uma chamada JSON, a partir de um script, de um e-mail ou de um formulário web, com pastas, pessoas, etiquetas, anexos e um callback.

Framework: todomator
Product: Todomator (todomator@1.7)
Language: pt
Content-SHA256: 71089741a625d8363a46ed821b0fb1304dab0714e9a0570c1af923cc78998beb
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

O Todomator expõe as suas ações através de um único endpoint de API: `POST /api/` com um corpo JSON `{ "schema": "<name>", "data": { ... } }` (as rotas API do Total.js; veja a receita [rotas API](/en/total5/api-routes/)). O endereço `/api/` vem da linha `$api` do ficheiro `config`.

## Autenticar com o token

Além da sessão de uma pessoa com sessão iniciada, a API aceita um **token**: envie-o no cabeçalho `x-token` ou no parâmetro de consulta `token`. Se for igual à definição `token` (veja [definições](/en/todomator/settings-and-database/)), o pedido corre como um utilizador integrado chamado *Bot*, um administrador com a permissão `bot`; qualquer outro token é recusado. Use um token longo e aleatório, guarde-o no seu servidor e envie-o apenas por HTTPS.

## Criar um ticket

A chamada chama-se `tickets_create`. Só `name` é obrigatório; o resto é opcional:

| Campo | Notas |
|---|---|
| `name` | o título |
| `folder` ou `folderid` | a pasta, por **nome** (o Todomator procura-a) ou por id; o ticket toma o indicador de faturável da pasta |
| `users` | as pessoas a atribuir, por **nome ou e-mail**; uma pessoa desconhecida é um erro (`User "..." not found`) |
| `watcherid` | as pessoas que o seguem, por **id** (ao contrário de `users`, o esquema desta versão não as aceita por nome) |
| `statusid` | `pending` (predefinição), `open`, `review`, `postponed`, `note` ou `closed` |
| `markdown`, `html` | o conteúdo |
| `tags`, `ispriority`, `isbillable`, `ispublic` | etiquetas e indicadores |
| `date`, `deadline`, `worked` | o dia, um prazo e os minutos já trabalhados |
| `attachments` | uma lista de `{ name, data }` onde `data` é o ficheiro em Base64 |
| `reference`, `source`, `attrs` | campos livres para ligar o ticket ao seu sistema |
| `callback` | um endereço que recebe o 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"
	}
}
```

A resposta é o id do novo ticket. As pessoas atribuídas são notificadas e as sessões abertas das pessoas que o podem ver são atualizadas.

## O callback

Quando `callback` está definido, o Todomator envia um `POST` para esse endereço com os dados do ticket quando o ticket é criado, atualizado ou clonado, e quando se acrescenta um comentário (ao criar e atualizar envia também a lista dos campos fornecidos, `keys`). O seu sistema pode usá-lo para refletir o estado de um ticket.

## Outras chamadas

O mesmo endpoint serve as restantes ações, com os nomes de `controllers/api.js`: `tickets` (lista), `tickets_detail/{id}`, `tickets_update/{id}`, `tickets_clone/{id}`, `tickets_remove/{id}`, `logwork_create`, `folders`, `tags` e mais. A documentação oficial da API está em [docs.totaljs.com/todomator](https://docs.totaljs.com/todomator/).