> For the complete documentation index, see [llms.txt](https://apidoc.toplojas.com.br/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.toplojas.com.br/master.md).

# API Toplojas

Bem-vindo à documentação da **API Toplojas**. Através dela sua loja pode integrar-se ao nosso sistema para gerenciar produtos, pedidos, clientes e muito mais.

A API é desenvolvida em **OpenAPI 3.0**, então você pode importar nosso arquivo **YAML** ou **JSON** no seu programa de teste de API preferido e explorar todos os métodos.

{% hint style="info" %}
:arrow\_left: Use o **menu lateral** para navegar por todos os detalhes de funcionamento da API e de seus métodos.
{% endhint %}

## 🚀 Comece por aqui

Se é a sua primeira vez, comece pelo **Guia Rápido** — do zero à primeira chamada:

{% content-ref url="/pages/BfXTqpE5BlMd0dFjXsV1" %}
[Guia Rápido](/funcionamento/guia-rapido.md)
{% endcontent-ref %}

Ou siga os passos individualmente:

{% content-ref url="/pages/-MObk4z78qnd5Uc2I2C4" %}
[Geração de Token](/funcionamento/geracao-de-token.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MObl7NP3zj882FPydVu" %}
[Conectando na API](/funcionamento/conectando-na-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/-MOhu6BpNGzDzk6tFd1l" %}
[Utilizando o Simulador Online](/funcionamento/utilizando-o-simulador-online.md)
{% endcontent-ref %}

{% content-ref url="/pages/MdDne9XokrDLETbAoRYK" %}
[Configurando o Postman](/funcionamento/configurando-o-postman.md)
{% endcontent-ref %}

## 🤖 Assistente IA (MCP)

Prefere **conversar com a sua loja** em vez de programar? Conecte o Claude, o ChatGPT ou outro aplicativo de IA à sua loja e pergunte em português normal — *"quantos produtos eu tenho?"*, *"me mostre os últimos pedidos"* — sem colar token nem escrever código.

{% content-ref url="/pages/9DL07vHrmLn1sMjUkn3k" %}
[Visão Geral](/assistente-ia-mcp/visao-geral.md)
{% endcontent-ref %}

{% hint style="info" %}
URL do conector: `https://admin-mcp.toplojas.com.br`. O assistente **consulta e altera** a sua loja (cadastra e edita, pedindo confirmação) — a única ação que ele **não** faz é **excluir**. Veja como conectar em [Instalação e Ativação](/assistente-ia-mcp/instalacao-e-ativacao.md).
{% endhint %}

## 📚 Módulos da API

Guias práticos de como gerenciar cada recurso. Clique para ver a visão geral de cada módulo:

| Módulo                                                       | O que você gerencia                                               |
| ------------------------------------------------------------ | ----------------------------------------------------------------- |
| [🛒 Pedidos](/pedidos/visao-geral.md)                        | Listar, detalhar, alterar status, informar rastreio e nota fiscal |
| [📦 Produtos](/produtos/visao-geral.md)                      | Listar, criar, editar, excluir produtos e gerenciar estoque       |
| [🗂️ Departamentos](/departamentos/visao-geral.md)           | Listar, criar, editar e excluir departamentos (categorias)        |
| [👥 Clientes](/clientes/visao-geral.md)                      | Consultar clientes e seus dados (somente leitura)                 |
| [🏷️ Cupons de Desconto](/cupons-de-desconto/visao-geral.md) | Listar, criar, editar e excluir cupons de desconto                |
| [✉️ Newsletter](/newsletter/visao-geral.md)                  | Listar, cadastrar, editar e excluir inscrições de newsletter      |
| [ℹ️ Informações](/informacoes/informacoes.md)                | Consultar status de pedidos, formas de entrega e de pagamento     |
| [🔔 Webhook](/funcionamento/webhook.md)                      | Receber notificações automáticas de eventos                       |

## 🧭 Guias de fluxo

Casos de uso completos que combinam vários módulos:

* [Processar um Pedido](/guias/processar-pedido.md) — do recebimento à entrega
* [Sincronizar Catálogo](/guias/sincronizar-catalogo.md) — departamentos, produtos e estoque

Com dúvidas ou problemas? Veja a [Solução de Problemas](/funcionamento/solucao-de-problemas.md), o [FAQ](/funcionamento/faq.md) e o [Glossário](/funcionamento/glossario.md).

## ℹ️ Informações principais

| Item              | Valor                                                             |
| ----------------- | ----------------------------------------------------------------- |
| **Endpoint base** | `https://api.toplojas.com.br/`                                    |
| **Autenticação**  | Headers `Authorization: Bearer [Token]` e `Loja: [Identificador]` |
| **Limite de uso** | 30 requisições por minuto                                         |
| **Codificação**   | JSON com charset UTF-8                                            |

## 📖 Referência da API

Consulte a documentação detalhada de cada método — com campos, exemplos e schemas — e teste tudo online no simulador:

{% embed url="<https://api.toplojas.com.br/doc/>" %}

## ⬇️ Download do OpenAPI

Importe o contrato da API no seu programa de testes:

### Formato JSON

{% embed url="<https://api.toplojas.com.br/doc/doc.json>" %}

### Formato YAML

{% embed url="<https://api.toplojas.com.br/doc/doc.yaml>" %}