API pública v1

A API REST pública é destinada a integrações servidor a servidor com, por exemplo, softwares de CRM ou faturamento.

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 Administração → Chaves de API. Dê um nome reconhecível à chave e escolha os escopos:

• read: marca uma chave destinada à leitura;
• write: criar ou alterar recursos graváveis e usar endpoints de planejamento.
• plan: solicitar uma proposta de planejamento.

Para uma integração normal de leitura/escrita, selecione ambos os escopos. Atenção: o backend v1 atual verifica write explicitamente para POST/PATCH, mas permite GET para qualquer chave válida e ativa; portanto, read é atualmente uma indicação administrativa e ainda não um bloqueio técnico separado. A chave bruta começa com msk_, é exibida 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

Use um destes cabeçalhos:

Authorization: Bearer msk_...

X-API-Key: msk_...

Todos os resultados são filtrados no servidor para a organização da chave. Um id de outro tenant retorna o mesmo 404 que um id desconhecido.

Recursos e métodos

Não existe endpoint DELETE na v1.

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, pesquisa parcial sem diferenciar maiúsculas de minúsculas em texto literal. Um sinal de porcentagem procura um sinal de porcentagem. Os clientes correspondem por nome, e-mail ou número do cliente; os materiais por SKU ou nome.

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

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

Clientes

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

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

POST /addresses cria um endereço para um cliente e exige client_id. O cliente deve 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 de serviço, id do cliente, título, descrição, prioridade, status, duração prevista, id do técnico principal, número de técnicos exigidos, planejamento, id do endereço de serviço, id do tipo de tarefa, habilidades exigidas e timestamps. Notas internas e de técnico não são expostas.

POST /jobs exige 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á ausente, unplanned é usado. Quando job_number está ausente, 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 chaves estrangeiras de cliente, endereço de serviço e tipo de tarefa devem pertencer ao mesmo tenant.

POST /jobs/:id/assign planeja 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 planejada; não exclui a ordem de serviço.

Proposta de planejamento

POST /plan retorna uma proposta de planejamento e não altera nada: não cria nem move nenhuma ordem de serviço. Ele exige o escopo separado plan e é limitado a 3 chamadas por organização a cada 10 minutos; as chamadas seguintes retornam um erro 429 claro. Não usa a IA do Manisma nem consome as ações de IA incluídas no seu plano Manisma, porque o assistente que faz a chamada fornece o raciocínio.

Outros recursos

• assets: dispositivos instalados em um cliente; permitem gravação com POST e PATCH.

• task_types: permitem gravação com POST e PATCH.

• materials: permitem gravação com POST e PATCH; o preço de compra e o estoque permitem leitura e gravação.

• asset_models: somente leitura.

• technicians: nome, e-mail, telefone, status ativo e habilidades. Horários de trabalho, endereços e id de usuário não são públicos.

Erros e limites

A API é limitada a 600 requisições por minuto por IP de origem. Implemente retries com backoff exponencial para 429, 502 e erros temporários de rede. Não repita erros de validação sem corrigir a requisição.