Referencia de la API

Referencia completa de la API pública de FabHub. El portal de marca es canónico; también puedes cargar el contrato legible por máquina en cualquier visor de OpenAPI (Swagger Editor, Redoc, Postman o tu IDE).

• OpenAPI JSON - OpenAPI YAML

URL base

https://api.fabhub.app/v1

Convenciones

• Autentícate con X-API-Key (o Authorization: Bearer). Consulta Autenticación.
• Los cuerpos de petición son JSON con claves camelCase; los filtros de listado son parámetros de consulta snake_case.
• Los endpoints de listado se paginan por página y devuelven un objeto pagination; consulta Paginación.
• Los endpoints de escritura requieren una cabecera Idempotency-Key; consulta Idempotencia.
• Los errores usan un sobre estable con un code legible por máquina; consulta Errores.

Todos los endpoints

Esta tabla se genera a partir del contrato OpenAPI y siempre lista todas las operaciones públicas y su scope requerido. Las secciones siguientes son ejemplos prácticos para los recursos más comunes; el contrato OpenAPI es la fuente exhaustiva para los esquemas de petición y respuesta.

Servicio

GET /v1

Devuelve las capacidades (método, ruta, scope) que la credencial que llama puede usar. No requiere scope.

GET /v1/auth/context

Devuelve el tenant, plan, scopes, nivel de límite de tasa y caducidad de la credencial que llama. No requiere scope. Consulta el ejemplo en Quickstart.

Items

GET /v1/items

Scope: items:read. Lista los items (productos, materiales, combos).

curl "https://api.fabhub.app/v1/items?page=1&page_size=2&search=widget" \
  -H "X-API-Key: $FABHUB_API_KEY"

{
  "data": [
    {
      "id": "a1c9...",
      "name": "Blue Widget",
      "sku": "WIDG-BLUE",
      "itemType": "product",
      "salePrice": 19.99,
      "purchasePrice": 8.5,
      "isActive": true,
      "category": { "id": "cat_1", "name": "Widgets" },
      "supplier": { "id": "sup_1", "name": "Acme", "company": "Acme Ltd" },
      "updatedAt": "2026-06-19T14:02:00Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 2, "total": 57, "totalPages": 29 }
}

POST /v1/items

Scope: items:write. Requiere Idempotency-Key. Crea un item.

curl -X POST https://api.fabhub.app/v1/items \
  -H "X-API-Key: $FABHUB_API_KEY" \
  -H "Idempotency-Key: 0b9c4a2e-..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Blue Widget","itemType":"product","salePrice":19.99}'

Devuelve { "data": { ...item } } con el item creado.

GET /v1/items/{item_id}

Scope: items:read. Devuelve { "data": { ...item } }, o 404 con code: "NOT_FOUND".

PATCH /v1/items/{item_id}

Scope: items:write. Requiere Idempotency-Key. Acepta cualquier subconjunto de los campos de creación y devuelve el item actualizado.

Subrecursos de item

• GET /v1/items/{item_id}/ingredients (scope items:read) - componentes de un item combo/fabricado.
• GET /v1/items/{item_id}/suppliers (scope items:read) - proveedores vinculados a un item.

Orders

GET /v1/orders

Scope: orders:read.

{
  "data": [
    {
      "id": "ord_1",
      "module": "sell",
      "orderNumber": "SO-1042",
      "status": "open",
      "contactId": "con_7",
      "orderDate": "2026-06-18",
      "dueDate": "2026-06-25",
      "siteId": null,
      "priority": "normal",
      "assignedTo": null,
      "contact": { "id": "con_7", "name": "Globex" },
      "site": null,
      "createdAt": "2026-06-18T10:00:00Z",
      "updatedAt": "2026-06-18T10:05:00Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 20, "total": 3, "totalPages": 1 }
}

Las orders también admiten POST /v1/orders, GET /v1/orders/{order_id} y PATCH /v1/orders/{order_id} (las escrituras requieren Idempotency-Key), además de GET /v1/orders/{order_id}/lines (scope orders:read) para las líneas de la order. Consulta el contrato OpenAPI para los cuerpos de petición exactos.

Contacts

GET /v1/contacts

Scope: contacts:read.

Cada contact: id, name, email, phone, company, contactType, country, contactGroup, isPrimaryContact, isActive, updatedAt.

Los contacts también admiten POST /v1/contacts, GET /v1/contacts/{contact_id} y PATCH /v1/contacts/{contact_id} (las escrituras requieren Idempotency-Key); consulta el contrato OpenAPI para los campos.

Organization

GET /v1/organization

Scope: organization:read. Devuelve { "data": { "id", "name", "slug", "plan", "createdAt" } } donde plan es free | standard | pro | enterprise.

Usage

GET /v1/usage

Scope: usage:read. Devuelve el periodo de facturación actual, los totales de peticiones (globales y por capacidad) y el nivel de límite de tasa con el presupuesto restante. Consulta Límites de tasa.

Eventos de auditoría

GET /v1/audit/events

Scope: audit:read (Enterprise). Exportación paginada por cursor.

{
  "data": [
    {
      "id": "evt_1",
      "actorType": "api",
      "actorId": "key_8f...",
      "action": "item.created",
      "resourceType": "item",
      "resourceId": "a1c9...",
      "metadata": {},
      "ipAddress": "203.0.113.10",
      "createdAt": "2026-06-19T14:02:00Z"
    }
  ],
  "pagination": { "hasMore": true, "nextCursor": { "createdAt": "2026-06-19T14:02:00Z", "id": "evt_1" } }
}

Stock

GET /v1/stock-levels

Devuelve los niveles de stock actuales de los items del tenant (consulta la tabla anterior para el scope requerido, y el contrato OpenAPI para los filtros y la forma de la respuesta).

Webhooks

Los detalles completos del ciclo de vida y la firma están en Webhooks.