# 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)
{% endcontent-ref %}
Ou siga os passos individualmente:
{% content-ref url="/pages/-MObk4z78qnd5Uc2I2C4" %}
[Geração de Token](/funcionamento/geracao-de-token)
{% endcontent-ref %}
{% content-ref url="/pages/-MObl7NP3zj882FPydVu" %}
[Conectando na API](/funcionamento/conectando-na-api)
{% endcontent-ref %}
{% content-ref url="/pages/-MOhu6BpNGzDzk6tFd1l" %}
[Utilizando o Simulador Online](/funcionamento/utilizando-o-simulador-online)
{% endcontent-ref %}
{% content-ref url="/pages/MdDne9XokrDLETbAoRYK" %}
[Configurando o Postman](/funcionamento/configurando-o-postman)
{% 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)
{% 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).
{% 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) | Listar, detalhar, alterar status, informar rastreio e nota fiscal |
| [📦 Produtos](/produtos/visao-geral) | Listar, criar, editar, excluir produtos e gerenciar estoque |
| [🗂️ Departamentos](/departamentos/visao-geral) | Listar, criar, editar e excluir departamentos (categorias) |
| [👥 Clientes](/clientes/visao-geral) | Consultar clientes e seus dados (somente leitura) |
| [🏷️ Cupons de Desconto](/cupons-de-desconto/visao-geral) | Listar, criar, editar e excluir cupons de desconto |
| [✉️ Newsletter](/newsletter/visao-geral) | Listar, cadastrar, editar e excluir inscrições de newsletter |
| [ℹ️ Informações](/informacoes/informacoes) | Consultar status de pedidos, formas de entrega e de pagamento |
| [🔔 Webhook](/funcionamento/webhook) | 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) — do recebimento à entrega
* [Sincronizar Catálogo](/guias/sincronizar-catalogo) — departamentos, produtos e estoque
Com dúvidas ou problemas? Veja a [Solução de Problemas](/funcionamento/solucao-de-problemas), o [FAQ](/funcionamento/faq) e o [Glossário](/funcionamento/glossario).
## ℹ️ 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="" %}
## ⬇️ Download do OpenAPI
Importe o contrato da API no seu programa de testes:
### Formato JSON
{% embed url="" %}
### Formato YAML
{% embed url="" %}
# Guia Rápido
Este guia leva você do **zero** à sua **primeira chamada bem-sucedida** à API, em poucos minutos.
## 1️⃣ Obtenha o Token e o Identificador da Loja
No painel da loja, acesse **Sistema → Configurações Gerais → API de Acesso Externo → Atualizar Token** e copie o **Identificador** e o **Token**.
O passo a passo completo, com telas, está em:
{% content-ref url="/pages/-MObk4z78qnd5Uc2I2C4" %}
[Geração de Token](/funcionamento/geracao-de-token)
{% endcontent-ref %}
## 2️⃣ Monte a primeira requisição
Toda requisição precisa de dois headers de autenticação:
```
Authorization: Bearer [Token]
Loja: [Identificador de Sua Loja]
```
Vamos testar o endpoint `/status/`, que serve justamente para verificar se a API está disponível e se sua autenticação está correta:
```bash
curl -X GET "https://api.toplojas.com.br/status/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Substitua `[Token]` e `[Identificador de Sua Loja]` pelos valores obtidos no passo 1.
## 3️⃣ Interprete a resposta
Se tudo estiver correto, a API responde com o HTTP Code **204** (sucesso, sem conteúdo). Isso significa que sua loja está autenticada e pronta para usar a API.
Se receber um erro, consulte:
{% content-ref url="/pages/SYlZNpYxy5JUMvCVzaSQ" %}
[Solução de Problemas](/funcionamento/solucao-de-problemas)
{% endcontent-ref %}
## ✅ Próximos passos
Agora que sua autenticação funciona, explore os módulos:
* 🛒 [Pedidos](/pedidos/visao-geral) — consultar e gerenciar pedidos
* 📦 [Produtos](/produtos/visao-geral) — cadastrar e gerenciar produtos e estoque
* 🔔 [Webhook](/funcionamento/webhook) — receber notificações automáticas de eventos
{% hint style="info" %}
Prefere testar sem escrever código? Use o [Simulador Online](/funcionamento/utilizando-o-simulador-online) ou configure o [Postman](/funcionamento/configurando-o-postman).
{% endhint %}
{% hint style="info" %}
Lembre-se dos limites e padrões da API (limite de requisições, formato de datas e decimais) descritos em [Considerações Gerais](/funcionamento/consideracoes-gerais).
{% endhint %}
# Considerações Gerais
## Limite de Requisições
A API possui limite de 30 requisições por minuto
## Codificação
Toda recepção e envio de dados deve ser feito em **JSON** com **Charset UTF-8**
## Padrão de Campos
| Tipo de Campo | Padrão Esperado |
| ------------- | -------------------------------------------------------------- |
| Data | Ano-Mês-Dia - Exemplo: 2020-12-01 |
| Data e Hora | Ano-Mês-Dia Hora:Minuto:Segundo - Exemplo: 2020-12-01 12:00:00 |
| Decimal | Separado por "." no decimal - Exemplo: 1500.25 |
| Inteiro | Número inteiro limitado a 10 caracteres |
# Geração de Token
Para utilizar a API você precisa de duas informações da sua loja:
* **Identificador da Loja** — enviado no header `Loja` de cada requisição.
* **Token da Loja** — enviado no header `Authorization` (precedido de `Bearer`).
Ambos são obtidos no painel da loja, em poucos passos.
## Passo 1 — Abrir a API de Acesso Externo
No painel, acesse **Sistema → Configurações Gerais → API de Acesso Externo**:
## Passo 2 — Atualizar o Token
Na janela exibida, clique em **Atualizar Token**:
## Passo 3 — Copiar o Identificador e o Token
Após atualizar, o **Identificador** e o **Token** serão exibidos. Copie os dois valores:
{% hint style="warning" %}
Ao clicar em **Atualizar Token**, o token anterior é **invalidado** e deixa de funcionar. Se você já usa a API em alguma integração, atualize o token nela após gerar um novo.
Guarde o **Token** com segurança: ele dá acesso aos dados da sua loja.
{% endhint %}
Com o Identificador e o Token em mãos, o próximo passo é se conectar à API:
{% content-ref url="/pages/-MObl7NP3zj882FPydVu" %}
[Conectando na API](/funcionamento/conectando-na-api)
{% endcontent-ref %}
# Conectando na API
## Endpoint
A conexão com a API é feita através do **Endpoint**:
{% hint style="info" %}
{% endhint %}
## Autenticação
Para se autenticar na API, é necessário o **Token** e o **Identificador da Loja**, eles são enviados no **Header** da Requisição através dos parâmetros:
```
Authorization: Bearer [Token]
Loja: [Identificador de Sua Loja]
```
### Exemplo
O mesmo exemplo, via **curl**, chamando o endpoint `/status/`:
```bash
curl -X GET "https://api.toplojas.com.br/status/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
{% hint style="info" %}
No header "**Authorization**" não esqueça de começar com "**Bearer**".
**Exemplo:**
Authorization: Bearer AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
{% endhint %}
# Retornos Possíveis (HTTP Status Codes)
O resultado de cada requisição é indicado pelo **HTTP Status Code** retornado. Sempre consulte esse código para saber se a requisição funcionou ou qual problema ocorreu.
## ✅ Sucesso
Códigos na faixa **2xx** indicam que a requisição foi processada com sucesso.
| Código | Significado | Quando ocorre |
| ------- | ----------------------------- | ------------------------------------------------------ |
| **200** | Sucesso, com dados retornados | Consultas que retornam informações (ex.: listagens) |
| **201** | Registro criado / editado | Cadastro ou edição concluído com sucesso |
| **204** | Ação executada com sucesso | Ação concluída que não retorna conteúdo (ex.: remoção) |
## ❌ Erro
Qualquer código **fora da faixa 2xx** indica que algo deu errado. Nesses casos, o corpo da resposta traz o elemento **`Mensagem`** com a causa do erro.
| Código | Significado | Quando ocorre |
| ------- | -------------------- | ------------------------------------------------------------ |
| **400** | Requisição inválida | Faltam campos essenciais (`Loja`, `Token`, `Modulo`, `Acao`) |
| **401** | Não autorizado | Token inválido — gere um novo token no painel da loja |
| **404** | Não encontrado | Módulo ou ação não localizados |
| **405** | Método não permitido | O método HTTP usado não é aceito por esse endpoint |
| **422** | Falha de validação | Os dados enviados não passaram na validação |
{% content-ref url="/pages/-MOhyjfrwXCAIeHNbhHn" %}
[Erros](/funcionamento/erros)
{% endcontent-ref %}
## Exemplo
No exemplo abaixo, a requisição retornou o status **204** (ação executada com sucesso):
# Erros
Sempre que uma requisição retornar um **HTTP Code** diferente de "**20\***" indica que algum problema aconteceu, você pode consultar a listagem dos HTTP Code possíveis em:
{% content-ref url="/pages/-MObtn9uSkZCREngcvXe" %}
[Retornos Possíveis (HTTP Status Codes)](/funcionamento/retornos-possiveis-http-status-codes)
{% endcontent-ref %}
Junto ao HTTP Code, enviamos um elemento chamado de "**Mensagem**" que indica a **causa do erro.**
### Exemplo:
Uma requisição com dados inválidos retorna o HTTP Code **422** e o corpo abaixo:
```json
{
"Mensagem": "Preencha o campo NOME"
}
```
Exemplo de requisição que gera esse erro (envio sem o campo obrigatório):
```bash
curl -X POST "https://api.toplojas.com.br/clientes/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{}'
```
# Solução de Problemas
Reunimos aqui os problemas mais comuns na integração com a API e como resolvê-los. Sempre que uma requisição falhar, verifique também o elemento **`Mensagem`** retornado no corpo da resposta — ele indica a causa do erro.
{% content-ref url="/pages/-MOhyjfrwXCAIeHNbhHn" %}
[Erros](/funcionamento/erros)
{% endcontent-ref %}
## 🔒 Recebo 401 (não autorizado) mesmo com o token
Verifique, nesta ordem:
* **Esqueceu o `Bearer`?** O header `Authorization` deve começar com `Bearer` (com espaço), seguido do token. Exemplo: `Authorization: Bearer AAAA...`.
* **O token foi atualizado?** Ao clicar em **Atualizar Token** no painel, o token anterior é **invalidado**. Se sua integração parou de funcionar de repente, gere e configure o token atual.
Detalhes em [Conectando na API](/funcionamento/conectando-na-api) e [Geração de Token](/funcionamento/geracao-de-token).
## 🧩 Recebo 400 (campos essenciais faltando)
O código **400** indica que faltam informações essenciais na requisição. As causas mais comuns:
* Faltou o header **`Loja`** (o Identificador da Loja).
* Faltou o header **`Authorization`** (o Token).
* O módulo ou a ação não foram informados corretamente.
## 🔗 Recebo 404 (módulo ou ação não localizados)
* **Confira a barra final (`/`) da rota.** Todas as rotas da API terminam com `/` — por exemplo, `/pedidos/` e `/pedidos/1000/`. Uma rota sem a barra final pode não ser localizada.
* Confira se o nome do módulo/ação está escrito corretamente.
## 🈶 Acentos chegam quebrados
Toda troca de dados deve ser feita em **JSON com charset UTF-8**. Se caracteres acentuados aparecem corrompidos, garanta que sua requisição envia e lê os dados em UTF-8.
Veja os padrões esperados em [Considerações Gerais](/funcionamento/consideracoes-gerais).
## 📄 Recebo 422 (falha de validação)
O código **422** indica que os dados enviados não passaram na validação. O corpo da resposta traz o campo **`Mensagem`** com o motivo (por exemplo, um campo obrigatório não preenchido). Ajuste os dados conforme a indicação e reenvie.
## 🔔 Meu webhook não está recebendo notificações
* **Firewall:** garanta que o IP `177.136.232.132` está na lista branca do seu servidor.
* **UserAgent:** garanta que o UserAgent `Toplojas (+https://www.toplojas.com.br/)` não está sendo bloqueado.
* **Resposta:** seu endpoint precisa responder **HTTP 200**; qualquer outro código é interpretado como falha. O sistema tenta reenviar até **3 vezes**, a cada **10 minutos**.
* **SSL:** a URL do webhook precisa ter **SSL** e aceitar **POST** em **JSON**.
Detalhes completos em [Webhook](/funcionamento/webhook).
{% hint style="info" %}
Não encontrou seu problema aqui? Consulte as [Perguntas Frequentes (FAQ)](/funcionamento/faq) ou teste a requisição no [Simulador Online](/funcionamento/utilizando-o-simulador-online) para comparar com o esperado.
{% endhint %}
# Paginação
Em casos de paginação, é retornado **dois objetos**:
* **Dados:** Que contém a *listagem* dos dados buscados
* **Paginacao:** Que contém informações da *quantidade de páginas disponíveis* e quantos registros por página estão sendo exibidos
No objeto "**Paginacao**" temos:
* PaginaAtual
* QtdPaginas
* QtdRegistros
### Exemplo:
```json
{
"Dados": [
{ "Codigo": 41360, "Status": "A", "Nome": "Livros 2", "Pai": { "Codigo": 0 } },
{ "Codigo": 41361, "Status": "A", "Nome": "Amamentação", "Pai": { "Codigo": 0 } },
{ "Codigo": 41362, "Status": "A", "Nome": "Conjunto Infantil", "Pai": { "Codigo": 0 } }
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 6
}
}
```
Para alterar a página desejada, envie na **Query** a página desejada, no elemento "**Pagina**", exemplo:
Você pode também alterar a quantidade de registros por página, para isto, envie na **Query** a quantidade desejada no elemento "**QtdPorPagina**", exemplo:
Combinando os dois parâmetros na **Query**, o exemplo abaixo busca a **página 2** com **50 registros** por página:
```
?Pagina=2&QtdPorPagina=50
```
{% hint style="info" %}
O **máximo** por página **permitido** é de **100 registros**
{% endhint %}
# Utilizando o Simulador Online
Através de nosso simulador você pode **testar todos os métodos**:
{% embed url="" %}
## Configurando o Token e o Identificador da Loja
Antes de começar a utilizar, clique em "**Authorize**":
Preencha seu "**Token**" e o "**Identificador da Loja**" conforme os dados obtidos em:
{% content-ref url="/pages/-MObk4z78qnd5Uc2I2C4" %}
[Geração de Token](/funcionamento/geracao-de-token)
{% endcontent-ref %}
### Exemplo:
Após, clique nos **DOIS** botões de "**Authorize**":
Após isto, o botão 
irá sumir e será exibido o botão 
, exemplo:
Pronto! Feche a janela através do "**X**" no canto direito superior e comece a testar a API.
## Chamando o endpoint "/status/"
Para testarmos o funcionamento, iremos acionar o endpoint "*/status/*", para isto, localize a seção "**Outros -> Status**" e clique na linha azul:
Após isto, o sistema irá exibir quais os parâmetros que podem ser enviados, o que pode (ou deve) ser enviado no body da requisição e qual o retorno esperado.
Clique em "**Try it Out**" e após em "**Execute**":
Após isto, será exibido alguns detalhes muito importantes:
* A requisição CURL completa
* A url completa chamada
* A resposta do servidor
### Exemplo:
Observe também, que existe uma área "**Responses**", onde o sistema mostra cada campo que pode ser retornado e exemplos de retorno.
## Quais dados devem ser enviados
Ao abrir um dos métodos, o sistema exibe um exemplo dos campos que devem ser enviados no body da requisição.
Em alguns métodos, existem mais exemplos para o mesmo método, para isto, clique no campo ao lado de "**Examples**":
Junto ao exemplo de dados, temos a referência de cada campo que pode ser enviado e seus requisitos, para isto, clique em "**Schema**":
Neste espaço é exibido todos os campos, exemplo de como devem ser preenchidos, quais são obrigatórios e os tipos de informações esperados.
## Quais dados devem ser recebidos
Ao abrir um dos métodos, no espaço "**Responses**", o sistema exibe um exemplo dos dados que são retornados:
Em alguns métodos, existem mais exemplos para o mesmo método, para isto, clique no campo ao lado de "**Examples**":
Junto ao exemplo de dados, temos a referência de cada campo que pode ser retornado e seus requisitos, para isto, clique em "**Schema**":
Neste espaço é exibido todos os campos que podem ser retornados, os valores possíveis e os tipos de dados que serão retornados.
# Configurando o Postman
O **Postman** é um dos programas mais usados para testar APIs. Como nossa API é publicada em **OpenAPI 3.0**, você pode **importar** todos os métodos de uma vez a partir do nosso arquivo `doc.json` — sem precisar cadastrar cada requisição manualmente.
{% hint style="info" %}
Não tem o Postman? Baixe gratuitamente em .
{% endhint %}
## 📥 Importando o doc.json
Você pode importar diretamente pela **URL** do contrato (recomendado, pois sempre traz a versão mais recente) ou baixando o arquivo.
### Opção 1 — Importar pela URL
1. No Postman, clique em **Import** (canto superior esquerdo).
2. Selecione a aba **Link**.
3. Cole a URL do nosso `doc.json`:
```
https://api.toplojas.com.br/doc/doc.json
```
4. Clique em **Continue** e depois em **Import**.
### Opção 2 — Importar o arquivo baixado
1. Baixe o arquivo `doc.json`:
{% embed url="" %}
2. No Postman, clique em **Import** e arraste o arquivo (ou selecione-o pelo botão **files**).
Ao final, o Postman cria uma **Collection** chamada **Toplojas**, já com todos os endpoints organizados por módulo (Pedidos, Produtos, Clientes, etc.).
## 🔑 Configurando a autenticação
Todas as requisições precisam dos headers de autenticação. Em vez de preenchê-los em cada requisição, configure-os **uma única vez** na Collection usando variáveis.
Se ainda não tem o **Token** e o **Identificador da Loja**, obtenha-os aqui:
{% content-ref url="/pages/-MObk4z78qnd5Uc2I2C4" %}
[Geração de Token](/funcionamento/geracao-de-token)
{% endcontent-ref %}
### Passo 1 — Crie as variáveis na Collection
1. Clique com o botão direito na Collection **Toplojas** e escolha **Edit**.
2. Abra a aba **Variables** e cadastre:
| Variável | Valor inicial (Initial value) |
| -------- | ----------------------------- |
| `token` | *o Token da sua loja* |
| `loja` | *o Identificador da sua loja* |
3. Salve.
### Passo 2 — Configure os headers na Collection
1. Ainda na edição da Collection, abra a aba **Authorization** e escolha o tipo **Bearer Token**.
2. No campo **Token**, informe:
```
{{token}}
```
3. Abra a aba **Headers** e adicione o header da loja:
| Key | Value |
| ------ | ---------- |
| `Loja` | `{{loja}}` |
4. Salve.
{% hint style="info" %}
Como cada requisição **herda** a autenticação da Collection, todos os endpoints já ficam prontos para uso. Se preferir, você também pode informar o `Authorization: Bearer {{token}}` e o `Loja: {{loja}}` diretamente na aba **Headers** de cada requisição.
{% endhint %}
## ▶️ Testando
Abra qualquer requisição da Collection — por exemplo, **Outros → /status/** — e clique em **Send**. Se a autenticação estiver correta, você receberá uma resposta de sucesso da API.
Pronto! A partir daqui você pode explorar e testar todos os métodos da API pelo Postman.
{% hint style="info" %}
Prefere testar sem instalar nada? Use o nosso simulador online:
{% endhint %}
# Webhook
Através deste recurso, você pode **receber uma notificação** quando um evento específico ocorrer.
Como, por exemplo, *quando um pedido tiver seu pagamento confirmado*.
## Eventos Disponíveis 🗓️
Para obter os eventos disponíveis, faça uma **GET** para:
```
/webhook/eventos/
```
Será retornado todos os eventos disponíveis e quais informações serão enviadas:
```json
[
{
"Codigo": "Pedidos_Concluidos",
"Titulo": "Pedidos que foram marcados como Concluído/Entregue"
}
]
```
Nestes eventos, o que iremos utilizar para configurar o webhook é o "**Codigo**", que representa o evento que será enviado.
No caso de Pedidos com *pagamento confirmado*, o evento é:
```
Pedidos_Pagos
```
## Configurando Webhook ⚙️
Para criar um webhook, faça um **POST** para:
```
/webhook/
```
Neste POST, precisamos enviar:
Evento
O Código do Evento, que obtemos na API "**/webhook/eventos/**".
É possível configurar **um webhook para cada evento**.
Endpoint
A Url para qual será enviado as notificações.
**Exemplo:**
**
Esta Url deve possuir alguns requisitos:
* Possuir **SSL**
* Permitir receber **POST** no formato **JSON**
* Retornar um HttpCode **200**
**Exemplo de POST:**
```json
{
"Evento": "Pedidos_Pagos",
"Endpoint": "https://webhook.site/34bde777-5d3d-4591-b0c8-36a1e729753b"
}
```
O retorno será o **código do webhook**, para permitir **editar** o endpoint e **remover** o webhook:
```json
{
"Codigo": 6
}
```
## Dados Enviados 📤
Quando um webhook é disparado, nosso sistema envia os **dados do evento** e o **endpoint** de onde pode ser obtido detalhes do evento:
```json
{
"Evento": "Pedidos_Criados",
"Data": "2025-07-22 10:21:15",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Nestes dados, temos:
Evento
Evento que está sendo disparado
Data
**Data** em que o evento de notificação foi **iniciado**, caso ocorram mais tentativas, esta data não muda
Recurso
Endpoint que pode ser utilizado para obter os **dados completos** deste registro.
Caso não seja retornado um "**Recurso**", indica que a informação *não esta disponível nos Endpoints* de nossa API, neste caso, todos os dados serão retornados em "**Dados**".
Tentativa
**Tentativa** desta requisição (*limitando-se a 3 tentativas*)
Dados
**Dados relacionados** a esta notificação.
No caso de Pedidos, será sempre enviado o **Código do Pedido**, que pode ser utilizado nos endpoints **/pedidos/**.
**Exemplo de cada evento:**
Pedidos_Concluidos
Pedidos que já foram **Entregues** e **Concluídos**:
```json
{
"Evento": "Pedidos_Concluidos",
"Data": "2025-07-22 12:09:55",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Pedidos_Enviados
Pedidos **Enviados** ou **Reenviados**:
```json
{
"Evento": "Pedidos_Enviados",
"Data": "2025-07-22 12:09:50",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Pedidos_Pagos
Pedidos com **Pagamento Confirmado** (*Mesmo não estando Capturado - Para os casos de Captura Manual*):
```json
{
"Evento": "Pedidos_Pagos",
"Data": "2025-07-22 12:09:36",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Pedidos_Criados
Momento **inicial do Pedido**, quando o pedido é efetivado (*é normalmente o momento em que o cliente está realizando o pagamento*):
```json
{
"Evento": "Pedidos_Criados",
"Data": "2025-07-22 12:09:23",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Pedidos_Todos
Evento enviado quando qualquer alteração de status for realizada em um pedido:
```json
{
"Evento": "Pedidos_Todos",
"Data": "2025-07-22 12:09:36",
"Recurso": "/pedidos/999999/",
"Tentativa": 1,
"Dados": {
"CodigoPedido": 999999
}
}
```
Clientes_Cadastro
Cadastro de novos Clientes:
```json
{
"Evento": "Clientes_Cadastro",
"Data": "2025-07-22 12:08:33",
"Recurso": "/clientes/999999/",
"Tentativa": 1,
"Dados": {
"CodigoCliente": 999999
}
}
```
Clientes_Edicao
Edição do cliente realizado pelo próprio cliente e/ou pela administração:
```json
{
"Evento": "Clientes_Edicao",
"Data": "2025-07-22 12:09:02",
"Recurso": "/clientes/999999/",
"Tentativa": 1,
"Dados": {
"CodigoCliente": 999999
}
}
```
## Tentativas 🔁
O sistema irá tentar enviar a notificação por **3 vezes**, em intervalos de **10 minutos**.
No envio dos dados, será enviado o elemento "**Tentativa**" indicando qual a tentativa está sendo enviada neste instante.
## Sucesso ✅
O sistema irá entender que a notificação foi enviada com **sucesso**, quando o webhook nos retornar um **HTTPCODE ****200**.
**Qualquer outra HTTPCODE** será entendido como **FALHA**.
## Validando Webhook 🕵️♂️
Para garantir que o Webhook foi enviado pelo Toplojas, enviamos no **Header** da requisição a **API KEY** da Loja:
```json
{
"x-webhook-api-key": "XXXXXXXXXXXXXXXX"
}
```
Desta forma, você pode **validar a notificação,** garantindo que ela ***não veio** de fontes não confiáveis*.
## Firewall 🧱
Caso você tenha um firewall em seu servidor, é importante garantir que o **IP de nosso servidor** de notificações **esteja em sua lista branca**.
Para isto, adicione o **IP abaixo** em sua lista branca:
```
177.136.232.132
```
É importante, também, garantir que o **UserAgent**, utilizado nas requisições de nosso servidor, n**ão seja bloqueado** pelo seu servidor.
Para isto, garanta que o UserAgent abaixo **não seja bloqueado**:
```
Toplojas (+https://www.toplojas.com.br/)
```
## Mais Detalhes 🔍
Para obter **detalhes completos** dos endpoints relacionados ao módulo de Webhook, **clique no link** abaixo e consulte nossa documentação completa:
{% embed url="" %}
# Perguntas Frequentes (FAQ)
Respostas rápidas para as dúvidas mais comuns na integração com a API.
Onde consigo o Token e o Identificador da Loja?
No painel da loja, em **Sistema → Configurações Gerais → API de Acesso Externo → Atualizar Token**. Veja o passo a passo em [Geração de Token](/funcionamento/geracao-de-token).
Ao gerar um novo Token, o antigo continua funcionando?
Não. Ao clicar em **Atualizar Token**, o token anterior é **invalidado**. Atualize o token nas suas integrações após gerar um novo.
Qual é o limite de requisições?
**30 requisições por minuto**. Veja os demais padrões em [Considerações Gerais](/funcionamento/consideracoes-gerais).
Qual o máximo de registros por página?
**100 registros** por página. Use os parâmetros `Pagina` e `QtdPorPagina` na Query. Veja [Paginação](/funcionamento/paginacao).
Posso criar ou editar clientes pela API?
Não. O módulo de **Clientes é somente leitura** (consulta). O cadastro de clientes é feito pela própria loja/checkout. Veja [Clientes](/clientes/visao-geral).
Como altero o estoque de um produto?
O estoque **não** é alterado pelo endpoint de edição de produto. Use o endpoint específico de estoque. Veja [Gerenciar Estoque](/produtos/gerenciar-estoque).
Como recebo pedidos sem ficar consultando a API o tempo todo?
Use o recurso de **Webhook**: você é notificado automaticamente quando um pedido é criado, pago, enviado ou concluído. Veja [Webhook](/funcionamento/webhook).
Como sei qual código de status usar ao alterar um pedido?
Consulte a lista de status em `GET /informacoes/status/`. Veja [Informações](/informacoes/informacoes) e [Alterar Status](/pedidos/alterar-status).
Em qual formato devo enviar datas e valores?
Data no formato `Ano-Mês-Dia`; data e hora no formato `Ano-Mês-Dia Hora:Minuto:Segundo`; decimais com `.` (ponto). Veja [Considerações Gerais](/funcionamento/consideracoes-gerais).
Minha requisição falhou. Por onde começo?
Confira o elemento `Mensagem` no corpo da resposta e consulte a [Solução de Problemas](/funcionamento/solucao-de-problemas).
{% hint style="info" %}
Não encontrou sua dúvida? Consulte o [Glossário](/funcionamento/glossario) ou a documentação de referência no [Simulador Online](/funcionamento/utilizando-o-simulador-online).
{% endhint %}
# Glossário
Definições dos principais termos usados nesta documentação e nos dados da API.
| Termo | Significado |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Endpoint** | Endereço (URL) de um recurso da API. O endpoint base é `https://api.toplojas.com.br/`. |
| **Token** | Credencial de acesso da loja, enviada no header `Authorization: Bearer [Token]`. |
| **Identificador da Loja** | Código que identifica sua loja, enviado no header `Loja`. |
| **`x-webhook-api-key`** | Chave enviada no header das notificações de Webhook, usada para você validar que a notificação veio do Toplojas. |
| **Status `A` / `D`** | Situação de um registro: `A` (Ativado) ou `D` (Desativado). |
| **`CodigoImportacao`** | Código do produto em um sistema terceiro, usado para localizar/relacionar produtos importados. |
| **Marketplace** | Canal externo pelo qual um pedido pode ter sido feito; indicado nos detalhes e filtros de pedidos. |
| **Variação** | Combinação específica de um produto (ex.: Cor "Azul"), com seu próprio SKU, preço e estoque. |
| **SKU** | Código único de identificação de um produto ou variação (Stock Keeping Unit). |
| **Departamento** | Categoria que organiza os produtos. Pode ter um **Pai** (`CodigoPai`), formando uma hierarquia. |
| **`CodigoPai`** | Código do departamento "pai" de um subdepartamento. Ausente ou `0` indica um departamento raiz. |
| **Forma de Entrega** | Modalidade de envio ativa na loja (ex.: PAC, Sedex), com `Codigo` e `Nome`. |
| **Forma de Pagamento** | Meio de pagamento ativo na loja, com `Codigo`, `Grupo`, `Gateway` e `Nome`. |
| **Gateway** | Serviço que processa um pagamento (ex.: Cielo), associado a uma forma de pagamento. |
| **Paginação** | Divisão de listagens em páginas, controlada por `Pagina` e `QtdPorPagina` (máx. 100). |
| **Webhook** | Notificação automática enviada pela API quando um evento ocorre (ex.: pedido pago). |
| **NF-e** | Nota Fiscal Eletrônica; seus dados podem ser informados em um pedido. |
{% hint style="info" %}
A referência completa de cada campo de cada endpoint está no [Simulador Online](/funcionamento/utilizando-o-simulador-online).
{% endhint %}
# Versões
Histórico de mudanças da API Toplojas. A versão **mais recente** aparece sempre no **topo**.
Cada cartão indica o **tipo** da mudança, a **autora** (👤) e a **data de implantação** (📅):
| Badge | Significado |
| --------------- | ----------------------------------------------------- |
| ✨ **Novidade** | Recurso novo da API (ex.: Webhook, Assistente IA). |
| 🔧 **Melhoria** | Ajuste, campo ou filtro em um recurso que já existia. |
***
{% hint style="info" %}
### 1.5.0 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *17/08/2026*
* Implantado o elemento **FormasEntregaCalculadas** na listagem e nos detalhes dos pedidos — retorna **todas as formas de entrega calculadas no carrinho** no momento da compra (com **valor do frete** e **prazo de entrega** de cada opção), ordenadas do **menor para o maior valor**, e não somente a forma escolhida pelo cliente. Opções de **frete grátis** também são retornadas, com `Valor` igual a **0**.
{% endhint %}
{% content-ref url="/pages/MmarhErcLW6IbvhC3bZX" %}
[Detalhes do Pedido](/pedidos/detalhes-do-pedido)
{% endcontent-ref %}
***
{% hint style="success" %}
### 1.4.0 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *10/08/2026*
* Implantado o módulo **Pedidos Abandonados** — consulte os **carrinhos abandonados** da loja (compras iniciadas e não finalizadas) para ações de **recuperação de carrinho**, com listagem filtrável e detalhes do carrinho.
{% endhint %}
{% content-ref url="/pages/m8r1LXnapkHg7Xsqqk2Q" %}
[Visão Geral](/pedidos-abandonados/visao-geral)
{% endcontent-ref %}
***
{% hint style="success" %}
### 1.3.0 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *15/07/2026*
* Lançado o **Assistente IA (MCP)** — conecte a sua loja ao **Claude** ou ao **ChatGPT** e **consulte e altere** seus dados conversando em linguagem natural (cadastra e edita produtos, estoque, pedidos, cupons, webhooks e mais, sempre com confirmação). A única ação não permitida é **excluir** registros.
{% endhint %}
{% content-ref url="/pages/79HYKHeJB2eE2YGxwf2y" %}
[Instalação e Ativação](/assistente-ia-mcp/instalacao-e-ativacao)
{% endcontent-ref %}
***
{% hint style="info" %}
### 1.2.0 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *25/06/2026*
* Implantado filtro de **nota fiscal** na listagem de pedidos
* Implantados dados da **nota fiscal** nos detalhes dos pedidos
{% endhint %}
***
{% hint style="success" %}
### 1.1.0 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *27/07/2025*
* Implantado recurso de **Webhook**
* Implantado **prazo de entrega** nos detalhes dos produtos
{% endhint %}
***
{% hint style="info" %}
### 1.0.10 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *22/05/2025*
* Implantado **link do produto** nos detalhes dos produtos
{% endhint %}
***
{% hint style="info" %}
### 1.0.9 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *21/05/2025*
* Implantados **filtros** na listagem de produtos
{% endhint %}
***
{% hint style="info" %}
### 1.0.8 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *11/11/2024*
* Implantado **link de rastreamento** no endpoint de pedidos
{% endhint %}
***
{% hint style="success" %}
### 1.0.7 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *29/08/2024*
* Implantada integração com o módulo **Correios PPN (Pré-Postagem Nacional)**
{% endhint %}
***
{% hint style="info" %}
### 1.0.6 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *29/06/2024*
* Implantado campo **DataNascimento** no endpoint `/clientes/[codigo]/`
{% endhint %}
***
{% hint style="success" %}
### 1.0.5 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *02/08/2023*
* Implantado cadastro de **Atributos** nos produtos
{% endhint %}
***
{% hint style="info" %}
### 1.0.4 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *30/05/2023*
* Adicionado campo **CodigoImportacao** no cadastro de produtos
{% endhint %}
***
{% hint style="info" %}
### 1.0.3 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *06/04/2023*
* Adicionado campo **Marketplace** entre os filtros de pedidos, permitindo buscar pedidos por Marketplace
* Adicionado elemento **Marketplace** nos detalhes dos pedidos, indicando se o pedido foi feito através de um Marketplace e qual o Marketplace
{% endhint %}
***
{% hint style="info" %}
### 1.0.2 · 🔧 Melhoria
👤 *Paloma Macetko* · 📅 *21/03/2023*
* Adicionado campo **Departamentos** no gerenciamento de produtos, permitindo indicar N departamentos onde os produtos serão exibidos
{% endhint %}
***
{% hint style="success" %}
### 1.0.1 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *19/08/2022*
* Implantado recurso para gerenciar o **Newsletter**
{% endhint %}
***
{% hint style="success" %}
### 1.0.0 · ✨ Novidade
👤 *Paloma Macetko* · 📅 *23/12/2020*
* Versão nova da API lançada
{% endhint %}
# Visão Geral
O **Assistente IA** deixa você **conversar com a sua loja em português normal** — sem saber nada de API, sem colar token. Você conecta o assistente uma vez ao Claude, ao ChatGPT ou a outro aplicativo de IA compatível e passa a perguntar em linguagem natural: *"quantos produtos eu tenho?"*, *"me mostre os últimos pedidos"*, *"quais clientes compraram acima de R$ 1.000?"*.
Nos bastidores, ele usa o **MCP (Model Context Protocol)** — um padrão aberto que permite diferentes IAs se conectarem à sua loja com segurança. Por isso funciona em vários aplicativos de IA, não só em um.
## Como funciona
Você pergunta em linguagem natural → o assistente entende, busca os dados **da sua loja** e responde. Você pode encadear perguntas que ele continua o raciocínio:
1. *"Liste os produtos da minha loja."*
2. *"E desses, quais estão sem estoque?"*
3. *"Monte uma tabela com SKU e preço."*
Pense nele como um **analista de dados da sua loja**: ele lê, cruza informações de vários lugares (produtos, pedidos, clientes...) e explica — tudo a partir de uma conversa.
{% hint style="info" %}
**O assistente consulta *****e***** altera a sua loja.**
Além de **consultar, cruzar e explicar** os dados, o assistente também **executa ações** por você — sempre pedindo **confirmação** antes de mudar algo.
**O que dá para consultar:** listar, buscar, comparar, resumir e analisar produtos, pedidos, clientes, cupons, departamentos, newsletter, webhooks e informações da loja.
**O que dá para alterar:** editar produtos e ajustar estoque; mudar o status de um pedido (inclusive cancelar), informar código de rastreio e nota fiscal; cadastrar e editar departamentos, cupons, inscritos da newsletter e webhooks.
**A única coisa que ele *****não***** faz é excluir.** Nenhum registro é apagado pelo assistente — cadastros e edições sim, exclusões não.
{% endhint %}
## O que você precisa
* Ser o dono da loja e ter o **login de acesso** (Loja, Login e Senha do painel).
* Um aplicativo de IA compatível com conectores MCP (ex.: Claude ou ChatGPT). Alguns exigem plano pago — veja os detalhes na página de instalação.
Pronto para conectar?
{% content-ref url="/pages/79HYKHeJB2eE2YGxwf2y" %}
[Instalação e Ativação](/assistente-ia-mcp/instalacao-e-ativacao)
{% endcontent-ref %}
# Instalação e Ativação
Conectar sua loja ao assistente leva poucos minutos. O processo é parecido em todos os aplicativos: você adiciona um **conector** informando a URL abaixo e autoriza com o login da sua loja.
## A URL do conector
```
https://admin-mcp.toplojas.com.br
```
{% hint style="warning" %}
Conectores personalizados costumam exigir um **plano pago** do aplicativo de IA (por exemplo, planos pagos do Claude ou do ChatGPT). No plano gratuito, a opção de adicionar um conector pode não aparecer.
{% endhint %}
## Escolha o seu aplicativo
O passo a passo muda um pouco em cada aplicativo. Siga o guia do que você usa:
{% content-ref url="/pages/GwOvoOEuxyOAVBIoyIXj" %}
[Conectar no Claude](/assistente-ia-mcp/instalacao-e-ativacao/conectar-no-claude)
{% endcontent-ref %}
{% content-ref url="/pages/l19rZNX8YZvEow5fNdL8" %}
[Conectar no ChatGPT](/assistente-ia-mcp/instalacao-e-ativacao/conectar-no-chatgpt)
{% endcontent-ref %}
As seções abaixo (**login na loja**, **confirmação** e **solução de problemas**) valem para qualquer aplicativo.
## Fazendo login na sua loja
Em todos os aplicativos, a autorização acontece numa tela da **própria Toplojas**, aberta no seu navegador. Primeiro você informa **Loja, Login e Senha**:
Depois, confira as **permissões concedidas** — de **leitura** (`GET`) e de **escrita** (`POST` para cadastrar, `PUT` para editar). O assistente **não recebe permissão de exclusão**. Clique em **Autorizar**:
Alguns pontos importantes:
* Você usa as **mesmas credenciais do painel** (Loja, Login e Senha).
* **Nenhum token é colado manualmente** — o login cuida disso para você.
* O assistente **nunca vê a sua senha**: ela fica só no navegador, na tela da Toplojas.
* O acesso é **limitado a essa loja** e pode ser **revogado a qualquer momento**.
## Confirme que funcionou
Depois de conectar, faça um teste simples. Peça ao assistente:
> *"Liste os produtos da minha loja."*
Se ele retornar dados reais da sua loja, está tudo certo. 🎉
Você também pode pedir análises mais elaboradas — o assistente busca os dados e monta a resposta. Por exemplo:
> *"Crie um gráfico que mostra os estados com mais vendas em 2025."*
No Claude:
O mesmo pedido no ChatGPT:
Veja mais ideias em [O que pedir](/assistente-ia-mcp/o-que-pedir).
## Solução de problemas
| Situação | O que fazer |
| ---------------------------------------------------- | ------------------------------------------------------------------------------- |
| Não aparece a opção de adicionar conector | Verifique se o seu plano do aplicativo de IA permite conectores personalizados. |
| Erro ao fazer login | Confira **Loja, Login e Senha** — são os mesmos do painel da sua loja. |
| O assistente pede para reconectar depois de um tempo | A sessão expirou. Basta reconectar/autorizar novamente com o seu login. |
Agora que está conectado, veja tudo o que dá para pedir:
{% content-ref url="/pages/BErSemrf6qLdSlbTJ2ln" %}
[O que pedir](/assistente-ia-mcp/o-que-pedir)
{% endcontent-ref %}
# Conectar no Claude
Este é o passo a passo para conectar sua loja ao **Claude** (Desktop e Web). Antes de começar, tenha em mãos a [URL do conector](/assistente-ia-mcp/instalacao-e-ativacao#a-url-do-conector) e o login da sua loja.
1. Abra o Claude e acesse **Configurações → Conectores** (em algumas versões, **Personalizar → Conectores**). Clique em **Adicionar** e depois em **Adicionar conector personalizado**.
2. Preencha:
* **Nome:** um nome de sua escolha (ex.: `Minha Loja Toplojas`).
* **URL:** `https://admin-mcp.toplojas.com.br`
Clique em **Adicionar**.
3. O conector aparece como ainda não conectado. Clique em **Vincular** para iniciar a autorização.
4. O Claude abre o navegador na tela de **login da Toplojas**. Informe **Loja, Login e Senha**, clique em **Entrar** e, na tela seguinte, confira as permissões e clique em **Autorizar** (veja em [Fazendo login na sua loja](/assistente-ia-mcp/instalacao-e-ativacao#fazendo-login-na-sua-loja)).
5. Pronto! Para usar numa conversa, clique no botão **+** ao lado do campo de mensagem, escolha **Conectores** e ative o conector da sua loja.
{% hint style="info" %}
**Primeira vez que o assistente usa uma ferramenta.** O Claude pede sua **aprovação** antes de acessar os dados da loja. Você pode clicar em **Sempre permitir** (para não precisar confirmar de novo neste conector) ou **Negar**.
{% endhint %}
Conectado? Confira se está tudo certo em [Confirme que funcionou](/assistente-ia-mcp/instalacao-e-ativacao#confirme-que-funcionou).
# Conectar no ChatGPT
Este é o passo a passo para conectar sua loja ao **ChatGPT**. Antes de começar, tenha em mãos a [URL do conector](/assistente-ia-mcp/instalacao-e-ativacao#a-url-do-conector) e o login da sua loja.
No ChatGPT, os conectores ficam em **Aplicativos** e adicionar um conector personalizado exige ativar antes o **Modo desenvolvedor**.
1. Clique na sua foto de perfil → **Configurações** → **Aplicativos** e, em **Preferências do app**, abra **Configurações avançadas**.
2. Habilite o **Modo desenvolvedor**.
3. Clique em **Criar aplicativo**.
4. Preencha o formulário **Novo app**:
* **Nome:** um nome de sua escolha (ex.: `Minha Loja Toplojas`).
* **Conexão:** deixe em **URL do servidor** e informe `https://admin-mcp.toplojas.com.br`.
* **Autenticação:** **OAuth**.
* Marque **"Entendi e quero continuar"** e clique em **Criar**.
5. Clique em **Entrar com …** para autenticar. O ChatGPT abre a tela de **login da Toplojas** no navegador: informe **Loja, Login e Senha**, clique em **Entrar** e depois em **Autorizar** (veja em [Fazendo login na sua loja](/assistente-ia-mcp/instalacao-e-ativacao#fazendo-login-na-sua-loja)).
6. Pronto! Para usar numa conversa, clique no botão **+** ao lado do campo de mensagem e selecione a sua loja na lista.
{% hint style="info" %}
A interface do ChatGPT muda conforme o seu plano e a versão do aplicativo — os conectores podem aparecer como **Aplicativos** ou **Conectores**. O essencial é o mesmo: ativar o **Modo desenvolvedor**, criar um app com autenticação **OAuth** e colar a URL acima.
{% endhint %}
Conectado? Confira se está tudo certo em [Confirme que funcionou](/assistente-ia-mcp/instalacao-e-ativacao#confirme-que-funcionou).
# O que pedir
Depois de conectar, você conversa em **português normal** — o assistente escolhe o que buscar, lê os dados da sua loja e responde. Abaixo, exemplos do que você pode pedir em cada assunto.
## 📦 Produtos
* "Liste os produtos da minha loja."
* "Quantos produtos eu tenho cadastrados no total?"
* "Me mostre os 10 produtos mais caros."
* "Qual o preço e o estoque do produto com SKU RE152?"
* "Procure produtos com 'vestido' no nome."
* "Detalhe o produto de código 1283555 — quero ver descrição, preço e fotos."
* "Quais produtos estão desativados?"
* "Tem algum produto com estoque zerado?"
* "Compare o preço normal e o promocional dos meus produtos e me diga onde o desconto é maior."
* "Quais produtos pertencem ao departamento 'Cafeteiras'?"
* "Me dá a lista de SKUs e preços em formato de tabela."
## 🛒 Pedidos
* "Mostre meus últimos pedidos."
* "Quantos pedidos eu tenho no total?"
* "Liste os pedidos com pagamento confirmado."
* "Quais pedidos foram feitos entre 01/06 e 30/06?"
* "Me mostre os detalhes do pedido 3667015."
* "Qual o valor total, o frete e a forma de pagamento do pedido 3667015?"
* "Quais itens tem no pedido 3667015 e em que quantidade?"
* "Tem algum pedido que veio de marketplace?"
* "Liste os pedidos do cliente de código 123."
* "Qual o ticket médio dos meus últimos pedidos?"
* "Quais pedidos ainda estão aguardando pagamento?"
## 👥 Clientes
* "Liste meus clientes."
* "Quantos clientes eu tenho cadastrados?"
* "Procure o cliente pelo e-mail ."
* "Detalhe o cliente de código 456 — quero nome, telefone e endereço."
* "Quais clientes são pessoa jurídica (CNPJ)?"
* "Me mostre os clientes com telefone e e-mail para eu montar uma lista de contato."
## 🎟️ Cupons de desconto
* "Tenho algum cupom de desconto ativo?"
* "Liste todos os meus cupons."
* "Procure o cupom pela palavra 'natal'."
* "Detalhe o cupom de código 789."
## 🗂️ Departamentos (categorias)
* "Quais departamentos/categorias existem na minha loja?"
* "Me mostre a estrutura de categorias (quais são subcategorias de quais)."
* "Quantos departamentos eu tenho?"
* "Detalhe o departamento de código 44086."
## 📧 Newsletter
* "Quantas pessoas estão inscritas na minha newsletter?"
* "Liste os e-mails inscritos na newsletter."
* "Procure na newsletter pelo e-mail ."
## 🔔 Webhooks
* "Quais webhooks estão configurados na minha loja?"
* "Que tipos de eventos eu posso assinar por webhook?"
* "Detalhe o webhook de código 5."
## ⚙️ Informações da loja
* "Quais formas de entrega estão ativas na minha loja?"
* "Quais formas de pagamento eu aceito?"
* "Quais são os status de pedido possíveis na plataforma?"
## ✍️ Ações que alteram a loja
Além de consultar, o assistente também **executa mudanças** — sempre pedindo **confirmação** antes. Exemplos:
* "Altere o estoque do SKU RE152 para 100 unidades."
* "Edite o produto 1283555 e desative ele."
* "Mude o status do pedido 3667015 para 'Enviado' e avise o cliente por e-mail."
* "No pedido 3667015, informe o código de rastreamento AB47859625SA."
* "Informe a nota fiscal do pedido 3667015 (número, série, data e chave)."
* "Cancele o pedido 4974307."
* "Crie um cupom DIAMULHER com 10% de desconto, válido este mês."
* "Cadastre um departamento chamado 'Promoções'."
* "Inscreva o e-mail na newsletter."
* "Crie um webhook que avise a URL X quando um pedido for pago."
{% hint style="warning" %}
**O assistente não exclui nada.** Cadastrar e editar, sim; **apagar** registros, não. E toda ação que muda a loja — principalmente as **irreversíveis**, como cancelar um pedido — passa por uma **confirmação** antes de ser executada.
{% endhint %}
Veja essas ações passo a passo em [Exemplos de uso](/assistente-ia-mcp/exemplos-de-uso).
## 🧠 Perguntas que combinam várias fontes
O assistente pode cruzar dados de mais de um lugar numa única resposta:
* "Faça um resumo da minha loja: quantos produtos, pedidos e clientes eu tenho."
* "Quais foram meus pedidos pagos e qual o faturamento total deles?"
* "Liste os produtos mais caros e me diga quais deles já foram vendidos em algum pedido."
* "Monte um relatório: total de pedidos por status."
* "Quais clientes fizeram pedidos acima de R$ 1.000?"
* "Analise meus produtos e sugira quais estão sem estoque e precisam de reposição."
* "Do total de inscritos na newsletter, quantos também são clientes cadastrados?"
{% hint style="info" %}
Como as listagens são paginadas, para números totais o assistente pode precisar percorrer várias páginas. Se você tem muitos registros, peça um **período** ou um **filtro** (status, data, busca) para respostas mais rápidas.
{% endhint %}
## 💡 Dicas para perguntas melhores
* **Seja específico com códigos e filtros:** "detalhe o pedido 3667015" é mais direto que "me mostre um pedido".
* **Peça o formato que preferir:** "em tabela", "só os nomes e preços", "resumido".
* **Encadeie:** faça uma pergunta ampla e depois refine — "e desses, quais são de marketplace?".
* **Datas:** use `DD/MM` ou `AAAA-MM-DD`; para pedidos, dá para filtrar por período.
* **Grandes volumes:** filtrar por status, data ou busca deixa a resposta mais rápida e precisa.
{% hint style="info" %}
Lembre-se: o assistente **não exclui** nada. Ele consulta, cadastra e edita — mas **apagar** registros (produtos, cupons, webhooks, clientes...) não é permitido. Para isso, use o painel da loja.
{% endhint %}
# Exemplos de uso
Veja o assistente em ação — de uma consulta simples a ações que **alteram a loja**. Em cada exemplo você vê o que foi **pedido** (em português normal) e o que o assistente **fez**.
{% hint style="info" %}
As telas abaixo são do **Claude**, mas o comportamento é o mesmo em qualquer aplicativo de IA compatível (ChatGPT etc.). O que muda é só a aparência da conversa.
{% endhint %}
## 🛒 Consultar pedidos
Uma pergunta de leitura: o assistente busca os pedidos, monta a tabela e ainda **interpreta** o resultado (aqui, percebeu que nenhum pagamento foi confirmado).
> *"Liste os últimos pedidos."*
## 🚫 Cancelar um pedido (com confirmação)
Ações **irreversíveis** nunca são executadas às cegas. Ao pedir o cancelamento, o assistente **avisa que é irreversível** e pergunta **qual status de cancelamento** usar antes de agir:
> *"Cancele o pedido 4974307."*
{% hint style="warning" %}
Repare no aviso *"o cancelamento é irreversível"* e na pergunta de confirmação. Ações que mudam a loja passam por essa etapa antes de serem executadas.
{% endhint %}
## 🚚 Informar código de rastreio
O assistente confirma um detalhe (enviar ou não e-mail ao cliente) e grava o rastreio no pedido:
> *"No pedido 4647667, informe o código de rastreamento AB47859625SA."*
## 📦 Ajustar estoque
Você diz a quantidade final desejada e o assistente ajusta — inclusive de uma **variação** específica do produto:
> *"Altere o estoque para 100 unidades."*
## 🎟️ Cadastrar um cupom de desconto
Quando faltam informações (validade, limite de usos), o assistente **pergunta** antes de cadastrar — e depois resume o que foi criado:
> *"Crie um cupom de desconto com o código DIAMULHER que concede 10% de desconto em toda a loja e que é válido este mês."*
## Quer mais ideias?
Veja a lista completa de perguntas e ações em [O que pedir](/assistente-ia-mcp/o-que-pedir).
{% content-ref url="/pages/BErSemrf6qLdSlbTJ2ln" %}
[O que pedir](/assistente-ia-mcp/o-que-pedir)
{% endcontent-ref %}
# Visão Geral
Através da API de **Pedidos** você pode consultar e gerenciar todo o ciclo de vida de um pedido: listar, ver os detalhes, alterar o status, informar o código de rastreio e informar a nota fiscal.
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🔄 Fluxo típico
Um fluxo comum de integração de pedidos costuma seguir esta ordem:
1. **Listar** os pedidos, filtrando por data, status ou cliente.
2. **Consultar os detalhes** de um pedido específico (itens, cliente, valores).
3. **Alterar o status** conforme o andamento (ex.: separação, enviado).
4. **Informar o código de rastreio** quando o pedido for despachado.
5. **Informar a nota fiscal** emitida para o pedido.
## 🧭 Endpoints de Pedidos
| Ação | Método | Rota |
| --------------------------- | ------ | --------------------------------------------- |
| Listar e filtrar pedidos | GET | `/pedidos/` |
| Detalhes de um pedido | GET | `/pedidos/{Codigo}/` |
| Alterar status | PUT | `/pedidos/{Codigo}/alterar-status/` |
| Informar código de rastreio | PUT | `/pedidos/{Codigo}/informar-codigo-rastreio/` |
| Informar nota fiscal | PUT | `/pedidos/{Codigo}/informar-nota-fiscal/` |
## 🛒 E os carrinhos abandonados?
A listagem de `/pedidos/` retorna apenas as compras **finalizadas** pelo cliente. Os carrinhos que ficaram pelo caminho têm um módulo próprio:
{% content-ref url="/pages/m8r1LXnapkHg7Xsqqk2Q" %}
[Visão Geral](/pedidos-abandonados/visao-geral)
{% endcontent-ref %}
## 🔔 Recebendo pedidos automaticamente
Em vez de consultar a listagem repetidamente, você pode ser **notificado** quando um pedido é criado, pago, enviado ou concluído, usando o recurso de Webhook:
{% content-ref url="/pages/rbiZGRer0EGAGyswrCCw" %}
[Webhook](/funcionamento/webhook)
{% endcontent-ref %}
# Listar e Filtrar Pedidos
Retorna a **listagem de pedidos** da loja, com suporte a filtros e paginação.
```
GET /pedidos/
```
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| ------------------- | ------- | --------------------------------------------------- |
| `DataDe` | data | Retorna pedidos a partir desta data (`Ano-Mês-Dia`) |
| `DataAte` | data | Retorna pedidos até esta data (`Ano-Mês-Dia`) |
| `CodigoReferencial` | inteiro | Filtra pelo código referencial do pedido |
| `CodigoStatus` | inteiro | Filtra por um status específico |
| `CodigoCliente` | inteiro | Retorna apenas os pedidos de um cliente |
| `StatusIndicacao` | texto | Filtra por indicação de status (ex.: `Pago`) |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
## 📥 Exemplo de requisição
Buscando pedidos **pagos** entre duas datas, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/pedidos/?DataDe=2025-01-01&DataAte=2025-01-31&StatusIndicacao=Pago&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": 1000,
"CodigoReferencial": 1,
"Data": "2020-12-01 12:00:00",
"Loja": "cmacetkoteste",
"Cliente": {
"Codigo": 1,
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"Contato": "",
"DataNascimento": "1989-11-14",
"Sexo": "M",
"CPF_CNPJ": "000.000.000-00",
"RG_IE": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 33224477",
"Telefone02": "(47) 55447788",
"Telefone03": "(47) 55886699",
"Empresa": "",
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"Endereco": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"ValorTotal": 253.79,
"ValorProdutos": 220,
"ValorFrete": 33.79,
"ValorDescontosCupom": 0,
"ValorDescontosPagamento": 0,
"FormaPagamento": {
"Codigo": 78509,
"Nome": "PagSeguro"
},
"FormaEntrega": {
"Codigo": 27154,
"Nome": "PAC"
},
"NumeroParcelas": 1,
"Status": {
"Codigo": 25,
"Nome": "Pedido com Pagamento Confirmado, Aguardando Captura",
"Indicacao": "Pago"
},
"FormasEntregaCalculadas": [
{
"Codigo": 27150,
"Nome": "Frete Grátis",
"Valor": 0,
"PrazoEntrega": {
"QtdDias": 12,
"Texto": "Entrega em até 12 dias úteis após a postagem"
}
},
{
"Codigo": 27154,
"Nome": "PAC",
"Valor": 33.79,
"PrazoEntrega": {
"QtdDias": 9,
"Texto": "Entrega em até 9 dias úteis após a postagem"
}
},
{
"Codigo": 27155,
"Nome": "SEDEX",
"Valor": 52.4,
"PrazoEntrega": {
"QtdDias": 4,
"Texto": "Entrega em até 4 dias úteis após a postagem"
}
}
],
"Itens": [
{
"Codigo": 1187876,
"SKU": "3017",
"Nome": "Teste1",
"Quantidade": 2,
"ValorUnitario": 110,
"ValorTotal": 220
}
]
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 4
}
}
```
{% hint style="info" %}
Cada pedido da listagem também traz o elemento **`FormasEntregaCalculadas`**, com todas as opções de frete calculadas no carrinho (ordenadas do menor para o maior valor, incluindo **frete grátis** com `Valor` igual a **0**). Veja os detalhes desse elemento em:
{% endhint %}
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Pedido
Retorna os **dados completos** de um pedido específico, identificado pelo seu **Código**.
```
GET /pedidos/{Codigo}/
```
O `{Codigo}` é o código do pedido, obtido na [listagem de pedidos](/pedidos/listar-pedidos).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/pedidos/1000/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 O que é retornado
Os detalhes de um pedido incluem, entre outros:
| Grupo | Conteúdo |
| ------------ | --------------------------------------------------------------- |
| **Cliente** | Nome/Razão Social, documento, contato e endereço |
| **Endereço** | Endereço de entrega do pedido |
| **Itens** | Produtos do pedido (SKU, nome, quantidade e valores) |
| **Valores** | Total, produtos, frete e descontos |
| **Formas** | Forma de pagamento e forma de entrega |
| **Status** | Código, nome e indicação do status atual |
| **Fretes** | Formas de entrega **calculadas** no carrinho (opções e valores) |
Exemplo completo de um pedido retornado:
```json
{
"Codigo": 1000,
"CodigoReferencial": 1,
"Data": "2020-12-01 12:00:00",
"Loja": "cmacetkoteste",
"Cliente": {
"Codigo": 1,
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"Contato": "",
"DataNascimento": "1989-11-14",
"Sexo": "M",
"CPF_CNPJ": "000.000.000-00",
"RG_IE": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 33224477",
"Telefone02": "(47) 55447788",
"Telefone03": "(47) 55886699",
"Empresa": "",
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"Endereco": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"ValorTotal": 253.79,
"ValorProdutos": 220,
"ValorFrete": 33.79,
"ValorDescontosCupom": 0,
"ValorDescontosPagamento": 0,
"FormaPagamento": {
"Codigo": 78509,
"Nome": "PagSeguro"
},
"FormaEntrega": {
"Codigo": 27154,
"Nome": "PAC"
},
"NumeroParcelas": 1,
"Status": {
"Codigo": 25,
"Nome": "Pedido com Pagamento Confirmado, Aguardando Captura",
"Indicacao": "Pago"
},
"PrazoEntrega": {
"QtdDias": 9,
"Texto": "Entrega em até 9 dias úteis após a postagem"
},
"FormasEntregaCalculadas": [
{
"Codigo": 27150,
"Nome": "Frete Grátis",
"Valor": 0,
"PrazoEntrega": {
"QtdDias": 12,
"Texto": "Entrega em até 12 dias úteis após a postagem"
}
},
{
"Codigo": 27154,
"Nome": "PAC",
"Valor": 33.79,
"PrazoEntrega": {
"QtdDias": 9,
"Texto": "Entrega em até 9 dias úteis após a postagem"
}
},
{
"Codigo": 27155,
"Nome": "SEDEX",
"Valor": 52.4,
"PrazoEntrega": {
"QtdDias": 4,
"Texto": "Entrega em até 4 dias úteis após a postagem"
}
}
],
"Itens": [
{
"Codigo": 1187876,
"SKU": "3017",
"Nome": "Teste1",
"Quantidade": 2,
"ValorUnitario": 110,
"ValorTotal": 220
}
]
}
```
## 🚚 Formas de entrega calculadas
O elemento **`FormasEntregaCalculadas`** traz **todas as opções de frete que foram calculadas no carrinho** no momento da compra — e não apenas a que o cliente escolheu.
As opções vêm **ordenadas pelo valor do frete**, do **menor para o maior**.
| Campo | Tipo | Descrição |
| ---------------------- | ------- | ------------------------------------------------ |
| `Codigo` | inteiro | Código da forma de entrega |
| `Nome` | texto | Nome da forma de entrega apresentado no carrinho |
| `Valor` | decimal | Valor do frete calculado para esta opção |
| `PrazoEntrega.QtdDias` | inteiro | Prazo de entrega em dias úteis |
| `PrazoEntrega.Texto` | texto | Prazo em formato de texto (pode conter HTML) |
{% hint style="info" %}
Não confunda os dois elementos:
* **`FormaEntrega`** → a forma de entrega **escolhida** pelo cliente (e cobrada no pedido, em `ValorFrete`).
* **`FormasEntregaCalculadas`** → **todas** as opções que estavam **disponíveis** no carrinho, com seus respectivos valores e prazos.
Use `FormasEntregaCalculadas` para analisar, por exemplo, quanto o cliente **economizou** ao escolher uma opção mais barata, ou para comparar as cotações de frete dos seus pedidos.
{% endhint %}
{% hint style="success" %}
**Frete grátis também é retornado.** Opções de entrega gratuitas aparecem normalmente na lista, com **`Valor: 0`** — elas não são omitidas. Como a ordenação é pelo valor do frete (do menor para o maior), uma opção de frete grátis costuma ser o **primeiro item** da lista.
Portanto, para identificar frete grátis, verifique se **`Valor` é igual a `0`** — e não a ausência da opção na lista.
{% endhint %}
{% hint style="warning" %}
`FormasEntregaCalculadas` retorna uma **lista vazia** (`[]`) quando o pedido não possui cotações de frete registradas — por exemplo, em pedidos **antigos** (anteriores à implantação do recurso) ou em pedidos vindos de **Marketplace**. **Sempre trate essa possibilidade** na sua integração.
{% endhint %}
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Alterar Status
Altera o **status** de um pedido — por exemplo, marcá-lo como "Em Separação" ou "Enviado".
```
PUT /pedidos/{Codigo}/alterar-status/
```
## 1️⃣ Descubra o código do status
Cada status possui um **Código**. Para saber quais status existem na plataforma e seus códigos, consulte:
```
GET /informacoes/status/
```
A resposta lista os status disponíveis:
```json
[
{
"Codigo": 3,
"NomeStaff": "Aguardando Pagamento"
}
]
```
## 2️⃣ Envie a alteração
No corpo da requisição, envie o novo status:
| Campo | Tipo | Obrigatório | Descrição |
| --------------- | ------- | ----------- | ----------------------------------------------------- |
| `CodigoStatus` | inteiro | ✅ Sim | Código do novo status (obtido no passo anterior) |
| `IsEnviarEmail` | texto | ❌ Não | `S` para notificar o cliente por e-mail, `N` para não |
### 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/pedidos/1000/alterar-status/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"CodigoStatus": 8,
"IsEnviarEmail": "S"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **200**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Informar Código de Rastreio
Registra o **código de rastreio** de um pedido despachado, permitindo que o cliente acompanhe a entrega.
```
PUT /pedidos/{Codigo}/informar-codigo-rastreio/
```
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| -------------------- | ------- | ----------- | ----------------------------------------------------- |
| `CodigoRastramento` | texto | ✅ Sim | Código de rastreio do envio |
| `IsEnviarEmail` | texto | ✅ Sim | `S` para notificar o cliente por e-mail, `N` para não |
| `CodigoFormaEntrega` | inteiro | ❌ Não | Código da forma de entrega utilizada |
| `Tipo` | texto | ❌ Não | Tipo de envio |
| `DataPostagem` | data | ❌ Não | Data da postagem (`Ano-Mês-Dia`) |
{% hint style="warning" %}
O nome do campo é **`CodigoRastramento`** (exatamente como esperado pela API).
{% endhint %}
## 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/pedidos/1000/informar-codigo-rastreio/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"CodigoRastramento": "A1",
"CodigoFormaEntrega": 0,
"Tipo": "E",
"DataPostagem": "2020-12-01",
"IsEnviarEmail": "S"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint (incluindo os valores aceitos em `Tipo`):
{% embed url="" %}
{% endhint %}
# Informar Nota Fiscal
Registra os dados da **Nota Fiscal Eletrônica (NF-e)** emitida para um pedido.
```
PUT /pedidos/{Codigo}/informar-nota-fiscal/
```
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | ----- | ----------- | ------------------------------- |
| `NFE_Numero` | texto | ✅ Sim | Número da nota fiscal |
| `NFE_Serie` | texto | ✅ Sim | Série da nota fiscal |
| `NFE_Data` | data | ✅ Sim | Data de emissão (`Ano-Mês-Dia`) |
| `NFE_Chave` | texto | ✅ Sim | Chave de acesso da NF-e |
| `NFE_CFOP` | texto | ❌ Não | CFOP da operação |
## 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/pedidos/1000/informar-nota-fiscal/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"NFE_Numero": "4444444444",
"NFE_Serie": "3",
"NFE_Data": "2020-12-01",
"NFE_CFOP": "2222222222",
"NFE_Chave": "111111111"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Visão Geral
Através da API de **Pedidos Abandonados** você consulta os **carrinhos abandonados** da sua loja — ou seja, as compras que o cliente iniciou mas **não finalizou**.
É o mesmo conteúdo que o painel exibe em **Pedidos → Pedidos Abandonados**, agora disponível para integração.
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🛒 O que é um pedido abandonado
Quando um cliente monta o carrinho mas não conclui a compra, o registro fica na loja como **abandonado**. Se ele voltar e finalizar, o pedido passa a ser um pedido normal e **deixa de aparecer** nesta listagem.
| Situação do cliente | Onde aparece |
| ------------------------------------- | ----------------------- |
| Montou o carrinho e **não** finalizou | `/pedidos-abandonados/` |
| Finalizou a compra | `/pedidos/` |
{% hint style="warning" %}
Um mesmo código **nunca** aparece nos dois lugares ao mesmo tempo. Se você consultar `/pedidos-abandonados/{Codigo}/` de um carrinho que já foi finalizado, a API retorna **404**.
{% endhint %}
## 🧭 Endpoints de Pedidos Abandonados
| Ação | Método | Rota |
| ------------------------------------ | ------ | -------------------------------- |
| Listar e filtrar pedidos abandonados | GET | `/pedidos-abandonados/` |
| Detalhes de um pedido abandonado | GET | `/pedidos-abandonados/{Codigo}/` |
{% hint style="info" %}
Este módulo é **somente leitura**. Não há ações de criação, edição ou exclusão de carrinhos abandonados pela API.
{% endhint %}
## ⚠️ Diferenças em relação ao módulo Pedidos
O carrinho abandonado **não foi fechado**, então alguns blocos que existem em `/pedidos/` **não são retornados** aqui:
| Bloco | Retornado? | Motivo |
| ------------------------------- | ---------- | -------------------------------------------------- |
| `Cliente` | ✅ | O cliente já estava identificado |
| `EnderecoEntrega` | ✅ | Endereço informado até o momento do abandono |
| `Itens` | ✅ | Produtos que estavam no carrinho |
| `Valores.Produtos` | ✅ | Valor **estimado** (soma dos itens) |
| `FormaPagamento` | ❌ | O cliente não chegou a escolher |
| `FormaEntrega` / `PrazoEntrega` | ❌ | O cliente não chegou a escolher |
| `NumeroParcelas` | ❌ | Depende da forma de pagamento |
| `Status` | ❌ | Carrinho abandonado não percorre o fluxo de status |
| `NotaFiscal` | ❌ | Não existe nota para uma compra não concluída |
| `Marketplace` | ❌ | Não se aplica |
{% hint style="warning" %}
**O valor é estimado.** `Valores.Produtos` é a soma dos itens (`Quantidade × ValorUnitario`) e **não inclui frete**, já que não existe forma de entrega escolhida. Não use este valor como valor de venda.
{% endhint %}
## 💡 Para que usar
O uso mais comum é a **recuperação de carrinho**: identificar quem abandonou a compra e entrar em contato oferecendo um cupom, lembrete ou atendimento.
Um fluxo comum:
1. **Listar** os carrinhos abandonados do período que te interessa.
2. **Consultar os detalhes** para saber o que havia no carrinho.
3. Usar os dados de contato do `Cliente` para a ação de recuperação.
4. Reconsultar mais tarde os mesmos códigos em `/pedidos-abandonados/{Codigo}/`: quem passou a retornar **404** voltou e finalizou a compra.
{% hint style="info" %}
Guarde de sua parte os códigos já trabalhados. A API não marca quais carrinhos já receberam uma ação de recuperação — o controle de "já contatei este cliente" fica com a sua integração.
{% endhint %}
{% content-ref url="/pages/gPo4oa8dZ6wjbhQtqb2R" %}
[Listar e Filtrar Pedidos Abandonados](/pedidos-abandonados/listar-pedidos-abandonados)
{% endcontent-ref %}
{% content-ref url="/pages/yEI8qtisx6Clr6yZSqMf" %}
[Detalhes do Pedido Abandonado](/pedidos-abandonados/detalhes-do-pedido-abandonado)
{% endcontent-ref %}
# Listar e Filtrar Pedidos Abandonados
Retorna a **listagem de carrinhos abandonados** da loja, com suporte a filtros e paginação.
```
GET /pedidos-abandonados/
```
Os registros vêm ordenados do **mais recente para o mais antigo**, que é a ordem mais útil para ações de recuperação.
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| ------------------- | ------- | ------------------------------------------------------------ |
| `DataDe` | data | Retorna carrinhos a partir desta data (`Ano-Mês-Dia`) |
| `DataAte` | data | Retorna carrinhos até esta data (`Ano-Mês-Dia`) |
| `Codigo` | inteiro | Filtra pelo código interno do pedido |
| `CodigoCliente` | inteiro | Retorna apenas os carrinhos de um cliente |
| `CodigoLojaGerador` | inteiro | Filtra pela loja que gerou o pedido (para lojas com filiais) |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
## 📥 Exemplo de requisição
Buscando os carrinhos abandonados de janeiro, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/pedidos-abandonados/?DataDe=2026-01-01&DataAte=2026-01-31&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": 1234,
"CodigoReferencial": 0,
"Data": "2026-01-15 14:32:00",
"Loja": "cmacetkoteste",
"Cliente": {
"Codigo": 1,
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"Contato": "",
"DataNascimento": "1989-11-14",
"Sexo": "M",
"CPF_CNPJ": "000.000.000-00",
"RG_IE": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 33224477",
"Telefone02": "",
"Telefone03": "",
"Empresa": "",
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"EnderecoEntrega": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"Itens": [
{
"Produto": {
"Codigo": 1187876,
"SKU": "3017",
"Nome": "Teste1"
},
"Quantidade": 2,
"ValorUnitario": 110,
"ValorTotal": 220
}
],
"Valores": {
"Produtos": 220
}
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 1
}
}
```
{% hint style="warning" %}
`Valores.Produtos` é um valor **estimado** — a soma de `Quantidade × ValorUnitario` dos itens. **Não inclui frete**, pois o cliente não chegou a escolher a forma de entrega.
{% endhint %}
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Pedido Abandonado
Retorna os **detalhes de um carrinho abandonado**, incluindo o cliente, o endereço informado e os itens que estavam no carrinho.
```
GET /pedidos-abandonados/{Codigo}/
```
O `{Codigo}` é o **código interno** do pedido — o mesmo campo `Codigo` retornado na listagem.
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/pedidos-abandonados/1234/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
```json
{
"Codigo": 1234,
"CodigoReferencial": 0,
"Data": "2026-01-15 14:32:00",
"Loja": "cmacetkoteste",
"Cliente": {
"Codigo": 1,
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"Contato": "",
"DataNascimento": "1989-11-14",
"Sexo": "M",
"CPF_CNPJ": "000.000.000-00",
"RG_IE": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 33224477",
"Telefone02": "",
"Telefone03": "",
"Empresa": "",
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"EnderecoEntrega": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88355-000"
},
"Itens": [
{
"Produto": {
"Codigo": 1187876,
"SKU": "3017",
"Nome": "Teste1"
},
"Quantidade": 2,
"ValorUnitario": 110,
"ValorTotal": 220,
"Variacao": {
"Codigo": 552,
"SKU": "3017-P",
"Nome": "Tamanho: P / Cor: Azul"
}
}
],
"Valores": {
"Produtos": 220
}
}
```
{% hint style="info" %}
O bloco `Variacao` só aparece nos itens que **têm variação** selecionada (ex.: tamanho, cor). Itens sem variação não trazem este bloco.
{% endhint %}
## 🧮 Sobre o valor
`Valores.Produtos` é **estimado**: é a soma de `Quantidade × ValorUnitario` de todos os itens do carrinho.
{% hint style="warning" %}
Este valor **não inclui frete**, descontos de cupom ou descontos de forma de pagamento — nada disso foi definido, porque o cliente não concluiu a compra.
{% endhint %}
## ❌ Retornos de erro
| Código | Situação |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `422` | O `Codigo` não foi informado ("Preencha o Código") |
| `422` | O código informado não existe na loja ("Registro não Localizado") |
| `404` | O pedido existe, mas **já foi continuado** pelo cliente — ou seja, não é mais um carrinho abandonado |
{% hint style="info" %}
O retorno **404** é a forma de saber que um carrinho foi **recuperado**: o cliente voltou e finalizou a compra. A partir daí, consulte o pedido pelo módulo de Pedidos:
{% endhint %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
# Visão Geral
Através da API de **Produtos** você pode cadastrar e gerenciar todo o catálogo da loja: listar e filtrar produtos, consultar os detalhes, criar, editar, excluir e controlar o estoque (inclusive o estoque de cada variação).
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🔄 Fluxo típico
Um fluxo comum de integração de produtos costuma seguir esta ordem:
1. **Listar** os produtos, filtrando por Nome, SKU, Status ou Código de Importação.
2. **Consultar os detalhes** de um produto específico (preços, fotos, variações, atributos).
3. **Criar** novos produtos, com ou sem variações.
4. **Editar** as informações de um produto já existente.
5. **Gerenciar o estoque** do produto ou de cada variação.
6. **Excluir** um produto quando necessário.
## 🧭 Endpoints de Produtos
| Ação | Método | Rota |
| ------------------------------- | ------ | ----------------------------------------------------- |
| Listar e filtrar produtos | GET | `/produtos/` |
| Criar produto | POST | `/produtos/` |
| Detalhes de um produto | GET | `/produtos/{Codigo}/` |
| Editar produto | PUT | `/produtos/{Codigo}/` |
| Excluir produto | DELETE | `/produtos/{Codigo}/` |
| Obter estoque de um produto | GET | `/produtos/estoque/{CodigoProduto}/` |
| Alterar estoque de um produto | PUT | `/produtos/estoque/{CodigoProduto}/` |
| Obter estoque de uma variação | GET | `/produtos/estoque/{CodigoProduto}/{CodigoVariacao}/` |
| Alterar estoque de uma variação | PUT | `/produtos/estoque/{CodigoProduto}/{CodigoVariacao}/` |
{% hint style="info" %}
O **estoque não é editado** pelo endpoint de edição de produto (`PUT /produtos/{Codigo}/`). Para alterar quantidades disponíveis, use sempre os endpoints de **estoque** descritos em [Gerenciar Estoque](/produtos/gerenciar-estoque).
{% endhint %}
# Listar e Filtrar Produtos
Retorna a **listagem de produtos** da loja, com suporte a filtros e paginação.
```
GET /produtos/
```
{% hint style="info" %}
A listagem de produtos usa o wrapper **`Retorno`** (e não `Dados`, como em outros módulos), acompanhado de `Paginacao`.
{% endhint %}
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| ------------------ | ------- | ---------------------------------------------------------------- |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
| `Status` | texto | Filtra pelo status do produto: `A` (Ativado) ou `D` (Desativado) |
| `CodigoImportacao` | texto | Código importado de sistemas terceiros |
| `SKU` | texto | SKU do produto |
| `Nome` | texto | Nome do produto (o sistema também busca por nomes parciais) |
## 📥 Exemplo de requisição
Buscando produtos ativos que contenham "Teste" no nome, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/produtos/?Status=A&Nome=Teste&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta traz os produtos em `Retorno` e os dados de paginação em `Paginacao`:
```json
{
"Retorno": [
{
"Codigo": 1287407,
"DataCadastro": "2023-03-21 16:48:47",
"DataModificacao": "2023-03-21 17:01:06",
"Nome": "Teste1",
"SKU": "T1",
"GTIN": "TesteGTIN1",
"EAN": "TesteEAN1",
"CodigoImportacao": "IMP100",
"LinkSlug": "https://www.teste.com.br/conjuntos/teste1/",
"Tags": "Teste1 Teste1 Teste1 Teste1 Teste1",
"Peso": 12.34,
"Dim_Comprimento": 4.323,
"Dim_Largura": 2.323,
"Dim_Altura": 1.548,
"PrecoPromocional": 120.2,
"PrecoNormal": 234.56,
"PrecoCusto": 100.96,
"Status": "A",
"Fabricante": "TesteFabricante1",
"Marca": "TesteMarca1",
"DepartamentoPrincipal": "Livros > Aventura",
"Departamentos": [
"Livros",
"Livros > Aventura",
"Livros > Romance",
"Escolar",
"Escolar > Livros"
],
"Descricao": {
"Titulo": "Descrição",
"Texto": "TesteDescricao1"
},
"Estoque": {
"Tipo": "P",
"Disponivel": 125
},
"Variacoes": {
"CampoAIs": false,
"CampoA": "",
"CampoBIs": false,
"CampoB": "",
"Listagem": []
},
"Fotos": [
{
"Foto": "Produtos/1287407/Fotos/G_990ec2a14c2bc8010e03aec0cff058.png",
"IsCapa": true
}
],
"Relacionados": [],
"Atributos": [
{
"Grupo": "Composicao",
"Item": "Exemplo de Composicao 1"
},
{
"Grupo": "Genero",
"Item": "Exemplo de Genero 1"
},
{
"Grupo": "Mataria Prima",
"Item": "Exemplo de Mataria Prima 1"
}
]
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 1
}
}
```
{% hint style="info" %}
Produtos **com variação** trazem o campo `Estoque.Tipo` como `V` e a lista de variações em `Variacoes.Listagem`. Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Produto
Retorna os **dados completos** de um produto específico, identificado pelo seu **Código**.
```
GET /produtos/{Codigo}/
```
O `{Codigo}` é o código do produto, obtido na [listagem de produtos](/produtos/listar-produtos).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/produtos/1287407/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 O que é retornado
Os detalhes de um produto incluem, entre outros:
| Grupo | Conteúdo |
| ----------------- | --------------------------------------------------------- |
| **Identificação** | Nome, SKU, GTIN, EAN, Código de Importação |
| **Preços** | Preço normal, promocional e de custo |
| **Dimensões** | Peso, altura, largura e comprimento |
| **Departamentos** | Departamento principal e demais departamentos |
| **Estoque** | Tipo (`P` produto / `V` variação) e quantidade disponível |
| **Variações** | Campos e listagem de variações (quando houver) |
| **Fotos** | Imagens do produto (com indicação da capa) |
| **Atributos** | Grupos e itens de atributos (composição, gênero etc.) |
Exemplo de um produto **sem variação** retornado:
```json
{
"Nome": "Teste1",
"SKU": "T1",
"Status": "A",
"PrecoNormal": 234.56,
"PrecoPromocional": 120.2,
"PrecoCusto": 100.96,
"Tags": "Teste1 Teste1 Teste1 Teste1 Teste1",
"Fabricante": "TesteFabricante1",
"Marca": "TesteMarca1",
"Dim_Altura": 1.548,
"Dim_Largura": 2.323,
"Dim_Comprimento": 4.323,
"Peso": 12.34,
"DepartamentoPrincipal": "Livros > Aventura",
"Departamentos": [
"Livros",
"Livros > Aventura",
"Livros > Romance",
"Escolar",
"Escolar > Livros"
],
"GTIN": "TesteGTIN1",
"EAN": "TesteEAN1",
"CodigoImportacao": "IMP100",
"LinkSlug": "https://www.teste.com.br/conjuntos/teste1/",
"Estoque": {
"Tipo": "P",
"Disponivel": 125
},
"Descricao": {
"Texto": "TesteDescricao1"
},
"Relacionados": [
1188323,
1187878,
1187877
],
"Fotos": [
{
"Foto": "data:image/png;base64,XXXXXXX",
"IsCapa": true
}
],
"Atributos": [
{
"Grupo": "Composicao",
"Item": "Exemplo de Composicao 1"
},
{
"Grupo": "Genero",
"Item": "Exemplo de Genero 1"
},
{
"Grupo": "Mataria Prima",
"Item": "Exemplo de Mataria Prima 1"
}
]
}
```
Quando o produto **tem variação**, o `Estoque.Tipo` vem como `V` e as variações são listadas em `Variacoes.Listagem`, cada uma com seu próprio SKU, GTIN, EAN, preço e estoque:
```json
{
"Nome": "Teste1",
"SKU": "T1",
"Status": "A",
"Estoque": {
"Tipo": "V"
},
"Variacoes": {
"CampoAIs": true,
"CampoA": "Cor",
"CampoBIs": false,
"CampoB": "",
"Listagem": [
{
"CampoA": "Azul",
"CampoB": "",
"SKU": "Azul_SKU",
"GTIN": "Azul_GTIN",
"EAN": "Azul_EAN",
"PrecoTipo": "N",
"PrecoValor": 0,
"PesoTipo": "N",
"PesoValor": 0,
"Estoque": {
"Disponivel": 100
}
},
{
"CampoA": "Preto",
"CampoB": "",
"SKU": "Preto_SKU",
"GTIN": "Preto_GTIN",
"EAN": "Preto_EAN",
"PrecoTipo": "F",
"PrecoValor": 250.26,
"PesoTipo": "F",
"PesoValor": 2.32,
"Estoque": {
"Disponivel": 200
}
}
]
}
}
```
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Criar Produto
Cadastra um **novo produto** na loja. É possível criar produtos simples (sem variação) ou com variações (ex.: Cor, Tamanho), incluindo fotos e atributos.
```
POST /produtos/
```
{% hint style="info" %}
As **fotos** são enviadas no formato **Base64**, no padrão `data:image/png;base64,...`. A foto com `"IsCapa": true` é a imagem principal do produto.
{% endhint %}
## 🧩 Blocos principais do corpo
| Bloco | Descrição |
| --------------- | ------------------------------------------------------------------------------------- |
| Dados básicos | `Nome`, `SKU`, `Status`, preços, dimensões, `Fabricante`, `Marca`, `GTIN`, `EAN` etc. |
| `Departamentos` | Lista de departamentos; `DepartamentoPrincipal` indica o principal |
| `Estoque` | `Tipo`: `P` (produto simples, com `Disponivel`) ou `V` (controlado por variação) |
| `Variacoes` | Definição das variações (`CampoA`/`CampoB`) e a `Listagem` de cada combinação |
| `Fotos` | Imagens em Base64 (`data:image/png;base64,...`), com indicação da capa |
| `Atributos` | Grupos e itens de atributos do produto |
| `Relacionados` | Códigos de produtos relacionados |
## 📥 Exemplo de requisição (produto com variação)
Este é o exemplo **completo**, com variações, atributos e fotos:
```bash
curl -X POST "https://api.toplojas.com.br/produtos/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Nome": "Teste1",
"SKU": "T1",
"Status": "A",
"PrecoNormal": 234.56,
"PrecoPromocional": 120.2,
"PrecoCusto": 100.96,
"Tags": "Teste1 Teste1 Teste1 Teste1 Teste1",
"Fabricante": "TesteFabricante1",
"Marca": "TesteMarca1",
"Dim_Altura": 1.548,
"Dim_Largura": 2.323,
"Dim_Comprimento": 4.323,
"Peso": 12.34,
"DepartamentoPrincipal": "Livros > Aventura",
"Departamentos": [
"Livros",
"Livros > Aventura",
"Escolar",
"Escolar > Livros"
],
"GTIN": "TesteGTIN1",
"EAN": "TesteEAN1",
"CodigoImportacao": "IMP100",
"Estoque": {
"Tipo": "V"
},
"Descricao": {
"Texto": "TesteDescricao1"
},
"Relacionados": [
1188323,
1187878,
1187877
],
"Fotos": [
{
"Foto": "data:image/png;base64,XXXXXXXXXX",
"IsCapa": true
}
],
"Variacoes": {
"CampoAIs": true,
"CampoA": "Cor",
"CampoBIs": false,
"CampoB": "",
"Listagem": [
{
"CampoA": "Azul",
"CampoB": "",
"SKU": "Azul_SKU",
"GTIN": "Azul_GTIN",
"EAN": "Azul_EAN",
"PrecoTipo": "N",
"PrecoValor": 0,
"PesoTipo": "N",
"PesoValor": 0,
"Estoque": {
"Disponivel": 100
}
},
{
"CampoA": "Preto",
"CampoB": "",
"SKU": "Preto_SKU",
"GTIN": "Preto_GTIN",
"EAN": "Preto_EAN",
"PrecoTipo": "F",
"PrecoValor": 250.26,
"PesoTipo": "F",
"PesoValor": 2.32,
"Estoque": {
"Disponivel": 200
}
},
{
"CampoA": "Branco",
"CampoB": "",
"SKU": "Branco_SKU",
"GTIN": "Branco_GTIN",
"EAN": "Branco_EAN",
"PrecoTipo": "A",
"PrecoValor": 50.25,
"PesoTipo": "S",
"PesoValor": 0.852,
"Estoque": {
"Disponivel": 300
}
}
]
},
"Atributos": [
{
"Grupo": "Composicao",
"Item": "Exemplo de Composicao 1"
},
{
"Grupo": "Genero",
"Item": "Exemplo de Genero 1"
},
{
"Grupo": "Mataria Prima",
"Item": "Exemplo de Mataria Prima 1"
}
]
}'
```
## 🧾 Produto sem variação
Para um produto simples, use `Estoque.Tipo` como `P` e informe a quantidade em `Estoque.Disponivel`, sem o bloco `Variacoes`:
```json
{
"Nome": "Teste1",
"SKU": "T1",
"Status": "A",
"PrecoNormal": 234.56,
"PrecoPromocional": 120.2,
"PrecoCusto": 100.96,
"Estoque": {
"Tipo": "P",
"Disponivel": 125
},
"Descricao": {
"Texto": "TesteDescricao1"
},
"Fotos": [
{
"Foto": "data:image/png;base64,XXXXXXX",
"IsCapa": true
}
],
"Atributos": [
{
"Grupo": "Composicao",
"Item": "Exemplo de Composicao 1"
}
]
}
```
Em caso de sucesso, a API retorna o HTTP Code **201**.
{% hint style="info" %}
Referência completa deste endpoint (com todos os campos e schemas):
{% embed url="" %}
{% endhint %}
# Editar Produto
Atualiza as informações de um **produto já existente**, identificado pelo seu **Código**.
```
PUT /produtos/{Codigo}/
```
O `{Codigo}` é o código do produto, obtido na [listagem de produtos](/produtos/listar-produtos).
{% hint style="info" %}
**O estoque NÃO é editado por este endpoint.** Na edição de produtos não é possível alterar o estoque — para isso, utilize os endpoints de estoque descritos em [Gerenciar Estoque](/produtos/gerenciar-estoque).
{% endhint %}
## 🧩 Sobre o corpo
O corpo segue a mesma estrutura da [criação de produto](/produtos/criar-produto), porém com estas diferenças:
* Não envie quantidades de estoque — elas são ignoradas na edição. Em produtos com variação, informe apenas `Estoque.Tipo` como `V` (sem `Disponivel`), e nas variações **não** inclua o bloco `Estoque`.
* Nas variações já existentes, informe o `Codigo` da variação para atualizá-la.
## 📥 Exemplo de requisição (produto com variação)
```bash
curl -X PUT "https://api.toplojas.com.br/produtos/1287408/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Nome": "Teste2 Editado 2",
"SKU": "T2",
"Status": "A",
"PrecoNormal": 234.56,
"PrecoPromocional": 120.2,
"PrecoCusto": 100.96,
"Tags": "Teste1 Teste1 Teste1 Teste1 Teste1",
"Fabricante": "TesteFabricante1",
"Marca": "TesteMarca1",
"Dim_Altura": 1.548,
"Dim_Largura": 2.323,
"Dim_Comprimento": 4.323,
"Peso": 12.34,
"DepartamentoPrincipal": "Livros > Aventura",
"Departamentos": [
"Livros",
"Livros > Aventura",
"Escolar",
"Escolar > Livros"
],
"GTIN": "TesteGTIN1",
"EAN": "TesteEAN1",
"CodigoImportacao": "IMP100",
"Estoque": {
"Tipo": "V"
},
"Descricao": {
"Texto": "TesteDescricao1"
},
"Relacionados": [
1188323,
1187878,
1187877
],
"Fotos": [
{
"Foto": "data:image/png;base64,XXXXXXXXXX",
"IsCapa": true
}
],
"Variacoes": {
"CampoAIs": true,
"CampoA": "Cor",
"CampoBIs": false,
"CampoB": "",
"Listagem": [
{
"Codigo": 6880215,
"CampoA": "Azul",
"CampoB": "",
"SKU": "Azul_SKU",
"GTIN": "Azul_GTIN",
"EAN": "Azul_EAN",
"PrecoTipo": "N",
"PrecoValor": 0,
"PesoTipo": "N",
"PesoValor": 0
},
{
"Codigo": 6880216,
"CampoA": "Preto",
"CampoB": "",
"SKU": "Preto_SKU",
"GTIN": "Preto_GTIN",
"EAN": "Preto_EAN",
"PrecoTipo": "F",
"PrecoValor": 250.26,
"PesoTipo": "F",
"PesoValor": 2.32
},
{
"Codigo": 6880217,
"CampoA": "Branco",
"CampoB": "",
"SKU": "Branco_SKU",
"GTIN": "Branco_GTIN",
"EAN": "Branco_EAN",
"PrecoTipo": "A",
"PrecoValor": 50.25,
"PesoTipo": "S",
"PesoValor": 0.852
}
]
},
"Atributos": [
{
"Grupo": "Composicao",
"Item": "Exemplo de Composicao 1"
},
{
"Grupo": "Genero",
"Item": "Exemplo de Genero 1"
},
{
"Grupo": "Mataria Prima",
"Item": "Exemplo de Mataria Prima 1"
}
]
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Excluir Produto
Remove **definitivamente** um produto da loja, identificado pelo seu **Código**.
```
DELETE /produtos/{Codigo}/
```
O `{Codigo}` é o código do produto, obtido na [listagem de produtos](/produtos/listar-produtos).
{% hint style="info" %}
A exclusão é permanente. Confirme o `{Codigo}` antes de enviar a requisição.
{% endhint %}
## 📥 Exemplo de requisição
```bash
curl -X DELETE "https://api.toplojas.com.br/produtos/1287407/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Gerenciar Estoque
Consulta e altera o **estoque disponível** de um produto. Estes endpoints são a **única** forma de alterar quantidades — a edição de produto (`PUT /produtos/{Codigo}/`) **não** modifica o estoque.
```
GET /produtos/estoque/{CodigoProduto}/
PUT /produtos/estoque/{CodigoProduto}/
```
Para produtos **com variação**, o estoque é controlado por variação, usando as rotas com `{CodigoVariacao}`:
```
GET /produtos/estoque/{CodigoProduto}/{CodigoVariacao}/
PUT /produtos/estoque/{CodigoProduto}/{CodigoVariacao}/
```
Onde `{CodigoProduto}` é o código do produto e `{CodigoVariacao}` é o código da variação (obtido nos [detalhes do produto](/produtos/detalhes-do-produto)).
## 📤 Obter o estoque de um produto
```bash
curl -X GET "https://api.toplojas.com.br/produtos/estoque/1287407/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Resposta:
```json
{
"Disponivel": "222"
}
```
## ✏️ Alterar o estoque de um produto
Envie a nova quantidade disponível no corpo da requisição:
| Campo | Tipo | Obrigatório | Descrição |
| ------------ | ------- | ----------- | -------------------------- |
| `Disponivel` | inteiro | ✅ Sim | Nova quantidade em estoque |
```bash
curl -X PUT "https://api.toplojas.com.br/produtos/estoque/1287407/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Disponivel": 333
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
## 🎨 Estoque de uma variação
Para produtos com variação, informe também o `{CodigoVariacao}`.
Obter o estoque da variação:
```bash
curl -X GET "https://api.toplojas.com.br/produtos/estoque/1287408/6880215/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Resposta:
```json
{
"Disponivel": "222"
}
```
Alterar o estoque da variação:
```bash
curl -X PUT "https://api.toplojas.com.br/produtos/estoque/1287408/6880215/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Disponivel": 333
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa destes endpoints:
{% embed url="" %}
{% endhint %}
# Visão Geral
Através da API de **Departamentos** você pode consultar e gerenciar as categorias (departamentos) da sua loja: listar, ver os detalhes, criar, editar e excluir. Os departamentos podem ser organizados em hierarquia, ou seja, um departamento pode ter um departamento **"Pai"**.
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🔄 Fluxo típico
Um fluxo comum de integração de departamentos costuma seguir esta ordem:
1. **Listar** os departamentos existentes, filtrando por status quando necessário.
2. **Criar** um novo departamento (raiz ou filho de outro departamento).
3. **Consultar os detalhes** de um departamento específico.
4. **Editar** o nome ou o status de um departamento.
5. **Excluir** um departamento que não é mais utilizado.
## 🧭 Endpoints de Departamentos
| Ação | Método | Rota |
| ------------------------------ | ------ | -------------------------- |
| Listar e filtrar departamentos | GET | `/departamentos/` |
| Criar departamento | POST | `/departamentos/` |
| Detalhes de um departamento | GET | `/departamentos/{Codigo}/` |
| Editar departamento | PUT | `/departamentos/{Codigo}/` |
| Excluir departamento | DELETE | `/departamentos/{Codigo}/` |
## 🌳 Departamentos e hierarquia
Cada departamento possui um campo **`Pai`**, que identifica o departamento ao qual ele pertence:
* Quando **`Pai.Codigo` é `0`**, o departamento é **raiz** (não possui pai).
* Quando **`Pai.Codigo`** aponta para outro departamento, ele é um **subdepartamento** (filho) daquele departamento.
Ao **criar** um departamento, use o campo `CodigoPai` para definir essa relação.
# Listar Departamentos
Retorna a **listagem de departamentos** da loja, com suporte a filtro por status e paginação.
```
GET /departamentos/
```
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| -------------- | ------- | ----------------------------------------------------- |
| `Status` | texto | Filtra pelo status: `A` (Ativado) ou `D` (Desativado) |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
## 📥 Exemplo de requisição
Buscando departamentos **ativos**, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/departamentos/?Status=A&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": 41360,
"Status": "A",
"Nome": "Livros 2",
"Pai": {
"Codigo": 0,
"Nome": ""
}
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 6
}
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| ------------ | ------- | --------------------------------------------------------- |
| `Codigo` | inteiro | Código do departamento |
| `Status` | texto | Status do departamento: `A` (Ativado) ou `D` (Desativado) |
| `Nome` | texto | Nome do departamento |
| `Pai.Codigo` | inteiro | Código do departamento pai (`0` = departamento raiz) |
| `Pai.Nome` | texto | Nome do departamento pai (vazio quando não há pai) |
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Departamento
Retorna os **dados completos** de um departamento específico, identificado pelo seu **Código**.
```
GET /departamentos/{Codigo}/
```
O `{Codigo}` é o código do departamento, obtido na [listagem de departamentos](/departamentos/listar-departamentos).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/departamentos/41360/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
```json
{
"Codigo": 41360,
"Status": "A",
"Nome": "Livros 2",
"Pai": {
"Codigo": 0,
"Nome": ""
}
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| ------------ | ------- | --------------------------------------------------------- |
| `Codigo` | inteiro | Código do departamento |
| `Status` | texto | Status do departamento: `A` (Ativado) ou `D` (Desativado) |
| `Nome` | texto | Nome do departamento |
| `Pai.Codigo` | inteiro | Código do departamento pai (`0` = departamento raiz) |
| `Pai.Nome` | texto | Nome do departamento pai (vazio quando não há pai) |
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Criar Departamento
Cria um **novo departamento** na loja. Ele pode ser um departamento **raiz** ou um **subdepartamento** (filho de outro departamento).
```
POST /departamentos/
```
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| ----------- | ------- | ----------- | --------------------------------------------------------- |
| `Nome` | texto | ✅ Sim | Nome do departamento |
| `Status` | texto | ✅ Sim | Status do departamento: `A` (Ativado) ou `D` (Desativado) |
| `CodigoPai` | inteiro | ❌ Não | Código do departamento **"Pai"** deste departamento |
{% hint style="info" %}
**Departamento raiz x subdepartamento**
Se você informar `CodigoPai` com o valor **`0`** — ou **não enviar** o campo `CodigoPai` — o departamento será criado como **raiz** (sem pai).
Para criar um **subdepartamento**, informe em `CodigoPai` o `Codigo` de um departamento já existente.
{% endhint %}
## 📥 Exemplo de requisição
Criando um departamento raiz chamado **Livros**:
```bash
curl -X POST "https://api.toplojas.com.br/departamentos/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Nome": "Livros",
"Status": "A",
"CodigoPai": 0
}'
```
Em caso de sucesso, a API retorna o HTTP Code **201**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Editar Departamento
Atualiza o **nome** e o **status** de um departamento existente, identificado pelo seu **Código**.
```
PUT /departamentos/{Codigo}/
```
O `{Codigo}` é o código do departamento, obtido na [listagem de departamentos](/departamentos/listar-departamentos).
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| -------- | ----- | ----------- | --------------------------------------------------------- |
| `Nome` | texto | ✅ Sim | Nome do departamento |
| `Status` | texto | ✅ Sim | Status do departamento: `A` (Ativado) ou `D` (Desativado) |
## 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/departamentos/41360/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Nome": "Livros 22222",
"Status": "A"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Excluir Departamento
Remove um departamento da loja, identificado pelo seu **Código**.
```
DELETE /departamentos/{Codigo}/
```
O `{Codigo}` é o código do departamento, obtido na [listagem de departamentos](/departamentos/listar-departamentos).
## 📥 Exemplo de requisição
```bash
curl -X DELETE "https://api.toplojas.com.br/departamentos/41360/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Em caso de sucesso, a API retorna o HTTP Code **200**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Visão Geral
Através da API de **Clientes** você pode **consultar** os clientes cadastrados na sua loja: listar (com busca e paginação) e ver os detalhes de um cliente específico.
{% hint style="info" %}
O módulo de Clientes é **somente leitura (consulta)**. O cadastro dos clientes é feito pela própria loja, no checkout/site — a API apenas oferece a **consulta** desses dados. Não existem endpoints para criar, editar ou excluir clientes.
{% endhint %}
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🧭 Endpoints de Clientes
| Ação | Método | Rota |
| ------------------------ | ------ | --------------------- |
| Listar e buscar clientes | GET | `/clientes/` |
| Detalhes de um cliente | GET | `/clientes/{Codigo}/` |
## 🔔 Acompanhando novos clientes
Em vez de consultar a listagem repetidamente, você pode ser **notificado** quando um cliente é cadastrado ou editado, usando o recurso de Webhook (eventos `Clientes_Cadastro` e `Clientes_Edicao`):
{% content-ref url="/pages/rbiZGRer0EGAGyswrCCw" %}
[Webhook](/funcionamento/webhook)
{% endcontent-ref %}
# Listar Clientes
Retorna a **listagem de clientes** da loja, com suporte a busca e paginação.
```
GET /clientes/
```
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| -------------- | ------- | ----------------------------------------------------------------- |
| `ChaveBusca` | texto | Pesquisa por **Nome**, **CPF**, **CNPJ** ou **E-mail** do cliente |
| `Status` | texto | Situação do cadastro: `A` (Ativado) ou `D` (Desativado) |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
{% hint style="info" %}
O filtro `ChaveBusca` é o mais prático para localizar um cliente: basta informar parte do nome, o CPF, o CNPJ ou o e-mail e a API retorna os clientes correspondentes.
{% endhint %}
## 📥 Exemplo de requisição
Buscando clientes pelo nome, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/clientes/?ChaveBusca=Paloma&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": "679695",
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"CPF_CNPJ": "999.999.99-99",
"RG_IE": "",
"DataNascimento": "2024-01-01",
"ObsStaff": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 11111111",
"Telefone03": "(47) 22222222",
"Telefone02": "(47) 33333333",
"Endereco": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "Centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88350-000"
}
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 1
}
}
```
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Cliente
Retorna os **dados completos** de um cliente específico, identificado pelo seu **Código**.
```
GET /clientes/{Codigo}/
```
O `{Codigo}` é o código do cliente, obtido na [listagem de clientes](/clientes/listar-clientes).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/clientes/679695/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 O que é retornado
Os detalhes de um cliente incluem, entre outros:
| Campo | Descrição |
| ------------------ | ---------------------------------------------------------------- |
| `Codigo` | Código interno do cliente |
| `IsPessoa` | Tipo de pessoa: `F` (Física) ou `J` (Jurídica) |
| `Nome_RazaoSocial` | Nome completo ou razão social do cliente |
| `CPF_CNPJ` | CPF ou CNPJ (pode vir formatado ou não) |
| `RG_IE` | RG ou IE (pode vir formatado ou não) |
| `DataNascimento` | Data de nascimento (`Ano-Mês-Dia`) |
| `ObsStaff` | Observação interna, visível apenas para a administração |
| `Email` | E-mail do cliente |
| `Telefone01/02/03` | Telefones de contato |
| `Endereco` | Endereço do cliente (estado, cidade, bairro, logradouro, CEP...) |
Exemplo completo de um cliente retornado:
```json
{
"Codigo": "679695",
"IsPessoa": "F",
"Nome_RazaoSocial": "Paloma Macetko",
"CPF_CNPJ": "999.999.99-99",
"RG_IE": "",
"DataNascimento": "2024-01-01",
"ObsStaff": "",
"Email": "suporte2@web4business.com.br",
"Telefone01": "(47) 11111111",
"Telefone03": "(47) 22222222",
"Telefone02": "(47) 33333333",
"Endereco": {
"End_Estado": "SC",
"End_Cidade": "Brusque",
"End_Bairro": "Centro",
"End_Endereco": "Rua Central",
"End_Numero": "99",
"End_Complemento": "",
"End_CEP": "88350-000"
}
}
```
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Visão Geral
Através da API de **Cupons de Desconto** você pode consultar e gerenciar os cupons da loja: listar, ver os detalhes, criar novos cupons, editar e excluir.
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🔄 Fluxo típico
Um fluxo comum de integração de cupons costuma seguir esta ordem:
1. **Listar** os cupons, filtrando por status ou pela chave de busca (código ou observação).
2. **Consultar os detalhes** de um cupom específico.
3. **Criar** um novo cupom de desconto.
4. **Editar** um cupom já existente (valores, vigência, status).
5. **Excluir** um cupom que não será mais utilizado.
## 🧭 Endpoints de Cupons de Desconto
| Ação | Método | Rota |
| ----------------------- | ------ | --------------------------- |
| Listar e filtrar cupons | GET | `/cupom-desconto/` |
| Detalhes de um cupom | GET | `/cupom-desconto/{Codigo}/` |
| Criar cupom | POST | `/cupom-desconto/` |
| Editar cupom | PUT | `/cupom-desconto/{Codigo}/` |
| Excluir cupom | DELETE | `/cupom-desconto/{Codigo}/` |
# Listar Cupons
Retorna a **listagem de cupons de desconto** da loja, com suporte a filtros e paginação.
```
GET /cupom-desconto/
```
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| -------------- | ------- | -------------------------------------------------------------- |
| `Status` | texto | Filtra pelo status: `A` (Ativado) ou `D` (Desativado) |
| `ChaveBusca` | texto | Busca pelo **Código do Cupom** ou pela **Observação** do cupom |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
## 📥 Exemplo de requisição
Buscando cupons **ativos** que contenham um termo na chave de busca, 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/cupom-desconto/?Status=A&ChaveBusca=Teste&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": "309604",
"Status": "A",
"CodigoCupom": "Z3a3df80d2baad67",
"Observacao": "",
"DataDe": "2020-10-16",
"DataAte": "2020-11-15",
"QtdUtilizacoes": "100",
"QtdPorCliente": "1",
"DescontoTipo": "P",
"DescontoValor": "12.37",
"ValorMinimoCompra": "0.00"
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 2
}
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| ------------------- | ------- | ---------------------------------------------------------- |
| `Codigo` | inteiro | Código interno do cupom |
| `Status` | texto | `A` (Ativado) ou `D` (Desativado) |
| `CodigoCupom` | texto | Código que o cliente utiliza na cesta de compras |
| `Observacao` | texto | Observação privada, visível apenas para a administração |
| `DataDe` | data | Início da vigência do cupom (`Ano-Mês-Dia`) |
| `DataAte` | data | Fim da vigência do cupom (`Ano-Mês-Dia`) |
| `QtdUtilizacoes` | inteiro | Quantidade limite de utilizações do cupom |
| `QtdPorCliente` | inteiro | Quantidade de utilizações por cliente |
| `DescontoTipo` | texto | `P` (Porcentagem) ou `V` (Valor fixo) |
| `DescontoValor` | decimal | Valor ou porcentagem de desconto (conforme `DescontoTipo`) |
| `ValorMinimoCompra` | decimal | Valor mínimo da compra para o cupom poder ser utilizado |
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Cupom
Retorna os **dados completos** de um cupom de desconto específico, identificado pelo seu **Código**.
```
GET /cupom-desconto/{Codigo}/
```
O `{Codigo}` é o código interno do cupom, obtido na [listagem de cupons](/cupons-de-desconto/listar-cupons).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/cupom-desconto/313255/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
```json
{
"Codigo": "313255",
"Status": "D",
"CodigoCupom": "TesteCupom1 Editado",
"Observacao": "Teste",
"DataDe": "2020-12-01",
"DataAte": "2020-12-10",
"QtdUtilizacoes": "100",
"QtdPorCliente": "1",
"DescontoTipo": "P",
"DescontoValor": "12.34",
"ValorMinimoCompra": "100.98"
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| ------------------- | ------- | ---------------------------------------------------------- |
| `Codigo` | inteiro | Código interno do cupom |
| `Status` | texto | `A` (Ativado) ou `D` (Desativado) |
| `CodigoCupom` | texto | Código que o cliente utiliza na cesta de compras |
| `Observacao` | texto | Observação privada, visível apenas para a administração |
| `DataDe` | data | Início da vigência do cupom (`Ano-Mês-Dia`) |
| `DataAte` | data | Fim da vigência do cupom (`Ano-Mês-Dia`) |
| `QtdUtilizacoes` | inteiro | Quantidade limite de utilizações do cupom |
| `QtdPorCliente` | inteiro | Quantidade de utilizações por cliente |
| `DescontoTipo` | texto | `P` (Porcentagem) ou `V` (Valor fixo) |
| `DescontoValor` | decimal | Valor ou porcentagem de desconto (conforme `DescontoTipo`) |
| `ValorMinimoCompra` | decimal | Valor mínimo da compra para o cupom poder ser utilizado |
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Criar Cupom
Cadastra um **novo cupom de desconto** na loja.
```
POST /cupom-desconto/
```
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| ------------------- | ------- | ----------- | ------------------------------------------------------------------------------ |
| `CodigoCupom` | texto | ✅ Sim | Código que o cliente utiliza na cesta de compras |
| `DataDe` | data | ✅ Sim | Início da vigência do cupom (`Ano-Mês-Dia`) |
| `DataAte` | data | ✅ Sim | Fim da vigência do cupom (`Ano-Mês-Dia`) |
| `QtdUtilizacoes` | inteiro | ✅ Sim | Quantidade limite de utilizações do cupom |
| `DescontoTipo` | texto | ✅ Sim | `P` (Porcentagem) ou `V` (Valor fixo) |
| `DescontoValor` | decimal | ✅ Sim | Valor ou porcentagem de desconto (conforme `DescontoTipo`) |
| `Status` | texto | ✅ Sim | `A` (Ativado) ou `D` (Desativado) |
| `Observacao` | texto | ❌ Não | Observação privada, visível apenas para a administração |
| `QtdPorCliente` | inteiro | ❌ Não | Utilizações por cliente. Se omitido, o cliente pode usar quantas vezes desejar |
| `ValorMinimoCompra` | decimal | ❌ Não | Valor mínimo da compra para o cupom poder ser utilizado |
## 📥 Exemplo de requisição
```bash
curl -X POST "https://api.toplojas.com.br/cupom-desconto/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"CodigoCupom": "TesteCupom1",
"Observacao": "Teste",
"DataDe": "2020-12-01",
"DataAte": "2020-12-10",
"QtdUtilizacoes": 100,
"QtdPorCliente": 1,
"DescontoTipo": "P",
"DescontoValor": 12.34,
"ValorMinimoCompra": 100.98,
"Status": "A"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **201**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Editar Cupom
Altera os dados de um **cupom de desconto** já existente, identificado pelo seu **Código**.
```
PUT /cupom-desconto/{Codigo}/
```
O `{Codigo}` é o código interno do cupom, obtido na [listagem de cupons](/cupons-de-desconto/listar-cupons).
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| ------------------- | ------- | ----------- | ------------------------------------------------------------------------------ |
| `CodigoCupom` | texto | ✅ Sim | Código que o cliente utiliza na cesta de compras |
| `DataDe` | data | ✅ Sim | Início da vigência do cupom (`Ano-Mês-Dia`) |
| `DataAte` | data | ✅ Sim | Fim da vigência do cupom (`Ano-Mês-Dia`) |
| `QtdUtilizacoes` | inteiro | ✅ Sim | Quantidade limite de utilizações do cupom |
| `DescontoTipo` | texto | ✅ Sim | `P` (Porcentagem) ou `V` (Valor fixo) |
| `DescontoValor` | decimal | ✅ Sim | Valor ou porcentagem de desconto (conforme `DescontoTipo`) |
| `Status` | texto | ✅ Sim | `A` (Ativado) ou `D` (Desativado) |
| `Observacao` | texto | ❌ Não | Observação privada, visível apenas para a administração |
| `QtdPorCliente` | inteiro | ❌ Não | Utilizações por cliente. Se omitido, o cliente pode usar quantas vezes desejar |
| `ValorMinimoCompra` | decimal | ❌ Não | Valor mínimo da compra para o cupom poder ser utilizado |
## 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/cupom-desconto/313255/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"CodigoCupom": "TesteCupom1 Editado",
"Observacao": "Teste",
"DataDe": "2020-12-01",
"DataAte": "2020-12-10",
"QtdUtilizacoes": 100,
"QtdPorCliente": 1,
"DescontoTipo": "P",
"DescontoValor": 12.34,
"ValorMinimoCompra": 100.98,
"Status": "D"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Excluir Cupom
Remove um **cupom de desconto** da loja, identificado pelo seu **Código**.
```
DELETE /cupom-desconto/{Codigo}/
```
O `{Codigo}` é o código interno do cupom, obtido na [listagem de cupons](/cupons-de-desconto/listar-cupons).
{% hint style="info" %}
A exclusão é **definitiva**. Se você deseja apenas suspender o cupom temporariamente, prefira [editar o cupom](/cupons-de-desconto/editar-cupom) e alterar o `Status` para `D` (Desativado).
{% endhint %}
## 📥 Exemplo de requisição
```bash
curl -X DELETE "https://api.toplojas.com.br/cupom-desconto/313255/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Visão Geral
Através da API de **Newsletter** você pode gerenciar os inscritos na newsletter da loja: listar, ver os detalhes, cadastrar, editar e excluir inscritos.
{% hint style="info" %}
Estas páginas são **guias práticos**. A referência completa de cada campo, tipo e schema está no simulador online:
{% embed url="" %}
{% endhint %}
## 🔄 Fluxo típico
Um fluxo comum de integração da newsletter costuma seguir esta ordem:
1. **Listar** os inscritos, filtrando por status ou por nome/e-mail.
2. **Consultar os detalhes** de um inscrito específico.
3. **Cadastrar** um novo inscrito na newsletter.
4. **Editar** os dados de um inscrito (por exemplo, ativar ou desativar).
5. **Excluir** um inscrito quando necessário.
## 🧭 Endpoints de Newsletter
| Ação | Método | Rota |
| -------------------------- | ------ | ----------------------- |
| Listar e filtrar inscritos | GET | `/newsletter/` |
| Detalhes de um inscrito | GET | `/newsletter/{Codigo}/` |
| Cadastrar inscrito | POST | `/newsletter/` |
| Editar inscrito | PUT | `/newsletter/{Codigo}/` |
| Excluir inscrito | DELETE | `/newsletter/{Codigo}/` |
## 🏷️ Status do inscrito
O campo `Status` indica se o inscrito está ativo ou não na newsletter:
| Valor | Significado |
| ----- | ----------- |
| `A` | Ativado |
| `D` | Desativado |
# Listar Newsletter
Retorna a **listagem dos inscritos** na newsletter da loja, com suporte a filtros e paginação.
```
GET /newsletter/
```
## 🔎 Filtros disponíveis
Os filtros são enviados na **Query** da requisição. Todos são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
| -------------- | ------- | ----------------------------------------------------------------- |
| `Status` | texto | Filtra pelo status do inscrito: `A` (Ativado) ou `D` (Desativado) |
| `ChaveBusca` | texto | Pesquisa pelo **Nome** ou **E-mail** do inscrito |
| `Pagina` | inteiro | Página desejada (paginação) |
| `QtdPorPagina` | inteiro | Registros por página (máx. **100**) |
## 📥 Exemplo de requisição
Buscando inscritos **ativos**, pesquisando por "teste", 50 por página:
```bash
curl -X GET "https://api.toplojas.com.br/newsletter/?Status=A&ChaveBusca=teste&QtdPorPagina=50" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
A resposta segue o padrão de paginação (`Dados` + `Paginacao`):
```json
{
"Dados": [
{
"Codigo": 142639,
"Status": "A",
"Nome": "teste1",
"Email": "teste1@google.com.br"
}
],
"Paginacao": {
"PaginaAtual": 1,
"QtdPaginas": 1,
"QtdRegistros": 1
}
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| -------- | ------- | ----------------------------------------------------- |
| `Codigo` | inteiro | Código do inscrito na newsletter |
| `Status` | texto | Status do inscrito: `A` (Ativado) ou `D` (Desativado) |
| `Nome` | texto | Nome do inscrito |
| `Email` | texto | E-mail do inscrito |
{% hint style="info" %}
Consulte a descrição de cada campo na referência:
{% embed url="" %}
{% endhint %}
Para entender o funcionamento da paginação, veja:
{% content-ref url="/pages/-MObwaEfNJbBvr8ZSK0U" %}
[Paginação](/funcionamento/paginacao)
{% endcontent-ref %}
# Detalhes do Newsletter
Retorna os **dados** de um inscrito específico da newsletter, identificado pelo seu **Código**.
```
GET /newsletter/{Codigo}/
```
O `{Codigo}` é o código do inscrito, obtido na [listagem da newsletter](/newsletter/listar-newsletter).
## 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/newsletter/142639/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
## 📤 Exemplo de resposta
```json
{
"Status": "A",
"Nome": "teste2",
"Email": "teste2@google.com.br"
}
```
## 📋 Campos retornados
| Campo | Tipo | Descrição |
| -------- | ----- | ----------------------------------------------------- |
| `Status` | texto | Status do inscrito: `A` (Ativado) ou `D` (Desativado) |
| `Nome` | texto | Nome do inscrito |
| `Email` | texto | E-mail do inscrito |
{% hint style="info" %}
Consulte a descrição de cada campo retornado na referência:
{% embed url="" %}
{% endhint %}
# Cadastrar Newsletter
Cadastra um **novo inscrito** na newsletter da loja.
```
POST /newsletter/
```
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| -------- | ----- | ----------- | ----------------------------------------------------- |
| `Status` | texto | ✅ Sim | Status do inscrito: `A` (Ativado) ou `D` (Desativado) |
| `Email` | texto | ✅ Sim | E-mail do inscrito |
| `Nome` | texto | ❌ Não | Nome do inscrito |
## 📥 Exemplo de requisição
```bash
curl -X POST "https://api.toplojas.com.br/newsletter/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Status": "A",
"Nome": "teste2",
"Email": "teste2@google.com.br"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **201**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Editar Newsletter
Atualiza os dados de um **inscrito** da newsletter, identificado pelo seu **Código**. É o endpoint usado, por exemplo, para **ativar** ou **desativar** um inscrito.
```
PUT /newsletter/{Codigo}/
```
O `{Codigo}` é o código do inscrito, obtido na [listagem da newsletter](/newsletter/listar-newsletter).
## 📋 Campos
| Campo | Tipo | Obrigatório | Descrição |
| -------- | ----- | ----------- | ----------------------------------------------------- |
| `Status` | texto | ✅ Sim | Status do inscrito: `A` (Ativado) ou `D` (Desativado) |
| `Email` | texto | ✅ Sim | E-mail do inscrito |
| `Nome` | texto | ❌ Não | Nome do inscrito |
## 📥 Exemplo de requisição
```bash
curl -X PUT "https://api.toplojas.com.br/newsletter/142639/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]" \
-H "Content-Type: application/json" \
-d '{
"Status": "A",
"Nome": "teste2",
"Email": "teste2@google.com.br"
}'
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Excluir Newsletter
Remove um **inscrito** da newsletter da loja, identificado pelo seu **Código**.
```
DELETE /newsletter/{Codigo}/
```
O `{Codigo}` é o código do inscrito, obtido na [listagem da newsletter](/newsletter/listar-newsletter).
## 📥 Exemplo de requisição
```bash
curl -X DELETE "https://api.toplojas.com.br/newsletter/142639/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
Em caso de sucesso, a API retorna o HTTP Code **204**.
{% hint style="info" %}
Referência completa deste endpoint:
{% embed url="" %}
{% endhint %}
# Informações
O módulo **Informações** reúne endpoints de **consulta** que retornam listas de apoio da sua loja: os **status de pedidos** disponíveis na plataforma, as **formas de entrega** ativas e as **formas de pagamento** ativas.
Esses códigos são úteis, por exemplo, para saber qual `Codigo` de status usar ao **alterar o status de um pedido**, ou para identificar as formas de entrega e pagamento que aparecem nos pedidos.
{% hint style="info" %}
Todos os endpoints deste módulo são **GET** e retornam **listas simples** — **não** são paginados.
A referência completa de cada campo está no simulador online:
{% embed url="" %}
{% endhint %}
## 📋 Status de Pedidos
Retorna a lista de **status de pedidos** disponíveis na plataforma, com o `Codigo` de cada status.
```
GET /informacoes/status/
```
Use o `Codigo` retornado aqui para saber qual valor informar ao **alterar o status** de um pedido:
{% content-ref url="/pages/Z9rIbMa20RTCqjphukbt" %}
[Alterar Status](/pedidos/alterar-status)
{% endcontent-ref %}
### 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/informacoes/status/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
### 📤 Exemplo de resposta
```json
[
{
"Codigo": 3,
"NomeStaff": "Aguardando Pagamento"
}
]
```
## 🚚 Formas de Entrega
Retorna a lista de **formas de entrega ativas** na loja, com o `Codigo` e o `Nome` de cada uma.
```
GET /informacoes/formas-entrega/
```
### 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/informacoes/formas-entrega/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
### 📤 Exemplo de resposta
```json
[
{
"Codigo": 1747,
"Nome": "Sedex"
}
]
```
## 💳 Formas de Pagamento
Retorna a lista de **formas de pagamento ativas** na loja. Cada item traz o `Codigo`, o `Grupo` (tipo de pagamento, ex.: Cartão de Crédito, Boleto Bancário), o `Gateway` atrelado (ex.: Cielo, Stone, Rede) e o `Nome` exibido na loja.
```
GET /informacoes/formas-pagamento/
```
### 📥 Exemplo de requisição
```bash
curl -X GET "https://api.toplojas.com.br/informacoes/formas-pagamento/" \
-H "Authorization: Bearer [Token]" \
-H "Loja: [Identificador de Sua Loja]"
```
### 📤 Exemplo de resposta
```json
[
{
"Codigo": 35876,
"Grupo": "Cartão de Crédito",
"Gateway": "CIELO - Webservice 3.0",
"Nome": "Visa"
}
]
```
# Processar um Pedido
Este guia mostra um **fluxo completo** de processamento de um pedido, do recebimento até a entrega, combinando vários endpoints da API.
{% hint style="info" %}
Cada passo abaixo tem uma página dedicada com todos os detalhes. Aqui mostramos como eles se **encaixam** em um processo real.
{% endhint %}
## 1️⃣ Seja notificado de um novo pedido pago
Em vez de consultar a listagem repetidamente, configure um **Webhook** para o evento `Pedidos_Pagos`. Assim, sua aplicação é avisada assim que um pedido tem o pagamento confirmado.
{% content-ref url="/pages/rbiZGRer0EGAGyswrCCw" %}
[Webhook](/funcionamento/webhook)
{% endcontent-ref %}
O webhook envia o **código do pedido** (`CodigoPedido`), que você usa nos próximos passos.
## 2️⃣ Consulte os detalhes do pedido
Com o código em mãos, obtenha os dados completos (cliente, itens, valores, endereço):
{% content-ref url="/pages/MmarhErcLW6IbvhC3bZX" %}
[Detalhes do Pedido](/pedidos/detalhes-do-pedido)
{% endcontent-ref %}
## 3️⃣ Descubra o código do próximo status
Os status possuem **códigos**. Consulte a lista para saber qual código usar (por exemplo, "Em separação" ou "Enviado"):
{% content-ref url="/pages/XbCkfnDdDIoHsqwnsigd" %}
[Informações](/informacoes/informacoes)
{% endcontent-ref %}
## 4️⃣ Atualize o status do pedido
Conforme o pedido avança, altere o status (opcionalmente notificando o cliente por e-mail):
{% content-ref url="/pages/Z9rIbMa20RTCqjphukbt" %}
[Alterar Status](/pedidos/alterar-status)
{% endcontent-ref %}
## 5️⃣ Informe o código de rastreio
Ao despachar o pedido, registre o código de rastreio para o cliente acompanhar a entrega:
{% content-ref url="/pages/tti0G7q5dyajLfILqHdJ" %}
[Informar Código de Rastreio](/pedidos/informar-rastreio)
{% endcontent-ref %}
## 6️⃣ Informe a nota fiscal
Registre os dados da NF-e emitida para o pedido:
{% content-ref url="/pages/uOUqWCJNmzqo4LjNsyjy" %}
[Informar Nota Fiscal](/pedidos/informar-nota-fiscal)
{% endcontent-ref %}
## 🔄 Resumo do fluxo
| Passo | Ação | Endpoint |
| ----- | ----------------------------- | ------------------------------------------------- |
| 1 | Ser notificado do pedido pago | Webhook `Pedidos_Pagos` |
| 2 | Consultar detalhes | `GET /pedidos/{Codigo}/` |
| 3 | Descobrir código do status | `GET /informacoes/status/` |
| 4 | Alterar status | `PUT /pedidos/{Codigo}/alterar-status/` |
| 5 | Informar rastreio | `PUT /pedidos/{Codigo}/informar-codigo-rastreio/` |
| 6 | Informar nota fiscal | `PUT /pedidos/{Codigo}/informar-nota-fiscal/` |
# Sincronizar Catálogo
Este guia mostra o **fluxo recomendado** para montar e manter o catálogo da sua loja via API: dos departamentos aos produtos e ao estoque.
{% hint style="info" %}
Cada passo tem uma página dedicada com todos os detalhes. Aqui mostramos a **ordem** e como as peças se encaixam.
{% endhint %}
## 1️⃣ Crie a estrutura de departamentos
Os produtos são organizados em **departamentos** (categorias). Crie primeiro os departamentos, pois os produtos são associados a eles pelo nome.
{% content-ref url="/pages/mHqykE9GTRDBP0Gd1BLf" %}
[Criar Departamento](/departamentos/criar-departamento)
{% endcontent-ref %}
Para criar uma hierarquia (subdepartamentos), informe o `CodigoPai` do departamento pai. Consulte os departamentos existentes em:
{% content-ref url="/pages/gCqcpUynkvEUmuOBYBti" %}
[Listar Departamentos](/departamentos/listar-departamentos)
{% endcontent-ref %}
## 2️⃣ Cadastre os produtos
Com os departamentos prontos, cadastre os produtos, associando cada um aos seus departamentos:
{% content-ref url="/pages/KJSLnRImpNDiCRtK7Ult" %}
[Criar Produto](/produtos/criar-produto)
{% endcontent-ref %}
{% hint style="info" %}
Se você importa produtos de outro sistema, preencha o campo `CodigoImportacao`. Depois, você pode localizar o produto por esse código na [listagem de produtos](/produtos/listar-produtos).
{% endhint %}
## 3️⃣ Gerencie o estoque separadamente
{% hint style="warning" %}
O estoque **não** é alterado pelo endpoint de edição de produto. Use sempre o endpoint específico de estoque.
{% endhint %}
{% content-ref url="/pages/0VIX9jhqVUZ098rKiXAX" %}
[Gerenciar Estoque](/produtos/gerenciar-estoque)
{% endcontent-ref %}
## 4️⃣ Mantenha o catálogo atualizado
Para atualizações contínuas:
* **Editar** dados de um produto (preço, nome, descrição): [Editar Produto](/produtos/editar-produto).
* **Atualizar estoque** (inclusive por variação): [Gerenciar Estoque](/produtos/gerenciar-estoque).
* **Remover** um produto: [Excluir Produto](/produtos/excluir-produto).
## 🔄 Resumo do fluxo
| Passo | Ação | Endpoint |
| ----- | ------------------------- | ---------------------------------------- |
| 1 | Criar departamentos | `POST /departamentos/` |
| 2 | Cadastrar produtos | `POST /produtos/` |
| 3 | Definir/atualizar estoque | `PUT /produtos/estoque/{CodigoProduto}/` |
| 4 | Editar produto | `PUT /produtos/{Codigo}/` |