API pública v1

A API REST pública destina-se a integrações server-to-server com, por exemplo, software de CRM ou faturação.

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

Não utilize diretamente a API do Directus e nunca coloque uma chave de API em JavaScript de frontend.

Criar uma chave de API

Abra como Admin Gestão → Chaves de API. Dê à chave um nome reconhecível e escolha os scopes:

• read: marca uma chave destinada a leitura;
• write: criar ou alterar recursos com escrita e utilizar endpoints de planeamento.
• plan: pedir uma proposta de planeamento.

Selecione ambos os scopes para uma integração normal de leitura/escrita. Atenção: o backend v1 atual verifica write explicitamente para POST/PATCH, mas permite GET para qualquer chave válida e ativa; read é, por isso, neste momento, uma indicação administrativa e ainda não um bloqueio técnico separado. A chave em bruto começa com msk_, é mostrada uma única vez e não pode ser recuperada. Em caso de perda, crie uma nova chave e desative ou remova a antiga.

Autenticação

Utilize um destes cabeçalhos:

Authorization: Bearer msk_...

X-API-Key: msk_...

Todos os resultados são limitados, no servidor, à organização da chave. Um id de outro tenant devolve o mesmo 404 que um id desconhecido.

Recursos e métodos

Na v1 não existe endpoint DELETE.

Listas e paginação

GET /clients?limit=50&page=1

• limit: 1 a 100, padrão 50;
• page: começa em 1.
• search: para as listas de clientes e materiais, procura parcial sem distinguir maiúsculas de minúsculas de texto literal. Um sinal de percentagem procura um sinal de percentagem. Os clientes correspondem por nome, e-mail ou número de cliente; os materiais por SKU ou nome.

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

Uma resposta de detalhe ou de escrita utiliza { "data": { ... } }.

Clientes

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

POST /clients requer name. Os campos de escrita permitidos são name, customer_number, client_type, email, phone, vat_number e status. Em PATCH, são todos opcionais, mas tem de existir pelo menos um campo válido. Campos desconhecidos e um tenant_id fornecido são ignorados.

POST /addresses cria uma morada para um cliente e requer client_id. O cliente tem de pertencer ao mesmo 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"}'

Ordens de serviço

Os campos de leitura incluem id, tenant, número da ordem, id do cliente, título, descrição, prioridade, estado, duração prevista, id do técnico principal, número de técnicos exigidos, planeamento, id da morada de serviço, id do tipo de tarefa, competências exigidas e timestamps. As notas internas e as notas do técnico não são expostas.

POST /jobs requer title. Campos permitidos:

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.

Quando status está em falta, é utilizado unplanned. Quando job_number está em falta, o Manisma gera um número com o prefixo do tenant definido. Em PATCH, job_number, status e assigned_technician_id não podem ser alterados.

As foreign keys para cliente, morada de serviço e tipo de tarefa têm de pertencer ao mesmo tenant.

POST /jobs/:id/assign planeia uma ordem de serviço com technician_id, scheduled_start e scheduled_end. POST /jobs/:id/unassign remove a atribuição e devolve a ordem à fila não planeada; não elimina a ordem de serviço.

Proposta de planeamento

POST /plan devolve uma proposta de planeamento e não altera nada: não cria nem desloca nenhuma ordem de serviço. Requer o scope separado plan e está limitado a 3 chamadas por organização a cada 10 minutos; as chamadas seguintes devolvem um erro 429 claro. Não utiliza a IA do Manisma nem consome as ações de IA incluídas no seu plano Manisma, porque o seu assistente que faz a chamada fornece o raciocínio.

Outros recursos

• assets: dispositivos instalados num cliente; permitem escrita com POST e PATCH.

• task_types: permitem escrita com POST e PATCH.

• materials: permitem escrita com POST e PATCH; o preço de compra e o stock permitem leitura e escrita.

• asset_models: só de leitura.

• technicians: nome, e-mail, telefone, estado ativo e competências. Horários de trabalho, moradas e id de utilizador não são públicos.

Erros e limites

A API está limitada a 600 pedidos por minuto por IP de origem. Construa retries com backoff exponencial para 429, 502 e erros de rede temporários. Não repita erros de validação sem corrigir o pedido.