API 참조

FabHub 공개 API에 대한 완전한 참조입니다. 브랜드 포털이 공식 기준이며, 기계가 읽을 수 있는 계약을 OpenAPI 뷰어(Swagger Editor, Redoc, Postman 또는 IDE)에 로드할 수도 있습니다.

• OpenAPI JSON - OpenAPI YAML

기본 URL

https://api.fabhub.app/v1

규칙

• X-API-Key(또는 Authorization: Bearer)로 인증합니다. 인증을 참조하세요.
• 요청 본문은 camelCase 키를 사용하는 JSON이며, 목록 필터는 snake_case 쿼리 매개변수입니다.
• 목록 엔드포인트는 페이지 기반이며 pagination 객체를 반환합니다. 페이지네이션을 참조하세요.
• 쓰기 엔드포인트는 Idempotency-Key 헤더를 요구합니다. 멱등성을 참조하세요.
• 오류는 기계가 읽을 수 있는 code가 포함된 안정적인 봉투를 사용합니다. 오류를 참조하세요.

모든 엔드포인트

이 표는 OpenAPI 계약에서 생성되며, 항상 모든 공개 작업과 필요한 스코프를 나열합니다. 아래 섹션은 가장 일반적인 리소스에 대한 실제 예시이며, OpenAPI 계약이 요청 및 응답 스키마에 대한 완전한 소스입니다.

서비스

GET /v1

호출하는 자격 증명이 사용할 수 있는 기능(메서드, 경로, 스코프)을 반환합니다. 스코프가 필요하지 않습니다.

GET /v1/auth/context

호출하는 자격 증명의 테넌트, 플랜, 스코프, 속도 제한 등급, 만료를 반환합니다. 스코프가 필요하지 않습니다. 퀵스타트의 예시를 참조하세요.

항목

GET /v1/items

스코프: items:read. 항목(제품, 자재, 콤보)을 나열합니다.

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

스코프: items:write. Idempotency-Key가 필요합니다. 항목을 생성합니다.

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

생성된 항목과 함께 { "data": { ...item } }를 반환합니다.

GET /v1/items/{item_id}

스코프: items:read. { "data": { ...item } }를 반환하거나, code: "NOT_FOUND"와 함께 404를 반환합니다.

PATCH /v1/items/{item_id}

스코프: items:write. Idempotency-Key가 필요합니다. 생성 필드의 임의 하위 집합을 받아 업데이트된 항목을 반환합니다.

항목 하위 리소스

• GET /v1/items/{item_id}/ingredients(스코프 items:read) - combo/제조 항목의 구성 요소.
• GET /v1/items/{item_id}/suppliers(스코프 items:read) - 항목에 연결된 공급업체.

주문

GET /v1/orders

스코프: 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 }
}

주문은 또한 POST /v1/orders, GET /v1/orders/{order_id}, PATCH /v1/orders/{order_id}(쓰기에는 Idempotency-Key가 필요함)와, 라인 항목을 위한 GET /v1/orders/{order_id}/lines(스코프 orders:read)를 지원합니다. 정확한 요청 본문은 OpenAPI 계약을 참조하세요.

연락처

GET /v1/contacts

스코프: contacts:read.

각 연락처: id, name, email, phone, company, contactType, country, contactGroup, isPrimaryContact, isActive, updatedAt.

연락처는 또한 POST /v1/contacts, GET /v1/contacts/{contact_id}, PATCH /v1/contacts/{contact_id}(쓰기에는 Idempotency-Key가 필요함)를 지원합니다. 필드는 OpenAPI 계약을 참조하세요.

조직

GET /v1/organization

스코프: organization:read. { "data": { "id", "name", "slug", "plan", "createdAt" } }를 반환하며, 여기서 plan은 free | standard | pro | enterprise입니다.

사용량

GET /v1/usage

스코프: usage:read. 현재 청구 기간, 요청 총계(전체 및 기능별), 그리고 잔여 예산이 포함된 속도 제한 등급을 반환합니다. 속도 제한을 참조하세요.

감사 이벤트

GET /v1/audit/events

스코프: audit:read(Enterprise). 커서 페이지네이션 내보내기입니다.

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

재고

GET /v1/stock-levels

테넌트 항목의 현재 재고 수준을 반환합니다(필요한 스코프는 위 표를, 필터 및 응답 형태는 OpenAPI 계약을 참조하세요).

웹훅

전체 수명 주기 및 서명 세부 정보는 웹훅에 있습니다.