# Autenticação
Source: https://docs.martan.app/api-reference/authentication



As rotas de **Orders** e **Products** utilizam autenticação por **API Key** do tipo `orders`.

## Headers Obrigatórios

Todas as requisições devem incluir os seguintes headers:

<ParamField type="string">
  Sua API key do tipo `orders`
</ParamField>

<ParamField type="string">
  ID da sua loja
</ParamField>

<ParamField type="string">
  Deve ser `application/json`
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://api.appmartan.com.br/orders \
    -H "X-API-Key: sua-api-key-aqui" \
    -H "X-Store-Id: 123" \
    -H "Content-Type: application/json" \
    -d '{
      "order_id": "ORD-12345",
      "order_date": "2024-01-01T00:00:00.000Z",
      "delivery_date": "2024-01-05T00:00:00.000Z",
      "products": [...],
      "customers": [...]
    }'
  ```
</RequestExample>

## Erros de Autenticação

<ResponseField name="status" type="number">
  Código HTTP do erro
</ResponseField>

<ResponseField name="error_code" type="number">
  Código de erro específico da API
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem de erro em inglês
</ResponseField>

<ResponseField name="user_message" type="object">
  Mensagens de erro traduzidas

  <Expandable title="Ver estrutura">
    <ResponseField name="en_us" type="string">
      Mensagem em inglês
    </ResponseField>

    <ResponseField name="pt_br" type="string">
      Mensagem em português
    </ResponseField>
  </Expandable>
</ResponseField>

### Códigos de Erro

| Status | Código  | Descrição                                      |
| ------ | ------- | ---------------------------------------------- |
| 401    | 8121200 | API key ausente no header X-API-Key            |
| 417    | 8121201 | Store ID ausente no header X-Store-Id          |
| 401    | 8121202 | API key inválida ou inativa                    |
| 401    | 8121203 | Store inativa                                  |
| 401    | 8121204 | API key expirada                               |
| 403    | 8121205 | Store ID não corresponde à API key             |
| 403    | 8121206 | Limite de uso de pedidos excedido para o plano |

### Exemplo de Resposta de Erro

<ResponseExample>
  ```json theme={null}
  {
    "status": 401,
    "error_code": 8121202,
    "message": "Invalid or inactive API key",
    "user_message": {
      "en_us": "Invalid or inactive API key",
      "pt_br": "API key inválida ou inativa"
    },
    "more_info": null
  }
  ```
</ResponseExample>


# Tratamento de Erros
Source: https://docs.martan.app/api-reference/error-handling

Formato padrão de erros e códigos de erro da API

Todas as respostas de erro seguem um formato padrão consistente, facilitando o tratamento e debugging.

## Formato Padrão de Erro

<ResponseField name="status" type="number">
  Código HTTP do erro
</ResponseField>

<ResponseField name="error_code" type="number">
  Código de erro específico da API Martan
</ResponseField>

<ResponseField name="message" type="string">
  Mensagem de erro em inglês
</ResponseField>

<ResponseField name="user_message" type="object">
  Mensagens de erro traduzidas

  <Expandable title="Ver estrutura">
    <ResponseField name="en_us" type="string">
      Mensagem em inglês
    </ResponseField>

    <ResponseField name="pt_br" type="string">
      Mensagem em português
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="more_info" type="object | null">
  Informações adicionais sobre o erro (quando disponível)
</ResponseField>

## Códigos de Erro por Categoria

### Autenticação

| Status | Código  | Descrição                                      |
| ------ | ------- | ---------------------------------------------- |
| 401    | 8121200 | API key ausente no header X-API-Key            |
| 417    | 8121201 | Store ID ausente no header X-Store-Id          |
| 401    | 8121202 | API key inválida ou inativa                    |
| 401    | 8121203 | Store inativa                                  |
| 401    | 8121204 | API key expirada                               |
| 403    | 8121205 | Store ID não corresponde à API key             |
| 403    | 8121206 | Limite de uso de pedidos excedido para o plano |

### Orders

| Status | Código | Descrição                                   |
| ------ | ------ | ------------------------------------------- |
| 400    | 802030 | Body JSON mal formatado ou validação falhou |
| 422    | 103    | Pedido já existe (duplicado)                |

### Products

| Status | Código | Descrição                                           |
| ------ | ------ | --------------------------------------------------- |
| 400    | 802030 | Body JSON mal formatado ou validação falhou         |
| 422    | 103    | Produto já existe (mesmo `product_id` e `store_id`) |
| 500    | 520    | Erro inesperado ao buscar ou criar produto          |

## Exemplos de Respostas de Erro

### Erro de Validação

<ResponseExample>
  ```json theme={null}
  {
    "status": 400,
    "error_code": 802030,
    "message": "Bad-formatted JSON body, details in user_message",
    "user_message": {
      "en_us": "products: Array must contain at least 1 element(s)",
      "pt_br": "products: Array must contain at least 1 element(s)"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causas comuns:**

* Array vazio em `products` ou `customers`
* Campo obrigatório ausente
* Tipo de dado incorreto
* Valor fora do intervalo permitido (ex: preço negativo)

### Erro de Duplicação (Orders)

<ResponseExample>
  ```json theme={null}
  {
    "status": 422,
    "error_code": 103,
    "message": "Order has already been sent",
    "user_message": {
      "en_us": "Duplicated, Order has already been sent",
      "pt_br": "Pedido já encontra-se criado"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** Já existe um pedido com o mesmo `order_id` e `store_id`.

**Solução:** Use um `order_id` único ou verifique se o pedido já foi criado anteriormente.

### Erro de Duplicação (Products)

<ResponseExample>
  ```json theme={null}
  {
    "status": 422,
    "error_code": 103,
    "message": "Product has already been sent",
    "user_message": {
      "en_us": "Duplicated, Product has already been sent",
      "pt_br": "Produto já encontra-se criado"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** Já existe um produto com o mesmo `product_id` e `store_id`.

**Solução:** Use um `product_id` único ou atualize o produto existente.

### Erro de Limite de Uso

<ResponseExample>
  ```json theme={null}
  {
    "status": 403,
    "error_code": 8121206,
    "message": "Order usage limit exceeded",
    "user_message": {
      "en_us": "Order usage limit exceeded for your plan",
      "pt_br": "Limite de uso de pedidos excedido para o seu plano"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** O plano da sua conta atingiu o limite de pedidos permitidos.

**Solução:** Entre em contato com o suporte ou faça upgrade do seu plano.

### Erro de Autenticação

<ResponseExample>
  ```json theme={null}
  {
    "status": 401,
    "error_code": 8121202,
    "message": "Invalid or inactive API key",
    "user_message": {
      "en_us": "Invalid or inactive API key",
      "pt_br": "API key inválida ou inativa"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causas comuns:**

* API key ausente no header
* API key inválida ou inativa
* API key expirada
* API key não é do tipo `orders`

**Solução:** Verifique se a API key está correta e ativa no painel da Martan.

### Erro de Store ID

<ResponseExample>
  ```json theme={null}
  {
    "status": 403,
    "error_code": 8121205,
    "message": "Store ID does not match API key",
    "user_message": {
      "en_us": "Store ID does not match API key",
      "pt_br": "Store ID não corresponde à API key"
    },
    "more_info": null
  }
  ```
</ResponseExample>

**Causa:** O `X-Store-Id` fornecido não corresponde à store associada à API key.

**Solução:** Verifique se o `X-Store-Id` está correto e corresponde à store da sua API key.

## Tratamento de Erros no Código

### JavaScript/TypeScript

```typescript theme={null}
try {
  const response = await fetch('https://api.appmartan.com.br/orders', {
    method: 'POST',
    headers: {
      'X-API-Key': 'sua-api-key',
      'X-Store-Id': '123',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(orderData)
  });

  if (!response.ok) {
    const error = await response.json();

    switch (error.error_code) {
      case 802030:
        console.error('Erro de validação:', error.user_message.pt_br);
        break;
      case 103:
        console.error('Duplicação:', error.user_message.pt_br);
        break;
      case 8121206:
        console.error('Limite excedido:', error.user_message.pt_br);
        break;
      default:
        console.error('Erro desconhecido:', error);
    }

    throw new Error(error.user_message.pt_br);
  }

  const result = await response.json();
  console.log('Pedido criado:', result.id);
} catch (error) {
  console.error('Erro na requisição:', error);
}
```

## Boas Práticas

1. **Sempre verifique o status HTTP**: Use `response.ok` ou verifique o código de status antes de processar a resposta.

2. **Trate erros específicos**: Use os códigos de erro para implementar lógica específica para cada tipo de erro.

3. **Exiba mensagens ao usuário**: Use `user_message.pt_br` ou `user_message.en_us` para exibir mensagens amigáveis.

4. **Log de erros**: Registre os erros completos para debugging, incluindo `error_code` e `message`.

5. **Retry para erros temporários**: Implemente retry logic para erros 5xx (erros do servidor).


# Criar Pedido
Source: https://docs.martan.app/api-reference/orders

POST /orders
Cria um novo pedido no Martan

## Headers

<ParamField type="string">
  Sua API key do tipo `orders`
</ParamField>

<ParamField type="string">
  ID da sua loja
</ParamField>

<ParamField type="string">
  Deve ser `application/json`
</ParamField>

## Body

<ParamField type="string">
  ID único do pedido no seu sistema
</ParamField>

<ParamField type="string">
  Data do pedido no formato ISO 8601 (ex: `2024-01-01T00:00:00.000Z`)
</ParamField>

<ParamField type="string">
  Data de entrega do pedido no formato ISO 8601
</ParamField>

<ParamField type="string">
  Data para solicitar review (opcional). Se não fornecido, será calculado automaticamente baseado nas configurações da store, evitando fins de semana.
</ParamField>

<ParamField type="array">
  Array de produtos do pedido (mínimo 1 produto)

  <Expandable title="Estrutura do produto">
    <ParamField type="string">
      ID do produto no seu sistema
    </ParamField>

    <ParamField type="string">
      SKU do produto
    </ParamField>

    <ParamField type="string">
      Nome do produto
    </ParamField>

    <ParamField type="number">
      Preço do produto (0 a 9999999999)
    </ParamField>

    <ParamField type="string">
      URL do produto
    </ParamField>

    <ParamField type="array">
      Array de URLs de imagens do produto
    </ParamField>

    <ParamField type="string">
      Código GTIN do produto
    </ParamField>

    <ParamField type="string">
      Código MPN do produto
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="array">
  Array de clientes do pedido (mínimo 1 cliente)

  <Expandable title="Estrutura do cliente">
    <ParamField type="string">
      Nome do cliente
    </ParamField>

    <ParamField type="string">
      Email do cliente
    </ParamField>

    <ParamField type="string">
      Telefone do cliente
    </ParamField>

    <ParamField type="string">
      Origem do cliente (ex: "website", "mobile", etc.)
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="id" type="string">
  ID único do pedido criado no sistema Martan
</ResponseField>

## Erros Possíveis

| Status | Código  | Descrição                                      |
| ------ | ------- | ---------------------------------------------- |
| 400    | 802030  | Body JSON mal formatado ou validação falhou    |
| 422    | 103     | Pedido já existe (duplicado)                   |
| 403    | 8121206 | Limite de uso de pedidos excedido para o plano |

<Note>
  `request_review_at` não foi fornecido, então será calculado automaticamente baseado nas configurações da Loja.
</Note>


# Criar Produto
Source: https://docs.martan.app/api-reference/products

POST /products
Cria um novo produto no Martan.

## Headers

<ParamField type="string">
  Sua API key do tipo `orders`
</ParamField>

<ParamField type="string">
  ID da sua loja
</ParamField>

<ParamField type="string">
  Deve ser `application/json`
</ParamField>

## Body

<ParamField type="string">
  ID único do produto no seu sistema
</ParamField>

<ParamField type="string">
  Nome do produto
</ParamField>

<ParamField type="number">
  Preço do produto (0 a 9999999999). Se não fornecido, será 0 por padrão.
</ParamField>

<ParamField type="string">
  SKU do produto
</ParamField>

<ParamField type="string">
  Código GTIN do produto
</ParamField>

<ParamField type="string">
  Código MPN do produto
</ParamField>

<ParamField type="string">
  URL do produto
</ParamField>

<ParamField type="array">
  Array de URLs de imagens do produto
</ParamField>

## Response

<ResponseField name="id" type="string">
  ID único do produto criado no sistema Martan
</ResponseField>

## Erros Possíveis

| Status | Código | Descrição                                           |
| ------ | ------ | --------------------------------------------------- |
| 400    | 802030 | Body JSON mal formatado ou validação falhou         |
| 422    | 103    | Produto já existe (mesmo `product_id` e `store_id`) |
| 500    | 520    | Erro inesperado ao buscar ou criar produto          |


# Schemas de Validação
Source: https://docs.martan.app/api-reference/schemas

Estrutura e validação dos dados para Orders e Products

## Orders Schema

O schema de Orders utiliza validação **strict**.

```typescript theme={null}
{
  order_id: string;                    // Obrigatório
  order_date: string;                  // Obrigatório (ISO 8601)
  delivery_date: string;               // Obrigatório (ISO 8601)
  request_review_at?: string;          // Opcional (ISO 8601)
  products: Array<{                    // Obrigatório (mínimo 1)
    product_id: string;                // Obrigatório
    sku: string;                       // Obrigatório
    name: string;                      // Obrigatório
    price: number;                     // Obrigatório (0-9999999999)
    url: string;                       // Obrigatório
    pictures?: string[];               // Opcional
    gtin?: string;                     // Opcional
    mpn?: string;                      // Opcional
  }>;
  customers: Array<{                   // Obrigatório (mínimo 1)
    name: string;                      // Obrigatório
    email: string;                      // Obrigatório
    phone: string;                      // Obrigatório
    origin?: string;                    // Opcional
  }>;
}
```

### Características do Schema de Orders

* **Schema strict**: não permite campos adicionais
* **Validação mínima**: produtos e clientes devem ter pelo menos 1 item
* **Datas em ISO 8601**: formato `YYYY-MM-DDTHH:mm:ss.sssZ`

### Validações de Orders

| Campo                   | Tipo   | Obrigatório | Validação        |
| ----------------------- | ------ | ----------- | ---------------- |
| `order_id`              | string | Sim         | -                |
| `order_date`            | string | Sim         | Formato ISO 8601 |
| `delivery_date`         | string | Sim         | Formato ISO 8601 |
| `request_review_at`     | string | Não         | Formato ISO 8601 |
| `products`              | array  | Sim         | Mínimo 1 item    |
| `products[].product_id` | string | Sim         | -                |
| `products[].sku`        | string | Sim         | -                |
| `products[].name`       | string | Sim         | -                |
| `products[].price`      | number | Sim         | 0 a 9999999999   |
| `products[].url`        | string | Sim         | -                |
| `products[].pictures`   | array  | Não         | Array de strings |
| `products[].gtin`       | string | Não         | -                |
| `products[].mpn`        | string | Não         | -                |
| `customers`             | array  | Sim         | Mínimo 1 item    |
| `customers[].name`      | string | Sim         | -                |
| `customers[].email`     | string | Sim         | -                |
| `customers[].phone`     | string | Sim         | -                |
| `customers[].origin`    | string | Não         | -                |

## Products Schema

O schema de Products utiliza validação **strict**, não permitindo campos adicionais.

```typescript theme={null}
{
  product_id: string;                  // Obrigatório
  name: string;                        // Obrigatório
  price: number;                        // Obrigatório (0-9999999999, padrão: 0)
  sku: string;                         // Obrigatório
  gtin: string;                        // Obrigatório
  mpn: string;                         // Obrigatório
  url: string;                         // Obrigatório
  pictures?: string[];                 // Opcional
}
```

### Características do Schema de Products

* **Schema strict**: não permite campos adicionais
* **Preço tem valor padrão**: se não fornecido, será 0
* **Todos os campos (exceto `pictures`) são obrigatórios**

### Validações de Products

| Campo        | Tipo   | Obrigatório | Validação                  |
| ------------ | ------ | ----------- | -------------------------- |
| `product_id` | string | Sim         | -                          |
| `name`       | string | Sim         | -                          |
| `price`      | number | Sim         | 0 a 9999999999 (padrão: 0) |
| `sku`        | string | Sim         | -                          |
| `gtin`       | string | Sim         | -                          |
| `mpn`        | string | Sim         | -                          |
| `url`        | string | Sim         | -                          |
| `pictures`   | array  | Não         | Array de strings           |

## Exemplos de Validação

### Orders - Exemplo Válido

```json theme={null}
{
  "order_id": "ORD-12345",
  "order_date": "2024-01-01T00:00:00.000Z",
  "delivery_date": "2024-01-05T00:00:00.000Z",
  "products": [
    {
      "product_id": "PROD-001",
      "sku": "SKU-001",
      "name": "Produto Exemplo",
      "price": 99.90,
      "url": "https://example.com/produto",
      "pictures": ["https://example.com/img1.jpg"],
      "gtin": "1234567890123",
      "mpn": "MPN-001"
    }
  ],
  "customers": [
    {
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "+5511999999999",
      "origin": "website"
    }
  ]
}
```

### Orders - Exemplo Inválido

```json theme={null}
{
  "order_id": "ORD-12345",
  "order_date": "2024-01-01T00:00:00.000Z",
  "delivery_date": "2024-01-05T00:00:00.000Z",
  "products": [],
  "customers": [],
  "invalid_field": "valor"  // ❌ Não permitido (schema strict)
}
```

**Erro retornado:**

* `products: Array must contain at least 1 element(s)`
* `customers: Array must contain at least 1 element(s)`
* `invalid_field: Unrecognized key(s) in object`

### Products - Exemplo Válido

```json theme={null}
{
  "product_id": "PROD-001",
  "name": "Produto Exemplo",
  "price": 99.90,
  "sku": "SKU-001",
  "gtin": "1234567890123",
  "mpn": "MPN-001",
  "url": "https://example.com/produto",
  "pictures": [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg"
  ]
}
```

### Products - Exemplo Inválido

```json theme={null}
{
  "product_id": "PROD-001",
  "name": "Produto Exemplo",
  "price": 99.90,
  "sku": "SKU-001",
  "invalid_field": "valor"  // ❌ Não permitido (schema strict)
}
```

**Erro retornado:**

* `gtin: Required`
* `mpn: Required`
* `url: Required`
* `invalid_field: Unrecognized key(s) in object`

## Formato de Datas

Todas as datas devem estar no formato **ISO 8601**:

```
YYYY-MM-DDTHH:mm:ss.sssZ
```

**Exemplos:**

* `2024-01-01T00:00:00.000Z`
* `2024-01-15T10:30:00.000Z`
* `2024-12-31T23:59:59.999Z`

## Validação de Preços

Os preços devem estar no intervalo:

* **Mínimo**: 0
* **Máximo**: 9.999.999.999

<Warning>
  Valores negativos ou acima do máximo resultarão em erro de validação.
</Warning>


# E-Com Plus
Source: https://docs.martan.app/integracoes/ecomplus

Saiba como integrar sua loja com Martan.

Para utilizar o Martan em sua loja na E-Com Plus precisamos configurar alguns passos.
Primeiramente precisamos instalar nosso aplicativo na sua loja, e após isso configuramos nossos widgets.

### Instalar Aplicativo

Passo 1: Instale o aplicativo Martan na sua loja, isso pode ser feito através do [market](https://market.e-com.plus/apps/martan-avaliacao-de-produtos).
Siga as instruções para instalar na sua loja, esse app será responsável pela sincronização de pedidos e produtos.
Obs: é necessario criar a sua conta antes da instalação do app para seguir fluxo de oauth.

Após esta etapa o aplicativo está pronto para se comunicar com nossa API sincronizando novos pedidos automaticamente.


# Introdução
Source: https://docs.martan.app/introduction

Bem vindo à documentação oficial do Martan

O Martan é uma plataforma completa de **avaliações e perguntas para e-commerce**, projetada para aumentar a confiança dos clientes e impulsionar suas vendas através de prova social.

Nossa documentação foi organizada para ajudar você a integrar nossas soluções da maneira mais eficiente possível, seja utilizando nossos Widgets prontos, conectando-se via API ou utilizando nossas integrações nativas.

## O que você pode fazer

<CardGroup>
  <Card title="Widgets" icon="puzzle-piece" href="/widgets/introduction">
    Implemente avaliações, ratings e perguntas em sua loja usando nossos Web Components modernos e customizáveis.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/authentication">
    Explore nossa API REST para criar integrações personalizadas, gerenciar produtos e pedidos programaticamente.
  </Card>

  <Card title="Integrações" icon="link" href="/integracoes/ecomplus">
    Veja como conectar o Martan facilmente com plataformas de e-commerce como a E-Com Plus.
  </Card>

  <Card title="Suporte" icon="headset" href="mailto:contato@martan.app">
    Precisa de ajuda? Entre em contato com nosso time de suporte para resolver suas dúvidas.
  </Card>
</CardGroup>

## Funcionalidades Principais

Nossos widgets são construídos para performance e facilidade de uso:

* **Reviews Widget**: Exiba avaliações detalhadas com fotos e filtros.
* **Rating Widget**: Mostre a média de estrelas nos cards de produtos para aumentar o CTR.
* **Questions Widget**: Permita que clientes tirem dúvidas diretamente na página do produto.

Comece agora mesmo explorando a seção de [Widgets](/widgets/introduction).


# Formato de Dados da API
Source: https://docs.martan.app/widgets/api-format

Estrutura de dados esperada pela API Martan

## Reviews Widget

O widget consome a API Martan e espera o seguinte formato de resposta:

```json theme={null}
{
  "result": [
    {
      "id": "string",
      "display_name": "string",
      "rating": 5,
      "body": "string",
      "title": "string",
      "created_at": "2024-01-15T00:00:00Z",
      "verified_purchase": true,
      "is_recommended": true,
      "pictures": []
    }
  ],
  "count": 100,
  "meta": {
    "limit": 10,
    "offset": 0,
    "query": {
      "product_sku": "PROD-123"
    }
  }
}
```

### Campos do Review

| Campo               | Tipo    | Descrição                  |
| ------------------- | ------- | -------------------------- |
| `id`                | string  | ID único da avaliação      |
| `display_name`      | string  | Nome do avaliador          |
| `rating`            | number  | Nota de 1 a 5              |
| `body`              | string  | Texto da avaliação         |
| `title`             | string  | Título da avaliação        |
| `created_at`        | string  | Data de criação (ISO 8601) |
| `verified_purchase` | boolean | Se a compra foi verificada |
| `is_recommended`    | boolean | Se o produto é recomendado |
| `pictures`          | array   | Array de URLs de imagens   |

## Rating Widget

O widget de rating consome a API Martan no endpoint `/api/v1/ratings.json?expand=metrics` e espera o seguinte formato:

```json theme={null}
{
  "result": [
    {
      "sku": "PROD-123",
      "product_id": "123",
      "average": 4.5,
      "total": 120,
      "recommended": 100,
      "not_recommended": 5,
      "recommended_percentage": 83.33,
      "rate": {
        "one": 0,
        "two": 2,
        "three": 8,
        "four": 30,
        "five": 80
      }
    }
  ],
  "count": 1
}
```

### Campos do Rating

| Campo                    | Tipo   | Descrição                               |
| ------------------------ | ------ | --------------------------------------- |
| `sku`                    | string | SKU do produto                          |
| `product_id`             | string | ID do produto                           |
| `average`                | number | Média de avaliações (0-5)               |
| `total`                  | number | Total de avaliações                     |
| `recommended`            | number | Número de recomendações                 |
| `not_recommended`        | number | Número de não recomendações             |
| `recommended_percentage` | number | Percentual de recomendações             |
| `rate`                   | object | Distribuição por estrelas               |
| `rate.one`               | number | Quantidade de avaliações com 1 estrela  |
| `rate.two`               | number | Quantidade de avaliações com 2 estrelas |
| `rate.three`             | number | Quantidade de avaliações com 3 estrelas |
| `rate.four`              | number | Quantidade de avaliações com 4 estrelas |
| `rate.five`              | number | Quantidade de avaliações com 5 estrelas |

<Note>
  O widget faz cache dos dados no localStorage por 24 horas para otimizar performance. Apenas uma requisição à API é feita por página, mesmo com múltiplos componentes.
</Note>


# Configuração Global
Source: https://docs.martan.app/widgets/configuration

Configure credenciais uma única vez e compartilhe entre todos os widgets

Para evitar repetir `data-store-id` e `data-store-key` em cada widget, você pode configurar essas credenciais uma única vez e compartilhar entre todos os widgets.

## Opção 1: Via JavaScript (Recomendado)

Configure antes de carregar os widgets:

```html theme={null}
<script>
  // Define o stub do MartanConfig antes do módulo carregar
  window.MartanConfig = window.MartanConfig || {
    _pendingConfig: null,
    init: function (options) {
      // Se o módulo já carregou, chama o init real
      if (window.MartanConfig._realInit) {
        window.MartanConfig._realInit(options)
      } else {
        // Caso contrário, armazena para aplicar depois
        window.MartanConfig._pendingConfig = options
      }
    },
  }
  // Aplica a configuração imediatamente
  window.MartanConfig.init({
    storeId: 'your_store_id_generate_at_www_app_martan_app',
    storeKey: 'your_store_key_generate_at_www_app_martan_app',
  })
</script>
<script type="module" src="https://cdn.martan.app/widgets.js"></script>
```

## Opção 2: Via Data Attributes

Defina no elemento `<body>` ou `<html>`:

```html theme={null}
<body data-martan-store-id="seu-store-id" data-martan-store-key="sua-store-key">
  <!-- Seus widgets aqui -->
</body>
```

## Uso com Configuração Global

Após configurar globalmente, você pode usar os widgets sem repetir as credenciais:

```html theme={null}
<!-- Configuração global já definida acima -->
<martan-rating data-product-sku="PROD-123"></martan-rating>
<martan-reviews data-product-sku="PROD-123"></martan-reviews>
<martan-questions data-product-sku="PROD-123"></martan-questions>
```

<Note>
  Se um widget tiver `data-store-id` ou `data-store-key` definidos localmente, esses valores terão
  **prioridade** sobre a configuração global. Isso permite sobrescrever a configuração global para
  casos específicos.
</Note>


# Customização
Source: https://docs.martan.app/widgets/customization

Personalize os widgets usando CSS variables

Os widgets podem ser customizados usando CSS variables, permitindo que você adapte as cores, espaçamentos e tipografia para combinar com o design da sua loja.

## Variáveis CSS Disponíveis

### Cores

| Variável                  | Descrição                                              |
| ------------------------- | ------------------------------------------------------ |
| `--rw-primary-color`      | Cor primária (botões, links)                           |
| `--rw-text-color`         | Cor do texto principal                                 |
| `--rw-text-secondary`     | Cor do texto secundário                                |
| `--rw-border-color`       | Cor das bordas                                         |
| `--rw-bg-color`           | Cor de fundo                                           |
| `--rw-bg-secondary`       | Cor de fundo secundária                                |
| `--rw-star-color`         | Cor das estrelas preenchidas                           |
| `--rw-star-empty`         | Cor das estrelas vazias                                |
| `--rw-progress-bar-color` | Cor das barras de progresso (distribuição de estrelas) |

### Espaçamentos

| Variável          | Descrição                 |
| ----------------- | ------------------------- |
| `--rw-spacing-xs` | Espaçamento extra pequeno |
| `--rw-spacing-sm` | Espaçamento pequeno       |
| `--rw-spacing-md` | Espaçamento médio         |
| `--rw-spacing-lg` | Espaçamento grande        |
| `--rw-spacing-xl` | Espaçamento extra grande  |

### Tipografia

| Variável              | Descrição                |
| --------------------- | ------------------------ |
| `--rw-font-family`    | Família de fontes        |
| `--rw-font-size-base` | Tamanho de fonte base    |
| `--rw-font-size-sm`   | Tamanho de fonte pequeno |
| `--rw-font-size-lg`   | Tamanho de fonte grande  |

### Outros

| Variável             | Descrição       |
| -------------------- | --------------- |
| `--rw-border-radius` | Raio das bordas |
| `--rw-shadow`        | Sombra padrão   |
| `--rw-shadow-md`     | Sombra média    |

## Exemplo de Customização

```html theme={null}
<style>
  martan-reviews {
    --rw-primary-color: #10b981;
    --rw-star-color: #f59e0b;
    --rw-progress-bar-color: #f59e0b;
    --rw-bg-color: #ffffff;
    --rw-text-color: #1f2937;
    --rw-font-family: 'Arial', sans-serif;
  }

  martan-rating {
    --rw-star-color: #f59e0b;
    --rw-text-color: #1f2937;
    --rw-text-secondary: #6b7280;
  }
</style>
```

## Customização por Widget

Você pode customizar cada widget individualmente:

```html theme={null}
<style>
  /* Customização apenas para o widget de reviews */
  martan-reviews {
    --rw-primary-color: #10b981;
  }

  /* Customização apenas para o widget de rating */
  martan-rating {
    --rw-star-color: #f59e0b;
  }

  /* Customização apenas para o widget de questions */
  martan-questions {
    --rw-primary-color: #3b82f6;
  }
</style>
```

## Customização Global

Para aplicar customizações a todos os widgets:

```html theme={null}
<style>
  :root {
    --rw-primary-color: #10b981;
    --rw-star-color: #f59e0b;
    --rw-text-color: #1f2937;
    --rw-font-family: 'Inter', sans-serif;
  }
</style>
```


# Uso com Storefront v1 (E-Com.Plus)
Source: https://docs.martan.app/widgets/ecomplus-storefront-v1

Configuração dos widgets no Storefront v1 da E-Com Plus

[Demo](https://demo.martan.app)

### Configurar Widgets

Integrado ao storefront disponibilizamos três tipos de widgets; Rating, Reviews e Perguntas e Responstas.
Para usá-lo basta procurar o widget do Martan na coleção de Widget no seu CMS.
Após habilitar o Widget basta configurar quais widgets quer exibir e outras opções.

<img alt="title" />

## Configurações

<ResponseField name="Id da Loja (StoreId)" type="number">
  Identificador da Loja [Ver](https://dash.martan.app/stores).
</ResponseField>

<ResponseField name="Web Id (Api-Key)" type="string">
  Web Id [Ver](https://dash.martan.app/stores).
</ResponseField>

<ResponseField name="Ativar" type="boolean">
  Opção para habilitar exibição dos widgets no storefront.
</ResponseField>

Feita as configurações iniciais podemos configurar quais widgets iremos usar.

### Widget Rating (Card Produtos)

<img alt="title" />

## Opções

<ResponseField name="Habilitar Widget" type="boolean">
  Opção para habilitar exibição do widget no storefront.
</ResponseField>

<ResponseField name="Exibir na página de Pesquisa?" type="boolean">
  Opção para exibir widget no card de produtos na página de pesquisa
</ResponseField>

<ResponseField name="Tamanho da Fonte" type="number">
  Tamanho do icone das estrelas
</ResponseField>

<ResponseField name="Cor do Icone de Estrelas" type="string">
  Cor do icone
</ResponseField>

<ResponseField name="Estilo do Widget" type="string">
  Estilo do Widget: Pode ser Completo ou Compacto.
</ResponseField>

<ResponseField name="Exibição condicional" type="string">
  Quando exibir o widget: Exibir sempre ou apenas quando o produto tiver mais de 1 avaliação.
</ResponseField>

<img alt="title" />

### Widget Reviews

<img alt="title" />

## Opções

<ResponseField name="Habilitar Widget" type="boolean">
  Opção para habilitar exibição do widget no storefront.
</ResponseField>

<ResponseField name="Título" type="string">
  Título do Widget (exibido na página de produtos)
</ResponseField>

<ResponseField name="Cor do Icone de Estrelas" type="string">
  Cor do icone
</ResponseField>

<ResponseField name="Estilo de Cabeçalho" type="string">
  Opções: Padrão, Histogram, Compacto, Centralizado, Resumo
</ResponseField>

<ResponseField name="Estilo do Layout" type="string">
  Opções: Grid ou Lista
</ResponseField>

### Widget Perguntas e Respostas

<img alt="title" />

## Opções

<ResponseField name="Habilitar Widget" type="boolean">
  Opção para habilitar exibição do widget no storefront.
</ResponseField>

<ResponseField name="Título" type="string">
  Título do Widget (exibido na página de produtos)
</ResponseField>

<ResponseField name="Habilitar novas perguntas" type="boolean">
  Habilitar novas perguntas
</ResponseField>


# Exemplos Completos
Source: https://docs.martan.app/widgets/examples

Exemplos práticos de uso dos widgets Martan

## Exemplo Completo com Configuração Global

Exemplo completo usando configuração global:

```html theme={null}
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Exemplo - Widgets Martan</title>
</head>
<body>
  <!-- Configuração global via JavaScript -->
  <script>
    window.MartanConfig = window.MartanConfig || {}
    window.MartanConfig.init({
      storeId: 'STORE_ID_DA_LOJA',
      storeKey: 'STORE_KEY_TIPO_REVIEWS'
    })
  </script>

  <!-- Carregar os widgets -->
  <script type="module" src="https://cdn.martan.app/widgets.js"></script>

  <!-- Usar os widgets sem repetir store-id e store-key -->
  <h2>Rating do Produto</h2>
  <martan-rating data-product-sku="PROD-123"></martan-rating>

  <h2>Avaliações do Produto</h2>
  <martan-reviews
    data-product-sku="PROD-123"
    data-header-type="default"
    data-list-type="grid">
  </martan-reviews>

  <h2>Perguntas e Respostas</h2>
  <martan-questions
    data-product-sku="PROD-123"
    data-enable-new-questions="true">
  </martan-questions>
</body>
</html>
```

## Alternativa com Data Attributes

```html theme={null}
<body
  data-martan-store-id="STORE_ID_DA_LOJA"
  data-martan-store-key="STORE_KEY_TIPO_REVIEWS">

  <script type="module" src="https://cdn.martan.app/widgets.js"></script>

  <!-- Widgets aqui -->
  <martan-rating data-product-sku="PROD-123"></martan-rating>
  <martan-reviews data-product-sku="PROD-123"></martan-reviews>
  <martan-questions data-product-sku="PROD-123"></martan-questions>
</body>
```

## Exemplo com Customização CSS

```html theme={null}
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Widgets Customizados</title>
  <style>
    martan-reviews {
      --rw-primary-color: #10b981;
      --rw-star-color: #f59e0b;
      --rw-progress-bar-color: #f59e0b;
      --rw-bg-color: #ffffff;
      --rw-text-color: #1f2937;
      --rw-font-family: 'Inter', sans-serif;
    }

    martan-rating {
      --rw-star-color: #f59e0b;
      --rw-text-color: #1f2937;
      --rw-text-secondary: #6b7280;
    }
  </style>
</head>
<body>
  <script>
    window.MartanConfig = window.MartanConfig || {}
    window.MartanConfig.init({
      storeId: 'STORE_ID_DA_LOJA',
      storeKey: 'STORE_KEY_TIPO_REVIEWS'
    })
  </script>
  <script type="module" src="https://cdn.martan.app/widgets.js"></script>

  <martan-rating
    data-product-sku="PROD-123"
    data-star-color="#10b981"
    data-theme="compact">
  </martan-rating>

  <martan-reviews
    data-product-sku="PROD-123"
    data-header-type="histogram"
    data-list-type="list">
  </martan-reviews>
</body>
</html>
```

## Exemplo com Auto-Discovery (Rating)

```html theme={null}
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Auto-Discovery Rating</title>
</head>
<body>
  <!-- Elementos com classes específicas -->
  <div class="product-card">
    <h3>Produto 1</h3>
    <div class="product-card__rating" data-sku="PROD-123"></div>
  </div>

  <div class="product-card">
    <h3>Produto 2</h3>
    <div class="product-card__rating" data-sku="PROD-456"></div>
  </div>

  <script type="module" src="https://cdn.martan.app/widgets.js"></script>
  <script>
    // Inicializar auto-discovery após o módulo carregar
    window.addEventListener('DOMContentLoaded', () => {
      window.MartanRating.init({
        store_id: 'STORE_ID_DA_LOJA',
        web_id: 'STORE_KEY_TIPO_REVIEWS',
        widget_rating: {
          star_color: '#fbbf24',
          theme: 'compact',
          custom_class: '.product-card__rating'
        }
      });
    });
  </script>
</body>
</html>
```


# Uso com Frameworks
Source: https://docs.martan.app/widgets/frameworks

Integre os widgets Martan em React, Vue e outros frameworks

Os widgets Martan são Web Components padrão e podem ser usados diretamente em qualquer framework moderno.

## React

### 1. Configuração Inicial

Primeiro, carregue o script dos widgets no seu `index.html` ou `_document.tsx` (Next.js):

```html theme={null}
<!-- public/index.html ou pages/_document.tsx -->
<script>
  window.MartanConfig = window.MartanConfig || {}
  window.MartanConfig.init({
    storeId: 'seu-store-id',
    storeKey: 'sua-store-key'
  })
</script>
<script type="module" src="https://cdn.martan.app/widgets.js"></script>
```

### 2. Declarar Tipos TypeScript (opcional)

Crie um arquivo `martan-widgets.d.ts` para tipagem:

```typescript theme={null}
// src/types/martan-widgets.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'martan-rating': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        'data-store-id'?: string
        'data-store-key'?: string
        'data-product-id'?: string
        'data-product-sku'?: string
        'data-star-color'?: string
        'data-theme'?: string
        'data-disable-auto-fetch'?: boolean
        rating?: number
        'total-reviews'?: number
      },
      HTMLElement
    >
    'martan-reviews': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        'data-store-id'?: string
        'data-store-key'?: string
        'data-product-id'?: string
        'data-product-sku'?: string
        'data-items-per-page'?: number
        'data-header-type'?: string
        'data-list-type'?: string
      },
      HTMLElement
    >
    'martan-questions': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        'data-store-id'?: string
        'data-store-key'?: string
        'data-product-id'?: string
        'data-product-sku'?: string
        'data-enable-new-questions'?: boolean
      },
      HTMLElement
    >
  }
}
```

### 3. Componentes React

```tsx theme={null}
// components/ProductRating.tsx
import React from 'react'

interface ProductRatingProps {
  productSku: string
  productId?: string
  starColor?: string
  theme?: 'compact' | null
}

export const ProductRating: React.FC<ProductRatingProps> = ({
  productSku,
  productId,
  starColor,
  theme
}) => {
  return (
    <martan-rating
      data-product-sku={productSku}
      data-product-id={productId}
      data-star-color={starColor}
      data-theme={theme || undefined}
    />
  )
}
```

```tsx theme={null}
// components/ProductReviews.tsx
import React from 'react'

interface ProductReviewsProps {
  productSku: string
  productId?: string
  itemsPerPage?: number
  headerType?: 'default' | 'histogram' | 'compact' | 'minimal' | 'centered'
  listType?: 'grid' | 'list'
}

export const ProductReviews: React.FC<ProductReviewsProps> = ({
  productSku,
  productId,
  itemsPerPage = 10,
  headerType = 'default',
  listType = 'grid'
}) => {
  return (
    <martan-reviews
      data-product-sku={productSku}
      data-product-id={productId}
      data-items-per-page={itemsPerPage}
      data-header-type={headerType}
      data-list-type={listType}
    />
  )
}
```

```tsx theme={null}
// components/ProductQuestions.tsx
import React from 'react'

interface ProductQuestionsProps {
  productSku: string
  productId?: string
  enableNewQuestions?: boolean
}

export const ProductQuestions: React.FC<ProductQuestionsProps> = ({
  productSku,
  productId,
  enableNewQuestions = true
}) => {
  return (
    <martan-questions
      data-product-sku={productSku}
      data-product-id={productId}
      data-enable-new-questions={enableNewQuestions}
    />
  )
}
```

### 4. Uso em uma Página

```tsx theme={null}
// pages/ProductPage.tsx
import React from 'react'
import { ProductRating } from '../components/ProductRating'
import { ProductReviews } from '../components/ProductReviews'
import { ProductQuestions } from '../components/ProductQuestions'

const ProductPage: React.FC<{ productSku: string }> = ({ productSku }) => {
  return (
    <div>
      <h1>Produto</h1>

      <ProductRating
        productSku={productSku}
        starColor="#fbbf24"
      />

      <ProductReviews
        productSku={productSku}
        headerType="default"
        listType="grid"
      />

      <ProductQuestions
        productSku={productSku}
        enableNewQuestions={true}
      />
    </div>
  )
}

export default ProductPage
```

### SSR (Server-Side Rendering)

Os widgets são client-side only. Em Next.js, use `dynamic` import:

```tsx theme={null}
// Next.js
import dynamic from 'next/dynamic'

const ProductRating = dynamic(
  () => import('../components/ProductRating'),
  { ssr: false }
)
```

## Vue

### 1. Configuração Inicial

No seu `index.html` ou `nuxt.config.ts` (Nuxt.js):

```html theme={null}
<!-- public/index.html -->
<script>
  window.MartanConfig = window.MartanConfig || {}
  window.MartanConfig.init({
    storeId: 'seu-store-id',
    storeKey: 'sua-store-key'
  })
</script>
<script type="module" src="https://cdn.martan.app/widgets.js"></script>
```

### 2. Componentes Vue

```vue theme={null}
<!-- components/ProductRating.vue -->
<template>
  <martan-rating
    :data-product-sku="productSku"
    :data-product-id="productId"
    :data-star-color="starColor"
    :data-theme="theme"
  />
</template>

<script setup lang="ts">
interface Props {
  productSku: string
  productId?: string
  starColor?: string
  theme?: 'compact' | null
}

withDefaults(defineProps<Props>(), {
  starColor: '#ffc107',
  theme: null
})
</script>
```

```vue theme={null}
<!-- components/ProductReviews.vue -->
<template>
  <martan-reviews
    :data-product-sku="productSku"
    :data-product-id="productId"
    :data-items-per-page="itemsPerPage"
    :data-header-type="headerType"
    :data-list-type="listType"
  />
</template>

<script setup lang="ts">
interface Props {
  productSku: string
  productId?: string
  itemsPerPage?: number
  headerType?: 'default' | 'histogram' | 'compact' | 'minimal' | 'centered'
  listType?: 'grid' | 'list'
}

withDefaults(defineProps<Props>(), {
  itemsPerPage: 10,
  headerType: 'default',
  listType: 'grid'
})
</script>
```

```vue theme={null}
<!-- components/ProductQuestions.vue -->
<template>
  <martan-questions
    :data-product-sku="productSku"
    :data-product-id="productId"
    :data-enable-new-questions="enableNewQuestions"
  />
</template>

<script setup lang="ts">
interface Props {
  productSku: string
  productId?: string
  enableNewQuestions?: boolean
}

withDefaults(defineProps<Props>(), {
  enableNewQuestions: true
})
</script>
```

### 3. Uso em uma Página

```vue theme={null}
<!-- pages/ProductPage.vue -->
<template>
  <div>
    <h1>Produto</h1>

    <ProductRating
      :product-sku="productSku"
      star-color="#fbbf24"
    />

    <ProductReviews
      :product-sku="productSku"
      header-type="default"
      list-type="grid"
    />

    <ProductQuestions
      :product-sku="productSku"
      :enable-new-questions="true"
    />
  </div>
</template>

<script setup lang="ts">
import ProductRating from '@/components/ProductRating.vue'
import ProductReviews from '@/components/ProductReviews.vue'
import ProductQuestions from '@/components/ProductQuestions.vue'

const route = useRoute()
const productSku = computed(() => route.params.sku as string)
</script>
```

### 4. Nuxt.js - Configuração Global

Para Nuxt.js, você pode adicionar o script no `nuxt.config.ts`:

```typescript theme={null}
// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      scripts: [
        {
          innerHTML: `
            window.MartanConfig = window.MartanConfig || {}
            window.MartanConfig.init({
              storeId: 'seu-store-id',
              storeKey: 'sua-store-key'
            })
          `,
          type: 'text/javascript'
        },
        {
          src: 'https://cdn.martan.app/widgets.js',
          type: 'module'
        }
      ]
    }
  }
})
```

### SSR (Server-Side Rendering)

Em Nuxt.js, use `ClientOnly` wrapper:

```vue theme={null}
<!-- Nuxt.js -->
<template>
  <ClientOnly>
    <ProductRating :product-sku="productSku" />
  </ClientOnly>
</template>
```

## Notas Importantes

1. **Atributos com hífen**: Em React, use `data-product-sku` (com hífen) ou `dataProductSku` (camelCase). Em Vue, use `:data-product-sku` ou `data-product-sku`.

2. **Configuração Global**: Configure `window.MartanConfig` antes de carregar os widgets para evitar repetir credenciais.

3. **TypeScript**: Os tipos são opcionais, mas recomendados para melhor experiência de desenvolvimento.

4. **SSR (Server-Side Rendering)**: Os widgets são client-side only. Use `dynamic` import (Next.js) ou `ClientOnly` wrapper (Nuxt.js).


# Instalação
Source: https://docs.martan.app/widgets/installation

Como instalar e usar os widgets Martan

## Uso Básico

### Incluir o Script no HTML

<Warning>
  O widget é um módulo ES, então **sempre** precisa ser carregado com `type="module"`. Sem isso, você receberá o erro `Uncaught SyntaxError: Unexpected token 'export'`.
</Warning>

```html theme={null}
<script type="module" src="https://cdn.martan.app/widgets.js"></script>
```

<Note>
  Os componentes são registrados automaticamente como `<martan-reviews>`, `<martan-rating>` e `<martan-questions>`, então você não precisa importar as classes se estiver usando apenas HTML.
</Note>

## Exemplo Mínimo

```html theme={null}
<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <title>Widgets Martan</title>
</head>
<body>
  <!-- Carregar os widgets -->
  <script type="module" src="https://cdn.martan.app/widgets.js"></script>

  <!-- Usar os widgets -->
  <martan-rating
    data-store-id="seu-store-id"
    data-store-key="sua-store-key"
    data-product-sku="PROD-123">
  </martan-rating>
</body>
</html>
```


# Introdução aos Widgets
Source: https://docs.martan.app/widgets/introduction

Coleção de widgets usando Web Components (Lit) para uso em e-commerces

Os widgets Martan são componentes web construídos com **Web Components (Lit)** que podem ser facilmente integrados em qualquer e-commerce. Os widgets são distribuídos via CDN como módulos ES e oferecem uma experiência completa de avaliações, ratings e perguntas e respostas.

## Widgets Disponíveis

<CardGroup>
  <Card title="Reviews Widget" icon="star" href="/widgets/reviews-widget">
    Widget completo de avaliações com múltiplos layouts e funcionalidades
  </Card>

  <Card title="Rating Widget" icon="star-half" href="/widgets/rating-widget">
    Widget simples de exibição de rating com estrelas e total de avaliações
  </Card>

  <Card title="Questions Widget" icon="question-circle" href="/widgets/questions-widget">
    Widget de perguntas e respostas sobre produtos
  </Card>
</CardGroup>

## Características Principais

* ✅ **Web Components padrão** - Funcionam em qualquer framework ou HTML puro
* ✅ **Distribuição via CDN** - Fácil integração sem build steps
* ✅ **Módulos ES** - Suporte moderno e tree-shaking
* ✅ **Customizável** - CSS variables para personalização completa
* ✅ **Responsivo** - Layouts adaptáveis a diferentes telas
* ✅ **Performance** - Cache inteligente e requisições otimizadas


# Questions Widget
Source: https://docs.martan.app/widgets/questions-widget

Widget de perguntas e respostas sobre produtos

O widget de perguntas e respostas permite que clientes façam perguntas sobre produtos e visualizem respostas de outros clientes e lojistas.

## Uso Básico

O widget de perguntas e respostas permite que clientes façam perguntas sobre produtos e visualizem respostas:

```html theme={null}
<martan-questions
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-sku="PROD-123"
  data-enable-new-questions="true">
</martan-questions>
```

Ou usando `product-id`:

```html theme={null}
<martan-questions
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-id="123"
  data-enable-new-questions="true">
</martan-questions>
```

**Com configuração global:**

```html theme={null}
<!-- Configuração global já definida -->
<martan-questions
  data-product-sku="PROD-123"
  data-enable-new-questions="true">
</martan-questions>
```

## Propriedades

### Atributos HTML

| Atributo                    | Tipo    | Obrigatório | Descrição                                      |
| --------------------------- | ------- | ----------- | ---------------------------------------------- |
| `data-store-id`             | string  | Sim\*       | ID da loja na API Martan                       |
| `data-store-key`            | string  | Sim\*       | Chave da API (web\_id) da loja                 |
| `data-product-id`           | string  | Sim\*       | ID do produto na API Martan                    |
| `data-product-sku`          | string  | Sim\*       | SKU do produto na API Martan                   |
| `data-enable-new-questions` | boolean | Não         | Permite criar novas perguntas (padrão: `true`) |

<Note>
  \* `data-store-id` e `data-store-key` podem ser omitidos se configurados globalmente. É necessário fornecer `data-product-id` OU `data-product-sku` (não ambos).
</Note>

### Propriedades JavaScript

| Propriedade          | Tipo    | Descrição                     |
| -------------------- | ------- | ----------------------------- |
| `storeId`            | string  | ID da loja                    |
| `storeKey`           | string  | Chave da API                  |
| `productId`          | string  | ID do produto                 |
| `productSku`         | string  | SKU do produto                |
| `enableNewQuestions` | boolean | Permite criar novas perguntas |

## Exemplos

<WidgetQuestions />

## Funcionalidades

* ✅ Integração com API Martan
* ✅ Listagem de perguntas e respostas
* ✅ Busca por palavras-chave
* ✅ Formulário para criar novas perguntas (via iframe)
* ✅ Carregamento incremental (mostrar mais perguntas)
* ✅ Suporte a respostas de lojistas


# Rating Widget
Source: https://docs.martan.app/widgets/rating-widget

Widget simples de exibição de rating com estrelas e total de avaliações

<WidgetRatingPadrao />

O widget de rating exibe a avaliação média de um produto com estrelas e o total de avaliações. Ele pode buscar dados automaticamente da API Martan ou receber valores diretos.

## Uso Direto

O widget de rating pode ser usado diretamente com props para buscar automaticamente da API:

```html theme={null}
<martan-rating
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-sku="PROD-123"
  data-star-color="#fbbf24"
  data-theme="compact"
>
</martan-rating>
```

Ou usando `product-id`:

```html theme={null}
<martan-rating
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-id="123"
  data-theme="compact"
>
</martan-rating>
```

## Auto-Discovery

O widget também suporta auto-discovery, procurando automaticamente elementos no DOM com classes específicas:

```html theme={null}
<div class="product-card__rating" data-sku="PROD-123"></div>
```

E então inicializar o auto-discovery:

```javascript theme={null}
window.MartanRating.init({
  store_id: 'seu-store-id',
  web_id: 'sua-store-key',
  widget_rating: {
    star_color: '#fbbf24',
    theme: 'compact',
    custom_class: '.minha-classe-custom',
  },
})
```

O widget irá:

* Criar automaticamente componentes `<martan-rating>` nos elementos encontrados
* Observar o DOM para novos elementos adicionados dinamicamente

## Propriedades

### Atributos HTML

| Atributo                  | Tipo    | Obrigatório | Descrição                                            |
| ------------------------- | ------- | ----------- | ---------------------------------------------------- |
| `data-store-id`           | string  | Sim\*       | ID da loja na API Martan                             |
| `data-store-key`          | string  | Sim\*       | Chave da API (web\_id) da loja                       |
| `data-product-id`         | string  | Sim\*       | ID do produto na API Martan                          |
| `data-product-sku`        | string  | Sim\*       | SKU do produto na API Martan                         |
| `data-star-color`         | string  | Não         | Cor das estrelas (padrão: `#ffc107`)                 |
| `data-theme`              | string  | Não         | Tema do widget (padrão: `null`)                      |
| `data-disable-auto-fetch` | boolean | Não         | Desabilita busca automática da API (padrão: `false`) |

<Note>
  \* `data-store-id` e `data-store-key` podem ser omitidos se configurados globalmente. É necessário
  fornecer `data-product-id` OU `data-product-sku` (não ambos).
</Note>

**Valores possíveis para `data-theme`:**

* `compact` - Exibe apenas uma estrela com rating
* `null` (padrão) - Exibe 5 estrelas com rating e total

### Propriedades JavaScript

| Propriedade        | Tipo    | Descrição                                            |
| ------------------ | ------- | ---------------------------------------------------- |
| `storeId`          | string  | ID da loja                                           |
| `storeKey`         | string  | Chave da API                                         |
| `productId`        | string  | ID do produto                                        |
| `productSku`       | string  | SKU do produto                                       |
| `starColor`        | string  | Cor das estrelas                                     |
| `theme`            | string  | Tema do widget (`compact` ou `null`)                 |
| `rating`           | number  | Rating direto (0-5) - se fornecido, não busca da API |
| `totalReviews`     | number  | Total de avaliações - se fornecido, não busca da API |
| `disableAutoFetch` | boolean | Desabilita busca automática                          |

## Exemplos

### Tema Padrão (5 estrelas)

<WidgetRatingPadrao />

```html theme={null}
<martan-rating
  data-product-sku="PA321"
>
</martan-rating>
```

### Tema Compacto

<WidgetRatingCompacto />

```html theme={null}
<martan-rating
  data-product-sku="PA321"
  data-theme="compact"
>
</martan-rating>
```

### Com Cor Customizada

<WidgetRatingCor />

```html theme={null}
<martan-rating
  data-product-sku="PA321"
  data-star-color="#10b981"
>
</martan-rating>
```

### Com Tamanho Customizado

<WidgetRatingSize />

```html theme={null}
<martan-rating
  data-product-sku="PA321"
  data-size="16"
>
</martan-rating>
```

### Com Dados Diretos (sem buscar da API)

```html theme={null}
<martan-rating rating="4.5" total-reviews="120"> </martan-rating>
```

### Customização Avançada

Para mais opções de estilização usando variáveis CSS, consulte a página de [Customização](/widgets/customization).

## Funcionalidades

* ✅ Integração com API Martan
* ✅ Auto-discovery de elementos no DOM
* ✅ Requisição única à API (compartilhada entre múltiplos componentes)
* ✅ Dois temas: padrão (5 estrelas) e compacto (1 estrela)
* ✅ Customização de cor das estrelas
* ✅ Suporte a dados diretos (sem buscar da API)
* ✅ Observação automática do DOM para novos elementos
* ✅ Customização via CSS variables


# Reviews Widget
Source: https://docs.martan.app/widgets/reviews-widget

Widget completo de avaliações com múltiplos layouts e funcionalidades

O widget de avaliações permite que clientes visualizem e interajam com avaliações de produtos. Ele oferece múltiplos layouts, filtros, busca e paginação.

## Uso Básico

O widget sempre busca as avaliações da API Martan. Configure as credenciais e o produto:

```html theme={null}
<martan-reviews
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-id="123"
  data-items-per-page="10"
  data-header-type="default"
  data-list-type="grid"
>
</martan-reviews>
```

Ou usando SKU do produto com layout em lista:

```html theme={null}
<martan-reviews
  data-store-id="seu-store-id"
  data-store-key="sua-store-key"
  data-product-sku="PROD-123"
  data-items-per-page="10"
  data-list-type="list"
>
</martan-reviews>
```

## Propriedades

### Atributos HTML

| Atributo              | Tipo   | Obrigatório | Descrição                                              |
| --------------------- | ------ | ----------- | ------------------------------------------------------ |
| `data-store-id`       | string | Sim\*       | ID da loja na API Martan                               |
| `data-store-key`      | string | Sim\*       | Chave da API (web\_id) da loja                         |
| `data-product-id`     | string | Sim\*       | ID do produto na API Martan                            |
| `data-product-sku`    | string | Sim\*       | SKU do produto na API Martan                           |
| `data-items-per-page` | number | Não         | Número de itens por página (padrão: 10)                |
| `data-header-type`    | string | Não         | Tipo de header a exibir (padrão: "default")            |
| `data-list-type`      | string | Não         | Tipo de layout da lista de avaliações (padrão: "grid") |

<Note>
  \* `data-store-id` e `data-store-key` podem ser omitidos se configurados globalmente. É necessário
  fornecer `data-product-id` OU `data-product-sku` (não ambos).
</Note>

**Valores possíveis para `data-header-type`:**

* `default` - Header padrão com estatísticas
* `histogram` - Header com histograma de distribuição
* `compact` - Header compacto
* `minimal` - Header minimalista
* `centered` - Header centralizado

**Valores possíveis para `data-list-type`:**

* `grid` - 2 cards lado a lado (padrão)
* `list` - 1 card por linha, full width

### Propriedades JavaScript

| Propriedade    | Tipo   | Descrição                              |
| -------------- | ------ | -------------------------------------- |
| `storeId`      | string | ID da loja                             |
| `storeKey`     | string | Chave da API                           |
| `productId`    | string | ID do produto                          |
| `productSku`   | string | SKU do produto                         |
| `itemsPerPage` | number | Itens por página                       |
| `headerType`   | string | Tipo de header                         |
| `listType`     | string | Tipo de layout da lista (grid ou list) |

## Exemplos

### Padrão

<WidgetReviews />

### Customizando aparencia com CSS Variable

```html theme={null}
<style>
  martan-reviews {
    --rw-primary-color: #10b981;
    --rw-star-color: #f59e0b;
    --rw-progress-bar-color: #f59e0b;
    --rw-bg-color: #ffffff;
    --rw-text-color: #1f2937;
    --rw-font-family: 'Arial', sans-serif;
  }
</style>
```

<WidgetReviewsCustom />

### Headers Disponíveis

<WidgetReviewsHeaders />

## Funcionalidades

* ✅ Integração com API Martan
* ✅ Listagem de avaliações com layout responsivo
* ✅ Múltiplos tipos de header (default, histogram, compact, minimal, centered)
* ✅ Filtros por número de estrelas
* ✅ Busca por texto (via API)
* ✅ Ordenação (data, rating)
* ✅ Paginação e carregamento incremental
* ✅ Estatísticas (média, distribuição de estrelas)
* ✅ Customização via CSS variables
* ✅ Debounce na busca para melhor performance