Crear tickets desde otros sistemas con la API de Todomator

Todomator · todomator@1.7 todomatorapitokenticketsintegration

Todomator expone sus acciones mediante un único endpoint de API: POST /api/ con un cuerpo JSON { "schema": "<name>", "data": { ... } } (las rutas API de Total.js; consulta la receta rutas API). La dirección /api/ sale de la línea $api del archivo config.

Autenticar con el token

Además de la sesión de una persona con sesión iniciada, la API acepta un token: envíalo en la cabecera x-token o en el parámetro de consulta token. Si es igual al ajuste token (consulta los ajustes), la petición se ejecuta como un usuario integrado llamado Bot, un administrador con el permiso bot; cualquier otro token se rechaza. Usa un token largo y aleatorio, guárdalo en tu servidor y envíalo solo por HTTPS.

Crear un ticket

La llamada se llama tickets_create. Solo name es obligatorio; el resto es opcional:

Campo	Notas
`name`	el título
`folder` o `folderid`	la carpeta, por nombre (Todomator la busca) o por id; el ticket toma la bandera de facturable de la carpeta
`users`	las personas a asignar, por nombre o correo; una persona desconocida es un error (`User "..." not found`)
`watcherid`	las personas que lo siguen, por id (a diferencia de `users`, el esquema de esta versión no las admite por nombre)
`statusid`	`pending` (por defecto), `open`, `review`, `postponed`, `note` o `closed`
`markdown`, `html`	el contenido
`tags`, `ispriority`, `isbillable`, `ispublic`	etiquetas y banderas
`date`, `deadline`, `worked`	el día, una fecha límite y los minutos ya trabajados
`attachments`	una lista de `{ name, data }` donde `data` es el archivo en Base64
`reference`, `source`, `attrs`	campos libres para vincular el ticket con tu sistema
`callback`	una dirección que recibe el 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"
	}
}

La respuesta es el id del ticket nuevo. Se notifica a las personas asignadas y se actualizan las sesiones abiertas de las personas que pueden verlo.

El callback

Cuando callback está definido, Todomator envía un POST a esa dirección con los datos del ticket cuando el ticket se crea, se actualiza o se clona, y cuando se añade un comentario (al crear y actualizar envía además la lista de los campos que se dieron, keys). Tu sistema puede usarlo para reflejar el estado de un ticket.

Otras llamadas

El mismo endpoint sirve el resto de las acciones, con los nombres de controllers/api.js: tickets (lista), tickets_detail/{id}, tickets_update/{id}, tickets_clone/{id}, tickets_remove/{id}, logwork_create, folders, tags y más. La documentación oficial de la API está en docs.totaljs.com/todomator.