API pública v1

La API REST pública está pensada para integraciones servidor a servidor con, por ejemplo, software de CRM o facturación.

URL base: https://auto.manisma.com/api/v1

No utilices directamente la API de Directus y no coloques una Clave API en JavaScript de frontend.

Crear una Clave API

Abre como Admin Administración → Claves API. Asigna a la clave un nombre reconocible y elige scopes:

• read: marca una clave pensada para lectura;
• write: crear o modificar recursos de escritura y usar endpoints de planificación.
• plan: solicitar una propuesta de planificación.

Selecciona ambos scopes para una conexión normal de lectura/escritura. Ten en cuenta: el backend v1 actual comprueba write explícitamente para POST/PATCH, pero permite GET a cualquier clave válida y activa; read es por ahora una marca administrativa y aún no un bloqueo técnico independiente. La clave en bruto empieza por msk_, se muestra una sola vez y no se puede recuperar. Si la pierdes, crea una nueva y desactiva o elimina la antigua.

Autenticación

Utiliza uno de estos headers:

Authorization: Bearer msk_...

X-API-Key: msk_...

Todos los resultados se limitan en el servidor a la organización de la clave. Un id de otro tenant devuelve el mismo 404 que un id desconocido.

Recursos y métodos

En v1 no hay endpoint DELETE.

Listas y paginación

GET /clients?limit=50&page=1

• limit: de 1 a 100, por defecto 50;
• page: empieza en 1.
• search: para las listas de clientes y materiales, búsqueda parcial sin distinguir mayúsculas y minúsculas de texto literal. Un signo de porcentaje busca un signo de porcentaje. Los clientes coinciden por nombre, correo electrónico o número de cliente; los materiales por SKU o nombre.

{
  "data": [],
  "meta": { "total": 0, "page": 1, "limit": 50 }
}

Una respuesta de detalle o de escritura utiliza { "data": { ... } }.

Clientes

Campos de lectura: id, tenant_id, customer_number, name, client_type, email, phone, vat_number, status, created_at, updated_at.

POST /clients requiere name. Los campos de escritura admitidos son name, customer_number, client_type, email, phone, vat_number y status. En PATCH todos son opcionales, pero debe haber al menos un campo válido. Los campos desconocidos y un tenant_id enviado se ignoran.

POST /addresses crea una dirección para un cliente y requiere client_id. El cliente debe pertenecer al mismo tenant.

curl -X POST 'https://auto.manisma.com/api/v1/clients' \
  -H 'Authorization: Bearer msk_...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Bakkerij Peeters","client_type":"b2b","email":"info@example.com"}'

Órdenes de trabajo

Los campos de lectura incluyen id, tenant, número de orden, id de cliente, título, descripción, prioridad, estado, duración prevista, id del técnico principal, número de técnicos requeridos, planificación, id de dirección de servicio, id de tipo de tarea, habilidades requeridas y marcas de tiempo. Las notas internas y las notas del técnico no se exponen.

POST /jobs requiere title. Campos admitidos:

job_number, client_id, title, description, priority, status, estimated_duration_minutes, required_technicians, scheduled_date, scheduled_start, scheduled_end, service_address_id, task_type_id, required_skills.

Cuando falta status, se utiliza unplanned. Cuando falta job_number, Manisma genera un número con el prefijo del tenant configurado. En PATCH no se pueden modificar job_number, status ni assigned_technician_id.

Las claves foráneas de cliente, dirección de servicio y tipo de tarea deben pertenecer al mismo tenant.

POST /jobs/:id/assign planifica una orden de trabajo con technician_id, scheduled_start y scheduled_end. POST /jobs/:id/unassign elimina su asignación y la devuelve a la cola sin planificar; no elimina la orden de trabajo.

Propuesta de planificación

POST /plan devuelve una propuesta de planificación y no cambia nada: no crea ni mueve ninguna orden de trabajo. Requiere el scope independiente plan y está limitado a 3 llamadas por organización cada 10 minutos; las llamadas posteriores devuelven un error 429 claro. No utiliza la IA de Manisma ni consume las acciones de IA incluidas en tu plan de Manisma, porque tu asistente que llama aporta el razonamiento.

Otros recursos

• assets: dispositivos instalados en un cliente; admiten escritura con POST y PATCH.

• task_types: admiten escritura con POST y PATCH.

• materials: admiten escritura con POST y PATCH; el precio de compra y el stock se pueden leer y escribir.

• asset_models: solo lectura.

• technicians: nombre, correo electrónico, teléfono, estado activo y habilidades. Los horarios, direcciones e id de usuario no son públicos.

Errores y límites

La API está limitada a 600 solicitudes por minuto por IP de origen. Implementa reintentos con backoff exponencial para 429, 502 y errores de red temporales. No reintentes errores de validación sin corregir la solicitud.