Visión general de la API

FreeMaint tiene una sola superficie de API para integraciones entre sistemas: GraphQL, en /api/v1/graphql. Las rutas REST que ves en el navegador son la API de la propia aplicación y se autentican con una sesión de usuario — una clave de API no llega a ellas. Planifica tu integración sobre GraphQL.

API REST

Las rutas REST bajo /api/v1/{resource} son las que llaman las aplicaciones web y móvil de FreeMaint, autenticadas con una sesión de usuario (JWT). Una clave de API (fmk_...) NO las autentica — solo se acepta en /api/v1/graphql y en el endpoint de ingesta de energía. Si estás construyendo una integración, lee la sección de GraphQL más abajo; las rutas REST se documentan aquí porque las verás en la pestaña de red de tu navegador, no porque una clave pueda llamarlas.

Ejemplo (sesión de usuario, NO una clave de API — una clave fmk_ no autentica esta ruta): curl -H 'Authorization: Bearer <session-token>' 'https://freemaint.com/api/v1/work-orders?status=OPEN&assigneeId=42&page=1&pageSize=20'

API GraphQL

El endpoint GraphQL es POST /api/v1/graphql. Cubre un subconjunto deliberado del producto — órdenes de trabajo, activos, paradas de máquina, repuestos y sus movimientos de inventario, contadores, órdenes de compra, ubicaciones, proveedores, clientes y planos — no la aplicación entera. Use GraphQL cuando de otro modo tendría que llamar a varios endpoints para componer una sola pantalla: por ejemplo, una tarjeta que muestra una orden de trabajo con el detalle de su activo, los repuestos consumidos y el coste total de mano de obra. La guía de integración con ERP enumera lo que el esquema no alcanza.

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

Autenticación

Ambas API aceptan un token JWT en la cabecera Authorization, emitido por POST /api/v1/auth/login y válido 2 horas (se renueva con el token de actualización). Para integraciones servidor a servidor use en su lugar una clave de API: un administrador la crea en Configuración de la empresa > API (/company-settings/api), y una persona cuyo rol lo permite crea las suyas en Perfil > Seguridad > Claves de API (/profile/api-keys); envíe Authorization: Bearer fmk_... . Una clave actúa como su propietario: tiene sus permisos y solo ve lo que él ve. IMPORTANTE: una clave de API autentica el endpoint GraphQL (POST /api/v1/graphql), el endpoint de ingesta de energía y /public-api/{whoami,ping} — NO autentica las rutas REST de recursos, que requieren un JWT de usuario.

Disponibilidad por plan

Límites de peticiones

La cuota es un contador DIARIO por empresa, compartido entre GraphQL y el endpoint de ingesta de energía, y se reinicia a las 00:00 UTC. Business permite 5.000 llamadas al día; Enterprise, 100.000. Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. No hay ventana por minuto ni cabecera Retry-After. En las superficies REST el rechazo es un HTTP 403; en GraphQL el estado HTTP sigue siendo 200 — GraphQL siempre responde 200 — y el rechazo está en errors[0].extensions.code = FORBIDDEN. No compruebes el estado HTTP 403 en GraphQL: lee el array errors.

Formato de los errores

Cada error lleva un estado HTTP, un código legible por máquina y un mensaje legible por personas. Los 4xx son errores del cliente (validación, permisos, no encontrado); los 5xx son errores del servidor y conviene reintentarlos con espera exponencial. En GraphQL el código está en extensions.code, y los valores que puede filtrar son: BAD_REQUEST, UNAUTHENTICATED, FORBIDDEN, NOT_FOUND, CONFLICT, BAD_USER_INPUT y TOO_MANY_REQUESTS. Cuando falla la validación, el mensaje nombra exactamente los campos incorrectos —por ejemplo «quantity must be a number conforming to the specified constraints»—, así que nunca tendrá que adivinar cuál envió mal su sistema. Una búsqueda que sencillamente no coincide con nada no es un error: part(barcode:) devuelve null.

SDK y herramientas oficiales

Hoy no existe un SDK cliente oficial. El endpoint GraphQL tiene la introspección activada, así que cualquier cliente GraphQL (Apollo, graphql-codegen, Insomnia, Postman) puede descubrir el esquema apuntando a POST /api/v1/graphql con su clave API. Por ahora no publicamos un documento OpenAPI estático ni un archivo SDL en una URL fija.

Las claves de API no están disponibles en Core ni en Starter.