Riferimento API

Riferimento completo per l'API pubblica di FabHub. Il portale brandizzato è canonico; puoi anche caricare il contratto leggibile dalla macchina in qualsiasi visualizzatore OpenAPI (Swagger Editor, Redoc, Postman o il tuo IDE).

• OpenAPI JSON - OpenAPI YAML

URL base

https://api.fabhub.app/v1

Convenzioni

• Autenticati con X-API-Key (oppure Authorization: Bearer). Vedi Autenticazione.
• I corpi delle richieste sono JSON con chiavi camelCase; i filtri degli elenchi sono parametri di query snake_case.
• Gli endpoint di elenco sono basati su pagine e restituiscono un oggetto pagination; vedi Paginazione.
• Gli endpoint di scrittura richiedono un header Idempotency-Key; vedi Idempotenza.
• Gli errori usano un involucro stabile con un code leggibile dalla macchina; vedi Errori.

Tutti gli endpoint

Questa tabella è generata dal contratto OpenAPI ed elenca sempre ogni operazione pubblica e lo scope richiesto. Le sezioni seguenti sono esempi pratici per le risorse più comuni; il contratto OpenAPI è la fonte esaustiva per gli schemi di richiesta e risposta.

Servizio

GET /v1

Restituisce le funzionalità (metodo, percorso, scope) che la credenziale chiamante può usare. Nessuno scope richiesto.

GET /v1/auth/context

Restituisce il tenant, il piano, gli scope, il livello di rate limit e la scadenza della credenziale chiamante. Nessuno scope richiesto. Vedi l'esempio in Avvio rapido.

Articoli

GET /v1/items

Scope: items:read. Elenca gli articoli (prodotti, materiali, combo).

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. Richiede Idempotency-Key. Crea un articolo.

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

Restituisce { "data": { ...item } } con l'articolo creato.

GET /v1/items/{item_id}

Scope: items:read. Restituisce { "data": { ...item } }, oppure 404 con code: "NOT_FOUND".

PATCH /v1/items/{item_id}

Scope: items:write. Richiede Idempotency-Key. Accetta qualsiasi sottoinsieme dei campi di creazione e restituisce l'articolo aggiornato.

Sotto-risorse dell'articolo

• GET /v1/items/{item_id}/ingredients (scope items:read) - componenti per un articolo combo/manufacturato.
• GET /v1/items/{item_id}/suppliers (scope items:read) - fornitori collegati a un articolo.

Ordini

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

Gli ordini supportano anche POST /v1/orders, GET /v1/orders/{order_id} e PATCH /v1/orders/{order_id} (le scritture richiedono Idempotency-Key), oltre a GET /v1/orders/{order_id}/lines (scope orders:read) per le righe d'ordine. Vedi il contratto OpenAPI per i corpi esatti delle richieste.

Contatti

GET /v1/contacts

Scope: contacts:read.

Ogni contatto: id, name, email, phone, company, contactType, country, contactGroup, isPrimaryContact, isActive, updatedAt.

I contatti supportano anche POST /v1/contacts, GET /v1/contacts/{contact_id} e PATCH /v1/contacts/{contact_id} (le scritture richiedono Idempotency-Key); vedi il contratto OpenAPI per i campi.

Organizzazione

GET /v1/organization

Scope: organization:read. Restituisce { "data": { "id", "name", "slug", "plan", "createdAt" } } dove plan è free | standard | pro | enterprise.

Utilizzo

GET /v1/usage

Scope: usage:read. Restituisce il periodo di fatturazione corrente, i totali delle richieste (complessivi e per funzionalità) e il livello di rate limit con il budget rimanente. Vedi Rate limit.

Eventi di audit

GET /v1/audit/events

Scope: audit:read (Enterprise). Esportazione paginata tramite cursore.

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

Scorte

GET /v1/stock-levels

Restituisce i livelli di scorte attuali per gli articoli del tenant (vedi la tabella sopra per lo scope richiesto e il contratto OpenAPI per i filtri e la forma della risposta).

Webhook

I dettagli completi sul ciclo di vita e sulla firma sono in Webhook.