Visão geral da API

O FreeMaint expõe uma única superfície de API para integrações entre sistemas: GraphQL, em /api/v1/graphql. As rotas REST que vê no navegador são a API da própria aplicação, autenticada por sessão de utilizador — uma chave de API não lhes chega. Planeie a integração sobre GraphQL.

API REST

As rotas REST em /api/v1/{resource} são as que as aplicações web e móvel do FreeMaint chamam, autenticadas por sessão de utilizador (JWT). Uma chave de API (fmk_...) NÃO as autentica — é aceite apenas em /api/v1/graphql e no endpoint de ingestão de energia. Para uma integração, leia a secção GraphQL abaixo.

Exemplo (sessão de utilizador, NÃO uma chave de API — uma chave fmk_ não autentica esta rota): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

O endpoint GraphQL é POST /api/v1/graphql. Cobre um subconjunto deliberado do produto — ordens de trabalho, ativos, paragens de máquina, peças e os seus movimentos de stock, contadores, encomendas de compra, localizações, fornecedores, clientes e plantas — e não a aplicação inteira. Use GraphQL quando de outro modo teria de chamar vários endpoints para compor um só ecrã: por exemplo, um cartão que mostra uma ordem de trabalho com o detalhe do seu ativo, as peças consumidas e o custo total de mão de obra. O guia de integração com ERP enumera o que o esquema não alcança.

Consulta de exemplo: query { workOrders(status: "OPEN", limit: 10) { id reference title status priority assetId dueDate } }

Autenticação

Ambas as API aceitam um token JWT no cabeçalho Authorization, emitido por POST /api/v1/auth/login e válido por 2 horas (renova-se com o token de atualização). Para integrações servidor a servidor use antes uma chave de API: um administrador cria-a em Definições da Empresa > API (/company-settings/api), e uma pessoa cuja função o permita cria as suas em Perfil > Segurança > Chaves API (/profile/api-keys); envie Authorization: Bearer fmk_... . Uma chave atua como o seu proprietário: tem as permissões dele e só vê o que ele vê. IMPORTANTE: uma chave de API autentica o endpoint GraphQL (POST /api/v1/graphql), o endpoint de ingestão de energia e /public-api/{whoami,ping} — NÃO autentica as rotas REST de recursos, que exigem um JWT de utilizador.

Disponibilidade por nível

Limites de pedidos

A quota é um contador DIÁRIO por empresa, partilhado entre o GraphQL e o endpoint de ingestão de energia, e reinicia às 00:00 UTC. O Business permite 5.000 chamadas por dia; o Enterprise, 100.000. Cada resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Não há janela por minuto nem cabeçalho Retry-After. Nas superfícies REST a recusa é um HTTP 403; no GraphQL o estado HTTP mantém-se 200 — o GraphQL responde sempre 200 — e a recusa está em errors[0].extensions.code = FORBIDDEN. Não teste o estado HTTP 403 no GraphQL: leia o array errors.

Formato de erro

Cada erro traz um estado HTTP, um código legível por máquina e uma mensagem legível por pessoas. Os 4xx são erros do cliente (validação, permissões, não encontrado); os 5xx são erros do servidor e devem ser repetidos com espera exponencial. No GraphQL o código está em extensions.code e os valores que pode filtrar são: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT e TOO_MANY_REQUESTS. Quando a validação falha, a mensagem indica exatamente os campos em falta — por exemplo «quantity must be a number conforming to the specified constraints» — pelo que nunca terá de adivinhar qual deles o seu sistema enviou mal. Uma procura que simplesmente não corresponde a nada não é um erro: part(barcode:) devolve null.

SDK e ferramentas oficiais

Não existe hoje um SDK cliente oficial. O endpoint GraphQL tem introspeção ativada, pelo que qualquer cliente GraphQL (Apollo, graphql-codegen, Insomnia, Postman) pode descobrir o esquema apontando para POST /api/v1/graphql com a sua chave de API. De momento não publicamos um documento OpenAPI estático nem um ficheiro SDL num URL fixo.

As chaves de API não estão disponíveis no Core nem no Starter.