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

Todomator · todomator@1.7 todomatorapitokenticketsintegration

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). 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), 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

{
	"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.