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 você vê no navegador são a API do próprio aplicativo, autenticada por sessão de usuário — uma chave de API não as alcança. Planeje a integração sobre GraphQL.

API REST

As rotas REST em /api/v1/{resource} são as que os aplicativos web e mobile do FreeMaint chamam, autenticadas por sessão de usuário (JWT). Uma chave de API (fmk_...) NÃO as autentica — ela é aceita apenas em /api/v1/graphql e no endpoint de ingestão de energia. Para uma integração, leia a seção GraphQL abaixo.

Exemplo (sessão de usuário, 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. Ele cobre um subconjunto deliberado do produto — ordens de serviço, ativos, paradas de máquina, peças e suas movimentações de estoque, medidores, pedidos de compra, locais, fornecedores, clientes e plantas — não o aplicativo inteiro. Use GraphQL quando você precisaria chamar vários endpoints para montar uma única tela: por exemplo, um card que mostra uma ordem de serviço com o detalhe do ativo, as peças consumidas e o custo total de mão de obra. O guia de integração com ERP lista o que o schema não alcança.

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

Autenticação

As duas APIs 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 uma chave de API: um administrador a cria em Configurações da empresa > API (/company-settings/api), e uma pessoa cuja função permite cria as próprias em Perfil > Segurança > Chaves API (/profile/api-keys); envie Authorization: Bearer fmk_... . Uma chave age 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} — ela NÃO autentica as rotas REST de recursos, que exigem um JWT de usuário.

Disponibilidade por plano

Limites de requisição

A cota é um contador DIÁRIO por empresa, compartilhado 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 status HTTP continua 200 — o GraphQL sempre responde 200 — e a recusa está em errors[0].extensions.code = FORBIDDEN. Não teste o status HTTP 403 no GraphQL: leia o array errors.

Formato de erro

Cada erro traz um status 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 fica em extensions.code e os valores que você 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 aponta exatamente os campos com problema — por exemplo "quantity must be a number conforming to the specified constraints" — então você nunca precisa adivinhar qual deles o seu sistema enviou errado. Uma busca que simplesmente não encontra nada não é um erro: part(barcode:) retorna null.

SDKs oficiais e ferramentas

Hoje não existe um SDK cliente oficial. O endpoint GraphQL está com introspecção ativada, então qualquer cliente GraphQL (Apollo, graphql-codegen, Insomnia, Postman) consegue descobrir o schema apontando para POST /api/v1/graphql com a sua chave de API. No momento não publicamos um documento OpenAPI estático nem um arquivo SDL em uma URL fixa.

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