API pública de Fix OS: guía para conectar tu taller

Qué puedes hacer

La API v1 deja que otro sistema tuyo lea los datos de tu taller: las órdenes de reparación, el inventario y los clientes. Es de sólo lectura: ninguna llave puede crear, cambiar ni borrar nada. Sirve para alimentar una contabilidad, un tablero en una hoja de cálculo, un ERP o un respaldo propio.

Cada llave pertenece a un solo taller y nunca ve los datos de otro, aunque se le pida. Lo que no se publica nunca: contraseñas y patrones de desbloqueo de los equipos, el enlace privado de seguimiento y los datos internos de tu cuenta.

1. Crea una llave

1. Entra a Fix OS con la cuenta del dueño del taller.
2. Ve a Configuración → Sistema y opciones avanzadas → API e integraciones.
3. Ponle un nombre que reconozcas («Mi contabilidad») y elige qué puede leer: órdenes, inventario o clientes.
4. Copia la llave en ese momento. Sólo se muestra una vez: guardamos una huella cifrada, no la llave.

La llave se ve así: fxk_1a2b3c4d_… (48 caracteres más). Guárdala como una contraseña, en una variable de entorno o en el gestor de secretos de tu sistema; nunca en una hoja compartida ni en el código de una página web. Si se filtra, revócala desde la misma pantalla: deja de funcionar al instante. Puedes tener hasta 5 llaves activas.

2. Tu primera llamada

Comprueba que la llave funciona pidiendo de quién es:

curl https://fixos.mx/api/v1/yo \
  -H "Authorization: Bearer $FIXOS_API_KEY" \
  -H "User-Agent: MiContabilidad/1.0"

Respuesta:

{
  "taller": { "id": "…", "nombre": "Mi Taller" },
  "alcances": ["ordenes:leer", "inventario:leer"],
  "cupo": { "limite": 120, "restante": 119 }
}

Te recomendamos mandar un User-Agent con el nombre de tu integración: si algo falla, así la reconocemos en los registros. Las herramientas de escaneo de vulnerabilidades están bloqueadas.

Rutas

Una fecha sola en hasta (2026-10-31) incluye ese día completo. Una ruta sin su permiso responde 403 sin consultar nada.

Paginación

Las listas devuelven { "datos": [ … ], "siguiente": "…" }, de lo más reciente a lo más viejo. Para la página siguiente, manda ese valor en cursor; cuando siguiente es null, ya no hay más. limite vale 50 por omisión y como máximo 100. Una orden nueva no hace que otra se repita ni se salte.

En JavaScript (Node 18 o superior), leer todo el inventario:

const base = 'https://fixos.mx/api/v1/inventario?limite=100';
const headers = {
  Authorization: `Bearer ${process.env.FIXOS_API_KEY}`,
  'User-Agent': 'MiERP/1.0',
};
let cursor = null;
const productos = [];
do {
  const url = cursor ? `${base}&cursor=${encodeURIComponent(cursor)}` : base;
  const r = await fetch(url, { headers });
  if (r.status === 429) {
    await new Promise((ok) => setTimeout(ok, Number(r.headers.get('Retry-After') || 60) * 1000));
    continue;
  }
  if (!r.ok) throw new Error((await r.json()).code);
  const pagina = await r.json();
  productos.push(...pagina.datos);
  cursor = pagina.siguiente;
} while (cursor);

En Python, las órdenes de octubre:

import os, requests

r = requests.get(
    "https://fixos.mx/api/v1/ordenes",
    params={"desde": "2026-10-01", "hasta": "2026-10-31", "limite": 100},
    headers={
        "Authorization": f"Bearer {os.environ['FIXOS_API_KEY']}",
        "User-Agent": "MiContabilidad/1.0",
    },
    timeout=30,
)
r.raise_for_status()
for orden in r.json()["datos"]:
    print(orden["folio"], orden["estado"], orden["total"])

Qué trae cada registro

• Orden: id, folio, estado, creadaEn, sucursalId, cliente (nombre y teléfono), equipo (tipo, marca, modelo), problema, total, anticipo, tecnico.
• Producto: id, nombre, sku, categoria, precio, costo, existencia, minimo, marca, modelo, codigoBarras, tipo, ubicacion, precioMayoreo, precioDistribuidor, fechas.
• Cliente: id, nombre, telefono, correo, direccion, totalOrdenes, fechas.

Los registros borrados no aparecen. El contrato completo está en openapi.json.

Límites

• 120 peticiones por minuto por llave. Cada respuesta trae RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos).
• 180 peticiones por minuto por IP en todo /api, sumando todas tus llaves, antes incluso de revisar la llave.
• Al pasarte recibes 429 con Retry-After: espera ese tiempo; reintentar antes no sirve.
• Hasta 5 llaves activas por taller y 10 llaves nuevas por hora.
• Las respuestas no se guardan en caché (Cache-Control: no-store).

Errores

Todos los errores llegan en application/problem+json con un code estable: programa contra el code, no contra el texto.

Seguridad

• Usa la llave sólo desde un servidor. En una página web cualquiera la vería.
• Dale a cada sistema su propia llave con lo mínimo que necesita: si una se filtra, revocas sólo ésa.
• La versión viaja en la cabecera API-Version: 1. Puedes fijarla en tu petición; una versión que no existe responde 400.
• ¿Encontraste un problema de seguridad? Escríbenos desde contacto.

Lo que todavía no hace

No crea órdenes, no mueve estados y no ajusta existencias, y no avisa por webhook cuando algo cambia: para mantener tu sistema al día, consulta periódicamente con desde. Si necesitas escritura, cuéntanos tu caso en contacto. Más recursos en desarrolladores y agentes y acceso y autenticación.