> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão Geral da Hub API

> Endpoints REST para o Marketplace Hub — navegar, visualizar, clonar, assinar, sincronizar e analisar catálogos publicados.

## Visão Geral

A **Hub API** fornece acesso programático ao Marketplace Hub — a exchange de conteúdo B2B onde workspaces publicam e descobrem catálogos de produtos. A API suporta tanto operações de consumidor (navegar, visualizar, clonar, assinar) quanto operações de publisher (analytics, despublicar).

***

## URL Base

Todos os endpoints da Hub API utilizam a seguinte base:

```
https://app.alana.shopping/api/hub/
```

***

## Grupos de endpoints

<CardGroup cols={2}>
  <Card title="Navegar Catálogos" icon="search" href="/api-reference/hub/browse-catalogs">
    `GET /hub/catalogs` — pesquisar e filtrar o feed público do Hub
  </Card>

  <Card title="Visualizar" icon="eye" href="/api-reference/hub/preview">
    `GET /hub/catalogs/{id}/preview` — primeiros 10 produtos + estatísticas, sem necessidade de clonar
  </Card>

  <Card title="Clonar e Assinar" icon="copy" href="/api-reference/hub/clone-subscribe">
    `POST /hub/catalogs/{id}/clone` e `/subscribe` — adquirir acesso ao catálogo
  </Card>

  <Card title="Sync e Conflitos" icon="refresh" href="/api-reference/hub/sync-conflicts">
    Gerenciamento de sincronização de assinaturas e resolução de conflitos
  </Card>

  <Card title="Analytics do Publisher" icon="chart-bar" href="/api-reference/hub/publisher-analytics">
    `GET /hub/catalogs/{id}/analytics` — visualizações, clones, assinantes, receita
  </Card>
</CardGroup>

***

## Autenticação

### Endpoints públicos (sem autenticação)

Os seguintes endpoints são acessíveis publicamente sem autenticação:

| Endpoint                                    | Descrição                        |
| ------------------------------------------- | -------------------------------- |
| `GET /api/hub/catalogs`                     | Navegar o feed público do Hub    |
| `GET /api/hub/catalogs/{catalogId}/preview` | Visualizar um catálogo publicado |

### Endpoints autenticados

Todos os outros endpoints requerem um Bearer token:

```
Authorization: Bearer sk_live_sua_chave_api
```

Operações de escrita (clonar, assinar, analytics) requerem que a chave API pertença a um workspace com plano ativo.

***

## Rate limits

| Tier            | Endpoints públicos    | Endpoints autenticados |
| --------------- | --------------------- | ---------------------- |
| Não autenticado | 60 requisições/minuto | —                      |
| Free            | 60 requisições/minuto | 60 requisições/minuto  |
| Pro             | 60 requisições/minuto | 300 requisições/minuto |
| Business        | 60 requisições/minuto | 600 requisições/minuto |
| Enterprise      | Customizado           | Customizado            |

Headers de rate limit são incluídos em cada resposta:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1742300400
```

Quando o limite é excedido, uma resposta 429 é retornada com o header `Retry-After`.

***

## Objeto HubCatalog

O objeto principal retornado pelos endpoints de navegação e visualização do Hub:

```json theme={null}
{
  "id": "hub_cat_9x8k2m",
  "name": "Coleção Primavera 2026",
  "description": "Mais de 500 SKUs de vestuário primavera curado das melhores marcas europeias.",
  "publisher": {
    "workspaceId": "ws_abc",
    "displayName": "EuroFashion Wholesale",
    "verified": true
  },
  "productCount": 512,
  "price": {
    "model": "free"
  },
  "category": "apparel",
  "tags": ["primavera", "2026", "europeu"],
  "score": 78,
  "subscribers": 34,
  "publishedAt": "2026-02-01T09:00:00Z",
  "lastUpdatedAt": "2026-03-10T14:30:00Z",
  "version": 5
}
```

***

## Respostas de erro

Todos os endpoints do Hub retornam formatos de erro padrão:

```json theme={null}
{
  "error": {
    "code": "CATALOG_NOT_FOUND",
    "message": "Catálogo hub_cat_xyz não existe ou foi despublicado",
    "details": null
  }
}
```

Códigos de erro comuns:

| Código                     | Status HTTP | Descrição                                                                 |
| -------------------------- | ----------- | ------------------------------------------------------------------------- |
| `CATALOG_NOT_FOUND`        | 404         | ID do catálogo do Hub não encontrado ou despublicado                      |
| `CATALOG_PRIVATE`          | 404         | Catálogo existe mas é privado (retornado como 404 para evitar enumeração) |
| `ALREADY_SUBSCRIBED`       | 409         | Workspace já tem uma assinatura ativa para este catálogo                  |
| `PAYMENT_REQUIRED`         | 402         | Catálogo pago — conclua o Checkout do Stripe antes de clonar/assinar      |
| `INSUFFICIENT_PERMISSIONS` | 403         | Operação não permitida para esta chave API                                |
| `RATE_LIMIT_EXCEEDED`      | 429         | Muitas requisições — veja o header `Retry-After`                          |