# Crear tickets desde otros sistemas con la API de Todomator

> Autentícate con el token de Todomator y crea un ticket con una llamada JSON, desde un script, un correo o un formulario web, con carpetas, personas, etiquetas, archivos adjuntos y un callback.

Framework: todomator
Product: Todomator (todomator@1.7)
Language: es
Content-SHA256: b554175fecf5ca6764c1be786505d29888e6d852194dffdbcab63728292c801a
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

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](/en/total5/api-routes/)). 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](/en/todomator/settings-and-database/)), 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 |

```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 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](https://docs.totaljs.com/todomator/).