Referência da API

Referência completa para a API pública da FabHub. O portal de marca é canónico; também pode carregar o contrato legível por máquina em qualquer visualizador de OpenAPI (Swagger Editor, Redoc, Postman ou o seu IDE).

• OpenAPI JSON - OpenAPI YAML

URL base

https://api.fabhub.app/v1

Convenções

• Autentique-se com X-API-Key (ou Authorization: Bearer). Consulte Autenticação.
• Os corpos de pedido são JSON com chaves em camelCase; os filtros de listagem são parâmetros de consulta em snake_case.
• Os endpoints de listagem são baseados em páginas e devolvem um objeto pagination; consulte Paginação.
• Os endpoints de escrita exigem um cabeçalho Idempotency-Key; consulte Idempotência.
• Os erros usam um envelope estável com um code legível por máquina; consulte Erros.

Todos os endpoints

Esta tabela é gerada a partir do contrato OpenAPI e lista sempre todas as operações públicas e o respetivo scope necessário. As secções abaixo são exemplos práticos para os recursos mais comuns; o contrato OpenAPI é a fonte exaustiva para os esquemas de pedido e resposta.

Serviço

GET /v1

Devolve as capacidades (método, caminho, scope) que a credencial que faz a chamada pode usar. Não requer scope.

GET /v1/auth/context

Devolve o tenant, o plano, os scopes, o nível de limite de taxa e a expiração da credencial que faz a chamada. Não requer scope. Veja o exemplo em Quickstart.

Itens

GET /v1/items

Scope: items:read. Lista itens (produtos, materiais, 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. Requer Idempotency-Key. Cria um 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}'

Devolve { "data": { ...item } } com o item criado.

GET /v1/items/{item_id}

Scope: items:read. Devolve { "data": { ...item } }, ou 404 com code: "NOT_FOUND".

PATCH /v1/items/{item_id}

Scope: items:write. Requer Idempotency-Key. Aceita qualquer subconjunto dos campos de criação e devolve o item atualizado.

Sub-recursos do item

• GET /v1/items/{item_id}/ingredients (scope items:read) - componentes de um item combo/fabricado.
• GET /v1/items/{item_id}/suppliers (scope items:read) - fornecedores associados a um item.

Encomendas

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 }
}

As encomendas também suportam POST /v1/orders, GET /v1/orders/{order_id} e PATCH /v1/orders/{order_id} (as escritas exigem Idempotency-Key), além de GET /v1/orders/{order_id}/lines (scope orders:read) para as linhas. Consulte o contrato OpenAPI para os corpos de pedido exatos.

Contactos

GET /v1/contacts

Scope: contacts:read.

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

Os contactos também suportam POST /v1/contacts, GET /v1/contacts/{contact_id} e PATCH /v1/contacts/{contact_id} (as escritas exigem Idempotency-Key); consulte o contrato OpenAPI para os campos.

Organização

GET /v1/organization

Scope: organization:read. Devolve { "data": { "id", "name", "slug", "plan", "createdAt" } } em que plan é free | standard | pro | enterprise.

Utilização

GET /v1/usage

Scope: usage:read. Devolve o período de faturação atual, os totais de pedidos (globais e por capacidade) e o nível de limite de taxa com o orçamento restante. Consulte Limites de Taxa.

Eventos de auditoria

GET /v1/audit/events

Scope: audit:read (Enterprise). Exportação 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

Devolve os níveis de stock atuais para os itens do tenant (veja a tabela acima para o scope necessário, e o contrato OpenAPI para os filtros e a forma da resposta).

Webhooks

O ciclo de vida completo e os detalhes de assinatura estão em Webhooks.