{ "openapi": "3.1.0", "info": { "title": "API do Hotel das Lojas", "version": "1.2", "description": "Integre lojas do Hotel das Lojas com sistemas externos. Documentação: https://docs.hoteldaslojas.com.br" }, "servers": [ { "url": "https://api.hoteldaslojas.com.br/v1" } ], "components": { "securitySchemes": { "chave": { "type": "http", "scheme": "bearer", "description": "Chave hdl_live_... criada no painel da loja" } } }, "security": [ { "chave": [] } ], "paths": { "/loja": { "get": { "tags": [ "Loja" ], "summary": "Obter Loja", "description": "Retorna os dados da loja dona da chave. Escopo: loja.ler", "operationId": "obter_loja", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 220, "nome": "Página Dobrada", "descricao": "Livraria independente com curadoria: romances, ensaios, livros infantis, clássicos em capa dura, box de presente e acessórios de leitura.", "url": "https://demo73.hoteldaslojas.com.br", "subdominio": "demo73", "ativa": true, "contato": { "email": "contato@hoteldaslojas.com.br", "whatsapp": "(11) 97373-7373", "instagram": "paginadobrada.demo" }, "endereco": { "cep": "85905-370", "rua": "Rua México", "numero": "123", "bairro": "Jardim Gisela", "complemento": "", "cidade": "Toledo", "estado": "Paraná" }, "moeda": "BRL", "pedido_minimo": 10.0, "frete_gratis_a_partir": 149.0 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "patch": { "tags": [ "Loja" ], "summary": "Editar Loja", "description": "Altera descrição, contatos e pedido mínimo. Escopo: loja.escrever", "operationId": "editar_loja", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 220, "nome": "Página Dobrada", "descricao": "Livraria independente com curadoria: romances, ensaios, livros infantis, clássicos em capa dura, box de presente e acessórios de leitura.", "url": "https://demo73.hoteldaslojas.com.br", "subdominio": "demo73", "ativa": true, "contato": { "email": "contato@hoteldaslojas.com.br", "whatsapp": "(11) 97373-7373", "instagram": "paginadobrada.demo" }, "endereco": { "cep": "85905-370", "rua": "Rua México", "numero": "123", "bairro": "Jardim Gisela", "complemento": "", "cidade": "Toledo", "estado": "Paraná" }, "moeda": "BRL", "pedido_minimo": 10.0, "frete_gratis_a_partir": 149.0 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "descricao": { "type": "string", "description": "Até 2000." }, "pedido_minimo": { "type": "number", "description": "Em reais (0 = sem mínimo)." }, "contato": { "type": "object", "description": "{ email, whatsapp, instagram (sem @) }." } }, "required": [] }, "example": { "pedido_minimo": 30, "contato": { "whatsapp": "41999990000", "instagram": "paginadobrada" } } } } } } }, "/produtos": { "get": { "tags": [ "Produtos" ], "summary": "Listar Produtos", "description": "Lista os produtos da loja com filtros e paginação. Escopo: produtos.ler", "operationId": "listar_produtos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "busca", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Procura no nome, SKU e marca." }, { "name": "sku", "in": "query", "required": false, "schema": { "type": "string" }, "description": "SKU exato." }, { "name": "categoria_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Só desta categoria." }, { "name": "ativo", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true = só ativos, false = só desativados." }, { "name": "atualizado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Só alterados a partir desta data (AAAA-MM-DD ou ISO 8601). Ideal para sincronizar." }, { "name": "ordem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "id, -id (padrão), nome, preco, -preco, atualizado, -atualizado." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "descricao": "", "marca": "Página Dobrada", "categoria_id": 783, "preco": 59.9, "preco_promocional": 39.9, "preco_final": 39.9, "ativo": true, "visivel": false, "estoque": { "controlado": true, "quantidade": 7, "minimo": 0 }, "peso_kg": 0.0, "dimensoes_cm": { "altura": 0.0, "largura": 0.0, "comprimento": 0.0 }, "imagens": [], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 20.0, "cor": null, "estoque": 4, "sku": "LIV-001-CD" } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2496-livro-teste-api", "criado_em": "2026-10-28T00:43:26-03:00", "atualizado_em": "2026-10-28T00:43:29-03:00" }, { "id": 2291, "sku": "PD-001", "nome": "O Farol das Horas Quietas", "descricao": "Uma faroleira, uma ilha sem relógios e cartas que chegam com dez anos de atraso.\n\nDestaques:\n- 312 páginas\n- Romance\n- Leitura do mês do clube", "marca": "Helena Prado", "categoria_id": 711, "preco": 69.9, "preco_promocional": 59.9, "preco_final": 59.9, "ativo": true, "visivel": true, "estoque": { "controlado": false, "quantidade": null, "minimo": 0 }, "peso_kg": 0.4, "dimensoes_cm": { "altura": 8.0, "largura": 12.0, "comprimento": 16.0 }, "imagens": [ "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/dm-p01-tnlh34.webp", "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/dm-p01b-tnlh34.webp" ], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2291-o-farol-das-horas-quietas", "criado_em": "2026-10-27T21:49:56-03:00", "atualizado_em": "2026-10-27T21:49:56-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 2, "total": 25, "paginas": 13 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Produtos" ], "summary": "Criar Produto", "description": "Cadastra um produto novo no catálogo. Escopo: produtos.escrever", "operationId": "criar_produto", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "descricao": "", "marca": "Página Dobrada", "categoria_id": 783, "preco": 59.9, "preco_promocional": 39.9, "preco_final": 39.9, "ativo": true, "visivel": false, "estoque": { "controlado": true, "quantidade": 7, "minimo": 0 }, "peso_kg": 0.0, "dimensoes_cm": { "altura": 0.0, "largura": 0.0, "comprimento": 0.0 }, "imagens": [], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 20.0, "cor": null, "estoque": 4, "sku": "LIV-001-CD" } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2496-livro-teste-api", "criado_em": "2026-10-28T00:43:26-03:00", "atualizado_em": "2026-10-28T00:43:29-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome do produto (até 255 caracteres)." }, "preco": { "type": "number", "description": "Preço em reais." }, "categoria_id": { "type": "integer", "description": "Categoria da loja." }, "sku": { "type": "string", "description": "Código interno. Se não vier, vira REF-{id}." }, "descricao": { "type": "string", "description": "Descrição com HTML simples." }, "marca": { "type": "string", "description": "Marca." }, "preco_promocional": { "type": "number", "description": "Preço em oferta." }, "ativo": { "type": "boolean", "description": "Padrão true." }, "visivel": { "type": "boolean", "description": "Padrão true." }, "estoque": { "type": "object", "description": "{ controlado: boolean, quantidade: integer, minimo: integer }. A quantidade inicial entra no histórico de estoque." }, "peso_kg": { "type": "number", "description": "Peso para frete." }, "dimensoes_cm": { "type": "object", "description": "{ altura, largura, comprimento }." }, "variacoes": { "type": "array", "items": { "type": "object" }, "description": "[{ nome, escolha_minima, escolha_maxima, opcoes: [{ nome, descricao, valor_adicional, cor }] }] (até 20 grupos e 60 opções por grupo)." } }, "required": [ "nome", "preco", "categoria_id" ] }, "example": { "nome": "Camiseta Básica Algodão", "preco": 79.9, "preco_promocional": 69.9, "categoria_id": 783, "sku": "CAM-001", "marca": "Minha Marca", "estoque": { "controlado": true, "quantidade": 25 }, "peso_kg": 0.3, "variacoes": [ { "nome": "Tamanho", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "P" }, { "nome": "M" }, { "nome": "G", "valor_adicional": 5 } ] } ] } } } } } }, "/produtos/{id}": { "get": { "tags": [ "Produtos" ], "summary": "Obter Produto", "description": "Retorna um produto com imagens, estoque e variações. Escopo: produtos.ler", "operationId": "obter_produto", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "descricao": "", "marca": "Página Dobrada", "categoria_id": 783, "preco": 59.9, "preco_promocional": 39.9, "preco_final": 39.9, "ativo": true, "visivel": false, "estoque": { "controlado": true, "quantidade": 7, "minimo": 0 }, "peso_kg": 0.0, "dimensoes_cm": { "altura": 0.0, "largura": 0.0, "comprimento": 0.0 }, "imagens": [], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 20.0, "cor": null, "estoque": 4, "sku": "LIV-001-CD" } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2496-livro-teste-api", "criado_em": "2026-10-28T00:43:26-03:00", "atualizado_em": "2026-10-28T00:43:29-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Produtos" ], "summary": "Editar Produto", "description": "Altera só os campos enviados. Escopo: produtos.escrever", "operationId": "editar_produto", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "descricao": "", "marca": "Página Dobrada", "categoria_id": 783, "preco": 59.9, "preco_promocional": 39.9, "preco_final": 39.9, "ativo": true, "visivel": false, "estoque": { "controlado": true, "quantidade": 7, "minimo": 0 }, "peso_kg": 0.0, "dimensoes_cm": { "altura": 0.0, "largura": 0.0, "comprimento": 0.0 }, "imagens": [], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 20.0, "cor": null, "estoque": 4, "sku": "LIV-001-CD" } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2496-livro-teste-api", "criado_em": "2026-10-28T00:43:26-03:00", "atualizado_em": "2026-10-28T00:43:29-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome." }, "preco": { "type": "number", "description": "Preço." }, "preco_promocional": { "type": "number", "description": "null tira da oferta." }, "categoria_id": { "type": "integer", "description": "Categoria." }, "ativo": { "type": "boolean", "description": "false desativa o produto." }, "visivel": { "type": "boolean", "description": "Aparece nas listas." }, "sku": { "type": "string", "description": "" }, "descricao": { "type": "string", "description": "" }, "marca": { "type": "string", "description": "" }, "estoque": { "type": "object", "description": "{ controlado, minimo }. A quantidade muda pelo endpoint de estoque." }, "peso_kg": { "type": "number", "description": "" }, "dimensoes_cm": { "type": "object", "description": "" }, "variacoes": { "type": "array", "items": { "type": "object" }, "description": "Substitui todas as variações do produto." } }, "required": [] }, "example": { "preco": 89.9, "preco_promocional": null, "ativo": true } } } } } }, "/produtos/{id}/estoque": { "get": { "tags": [ "Estoque" ], "summary": "Obter Estoque", "description": "Saldo do produto e de cada opção de variação. Escopo: produtos.ler", "operationId": "obter_estoque", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "produto_id": 2496, "controlado": true, "quantidade": 7, "minimo": 0, "variacoes": [ { "variacao": "Edição", "opcao": "Capa dura", "quantidade": 4, "sku": "LIV-001-CD" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "put": { "tags": [ "Estoque" ], "summary": "Ajustar Estoque", "description": "Soma, subtrai ou define a quantidade em estoque. Escopo: estoque.escrever", "operationId": "ajustar_estoque", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "produto_id": 2496, "controlado": true, "quantidade": 7, "minimo": 0, "variacoes": [ { "variacao": "Edição", "opcao": "Capa dura", "quantidade": 4, "sku": "LIV-001-CD" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "operacao": { "type": "string", "description": "definir (contagem de inventário), somar (entrada) ou subtrair (saída)." }, "quantidade": { "type": "integer", "description": "Quantidade (0 a 999999)." }, "motivo": { "type": "string", "description": "Aparece no histórico de estoque da loja." } }, "required": [ "operacao", "quantidade" ] }, "example": { "operacao": "subtrair", "quantidade": 2, "motivo": "Venda no balcão" } } } } } }, "/produtos/{id}/estoque/variacoes": { "put": { "tags": [ "Estoque" ], "summary": "Estoque por Variação", "description": "Define o saldo de cada opção (tamanho, cor...). Escopo: estoque.escrever", "operationId": "estoque_variacoes", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "produto_id": 2496, "controlado": true, "quantidade": 7, "minimo": 0, "variacoes": [ { "variacao": "Edição", "opcao": "Capa dura", "quantidade": 4, "sku": "LIV-001-CD" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object" }, "description": "[{ variacao, opcao, quantidade, sku }]. quantidade null = a opção deixa de controlar estoque." } }, "required": [ "itens" ] }, "example": { "itens": [ { "variacao": "Tamanho", "opcao": "M", "quantidade": 8, "sku": "CAM-001-M" }, { "variacao": "Tamanho", "opcao": "G", "quantidade": 0 } ] } } } } } }, "/categorias": { "get": { "tags": [ "Categorias" ], "summary": "Listar Categorias", "description": "Lista as categorias em ordem de exibição. Escopo: categorias.ler", "operationId": "listar_categorias", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "pai_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Só as filhas desta categoria (0 = raiz)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 711, "nome": "Ficção", "ordem": 1, "pai_id": null, "visivel": true, "ativo": true, "atualizado_em": "2026-10-27T22:49:53-03:00" }, { "id": 712, "nome": "Não Ficção", "ordem": 2, "pai_id": null, "visivel": true, "ativo": true, "atualizado_em": "2026-10-27T22:49:53-03:00" }, { "id": 713, "nome": "Infantil", "ordem": 3, "pai_id": null, "visivel": true, "ativo": true, "atualizado_em": "2026-10-27T22:49:53-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 3, "total": 7, "paginas": 3 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Categorias" ], "summary": "Criar Categoria", "description": "Cadastra uma categoria nova. Escopo: categorias.escrever", "operationId": "criar_categoria", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 783, "nome": "Lançamentos", "ordem": 99, "pai_id": null, "visivel": false, "ativo": true, "atualizado_em": "2026-10-28T00:43:26-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome (até 120)." }, "ordem": { "type": "integer", "description": "Posição." }, "pai_id": { "type": "integer", "description": "Categoria pai." }, "visivel": { "type": "boolean", "description": "Padrão true." }, "ativo": { "type": "boolean", "description": "Padrão true." } }, "required": [ "nome" ] }, "example": { "nome": "Lançamentos", "ordem": 1 } } } } } }, "/categorias/{id}": { "get": { "tags": [ "Categorias" ], "summary": "Obter Categoria", "description": "Retorna uma categoria. Escopo: categorias.ler", "operationId": "obter_categoria", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do categoria." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 783, "nome": "Lançamentos", "ordem": 99, "pai_id": null, "visivel": false, "ativo": true, "atualizado_em": "2026-10-28T00:43:26-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Categorias" ], "summary": "Editar Categoria", "description": "Altera só os campos enviados. Escopo: categorias.escrever", "operationId": "editar_categoria", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do categoria." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 783, "nome": "Lançamentos", "ordem": 99, "pai_id": null, "visivel": false, "ativo": true, "atualizado_em": "2026-10-28T00:43:26-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "" }, "ordem": { "type": "integer", "description": "" }, "pai_id": { "type": "integer", "description": "0 = raiz." }, "visivel": { "type": "boolean", "description": "" }, "ativo": { "type": "boolean", "description": "" } }, "required": [] }, "example": { "visivel": false } } } } }, "delete": { "tags": [ "Categorias" ], "summary": "Apagar Categoria", "description": "Remove uma categoria vazia. Escopo: categorias.escrever", "operationId": "apagar_categoria", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do categoria." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } } } } }, "/pedidos": { "get": { "tags": [ "Pedidos" ], "summary": "Listar Pedidos", "description": "Lista os pedidos com filtros por status, data e cliente. Escopo: pedidos.ler", "operationId": "listar_pedidos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Um ou mais, separados por vírgula: pendente, pago, aceito, enviado, pronto_retirada, concluido, cancelado, reembolsado." }, { "name": "situacao_pagamento", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pendente, em_analise, aprovado, recusado, estornado, cancelado." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compras a partir desta data." }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Compras até esta data." }, { "name": "cliente_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Pedidos de um cliente." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Pedidos deste e-mail." }, { "name": "id_maior_que", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Só pedidos com número maior (importação incremental)." }, { "name": "ordem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "id (mais antigos primeiro) ou padrão (mais novos primeiro)." }, { "name": "incluir_itens", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true traz itens, notas e histórico em cada pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 2178, "criado_em": "2026-10-28T00:43:00-03:00", "status": "cancelado", "status_nome": "Cancelado", "situacao_pagamento": "aprovado", "situacao_entrega": "cancelada", "cliente": { "id": null, "nome": "Cliente Lançamentos", "email": "marina@exemplo.com.br", "whatsapp": "11999990000", "documento": "" }, "valores": { "subtotal": 59.9, "desconto": 0.0, "frete": 0.0, "total": 59.9 }, "cupom": null, "pagamento": { "forma": "6", "nome": "Pix", "informacao": "", "pago_em": "2026-10-28T00:44:12-03:00", "link": null }, "entrega": { "forma": "retirada", "nome": "Envio - retirada", "codigo_rastreio": "AA123456789BR", "endereco": { "cep": "01001000", "rua": "Rua Teste", "numero": "10", "complemento": "", "bairro": "Centro", "referencia": "", "cidade": "Florianópolis", "estado": "Santa Catarina" } }, "observacao": "Deixar na portaria" } ], "paginacao": { "pagina": 1, "por_pagina": 1, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Pedidos" ], "summary": "Criar Pedido", "description": "Registra uma venda feita fora da loja (marketplace, balcão, outro sistema). Escopo: pedidos.criar", "operationId": "criar_pedido", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2180, "criado_em": "2026-10-28T02:53:20-03:00", "status": "pago", "status_nome": "Pago", "situacao_pagamento": "aprovado", "situacao_entrega": "aguardando", "cliente": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "" }, "valores": { "subtotal": 184.7, "desconto": 3.0, "frete": 15.0, "total": 196.7 }, "cupom": null, "pagamento": { "forma": "api", "nome": "Venda externa (API)", "informacao": "Pix no balcão", "pago_em": "2026-10-28T02:53:20-03:00", "link": null }, "entrega": { "forma": "Transportadora X", "nome": "Transportadora X", "codigo_rastreio": null, "endereco": { "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "", "bairro": "Bela Vista", "referencia": "", "cidade": "São Paulo", "estado": "SP" } }, "observacao": null, "itens": [ { "id": 771, "produto_id": 2291, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": null, "quantidade": 3, "preco_unitario": 59.9, "total": 179.7, "peso_kg": 0.4 }, { "id": 772, "produto_id": null, "sku": "", "nome": "Embalagem presente", "variacao": null, "quantidade": 1, "preco_unitario": 5.0, "total": 5.0, "peso_kg": 0.0 } ], "notas_internas": null, "nota_fiscal": null, "referencia_externa": "ML-2000009876543", "historico": [ { "status": "pago", "origem": "api", "detalhe": "Pedido criado pela API (ML-2000009876543)", "em": "2026-10-28T02:53:20-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cliente": { "type": "object", "description": "{ nome (obrigatório), email, whatsapp, documento }. Liga ao cadastro com o mesmo e-mail ou WhatsApp, ou cria um." }, "itens": { "type": "array", "items": { "type": "object" }, "description": "[{ produto_id ou sku, quantidade (padrão 1), preco_unitario, nome, variacao }] (até 100). Sem preco_unitario vale o preço atual do produto. Item avulso: nome e preco_unitario, sem produto." }, "referencia_externa": { "type": "string", "description": "Id do pedido no seu sistema (até 80). Repetir a mesma referência devolve o pedido já criado, sem duplicar. Também aceita o cabeçalho Idempotency-Key." }, "entrega": { "type": "object", "description": "{ forma (\"retirada\" ou o nome do envio), valor, endereco: { cep, rua, numero, complemento, bairro, cidade, estado, referencia } }." }, "pagamento": { "type": "object", "description": "{ forma (texto livre, ex.: \"Pix no balcão\"), situacao: pendente (padrão) ou pago }." }, "desconto": { "type": "number", "description": "Desconto em reais (no máximo o subtotal)." }, "observacao": { "type": "string", "description": "Recado do pedido (até 240)." }, "baixar_estoque": { "type": "boolean", "description": "Padrão true: baixa o estoque dos produtos que controlam estoque (tudo ou nada)." }, "enviar_email": { "type": "boolean", "description": "true envia ao cliente o e-mail de pedido recebido (padrão false)." } }, "required": [ "cliente", "itens" ] }, "example": { "referencia_externa": "ML-2000009876543", "cliente": { "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000" }, "itens": [ { "sku": "LIV-001", "quantidade": 3 }, { "nome": "Embalagem presente", "preco_unitario": 5 } ], "entrega": { "forma": "Transportadora X", "valor": 15, "endereco": { "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cidade": "São Paulo", "estado": "SP" } }, "desconto": 3, "pagamento": { "forma": "Pix no balcão", "situacao": "pago" } } } } } } }, "/pedidos/{id}": { "get": { "tags": [ "Pedidos" ], "summary": "Obter Pedido", "description": "Retorna o pedido com itens, endereço, valores e histórico. Escopo: pedidos.ler", "operationId": "obter_pedido", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2178, "criado_em": "2026-10-28T00:43:00-03:00", "status": "cancelado", "status_nome": "Cancelado", "situacao_pagamento": "aprovado", "situacao_entrega": "cancelada", "cliente": { "id": null, "nome": "Cliente Lançamentos", "email": "marina@exemplo.com.br", "whatsapp": "11999990000", "documento": "" }, "valores": { "subtotal": 59.9, "desconto": 0.0, "frete": 0.0, "total": 59.9 }, "cupom": null, "pagamento": { "forma": "6", "nome": "Pix", "informacao": "", "pago_em": "2026-10-28T00:44:12-03:00", "link": null }, "entrega": { "forma": "retirada", "nome": "Envio - retirada", "codigo_rastreio": "AA123456789BR", "endereco": { "cep": "01001000", "rua": "Rua Teste", "numero": "10", "complemento": "", "bairro": "Centro", "referencia": "", "cidade": "Florianópolis", "estado": "Santa Catarina" } }, "observacao": "Deixar na portaria", "itens": [ { "id": 769, "produto_id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": "Edição: Brochura", "quantidade": 1, "preco_unitario": 59.9, "total": 59.9, "peso_kg": 0.4 } ], "notas_internas": "[28/10/2026 00:44 · API] Nota fiscal 1234 emitida", "historico": [ { "status": "pago", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:12-03:00" }, { "status": "aceito", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "separando no ERP", "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "Código de rastreio: AA123456789BR", "em": "2026-10-28T00:44:23-03:00" }, { "status": "cancelado", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:27-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/pedidos/{id}/status": { "post": { "tags": [ "Pedidos" ], "summary": "Mudar Status do Pedido", "description": "Avança o pedido (pago, aceito, enviado, pronto para retirada, concluído) ou cancela. Escopo: pedidos.escrever", "operationId": "mudar_status", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2178, "criado_em": "2026-10-28T00:43:00-03:00", "status": "cancelado", "status_nome": "Cancelado", "situacao_pagamento": "aprovado", "situacao_entrega": "cancelada", "cliente": { "id": null, "nome": "Cliente Lançamentos", "email": "marina@exemplo.com.br", "whatsapp": "11999990000", "documento": "" }, "valores": { "subtotal": 59.9, "desconto": 0.0, "frete": 0.0, "total": 59.9 }, "cupom": null, "pagamento": { "forma": "6", "nome": "Pix", "informacao": "", "pago_em": "2026-10-28T00:44:12-03:00", "link": null }, "entrega": { "forma": "retirada", "nome": "Envio - retirada", "codigo_rastreio": "AA123456789BR", "endereco": { "cep": "01001000", "rua": "Rua Teste", "numero": "10", "complemento": "", "bairro": "Centro", "referencia": "", "cidade": "Florianópolis", "estado": "Santa Catarina" } }, "observacao": "Deixar na portaria", "itens": [ { "id": 769, "produto_id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": "Edição: Brochura", "quantidade": 1, "preco_unitario": 59.9, "total": 59.9, "peso_kg": 0.4 } ], "notas_internas": "[28/10/2026 00:44 · API] Nota fiscal 1234 emitida", "historico": [ { "status": "pago", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:12-03:00" }, { "status": "aceito", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "separando no ERP", "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "Código de rastreio: AA123456789BR", "em": "2026-10-28T00:44:23-03:00" }, { "status": "cancelado", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:27-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "pago, aceito, enviado, pronto_retirada, concluido ou cancelado." }, "observacao": { "type": "string", "description": "Fica no histórico do pedido." } }, "required": [ "status" ] }, "example": { "status": "enviado", "observacao": "Despachado pela transportadora" } } } } } }, "/pedidos/{id}/rastreio": { "put": { "tags": [ "Pedidos" ], "summary": "Informar Rastreio", "description": "Grava ou remove o código de rastreio. Escopo: pedidos.escrever", "operationId": "rastreio", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2178, "criado_em": "2026-10-28T00:43:00-03:00", "status": "cancelado", "status_nome": "Cancelado", "situacao_pagamento": "aprovado", "situacao_entrega": "cancelada", "cliente": { "id": null, "nome": "Cliente Lançamentos", "email": "marina@exemplo.com.br", "whatsapp": "11999990000", "documento": "" }, "valores": { "subtotal": 59.9, "desconto": 0.0, "frete": 0.0, "total": 59.9 }, "cupom": null, "pagamento": { "forma": "6", "nome": "Pix", "informacao": "", "pago_em": "2026-10-28T00:44:12-03:00", "link": null }, "entrega": { "forma": "retirada", "nome": "Envio - retirada", "codigo_rastreio": "AA123456789BR", "endereco": { "cep": "01001000", "rua": "Rua Teste", "numero": "10", "complemento": "", "bairro": "Centro", "referencia": "", "cidade": "Florianópolis", "estado": "Santa Catarina" } }, "observacao": "Deixar na portaria", "itens": [ { "id": 769, "produto_id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": "Edição: Brochura", "quantidade": 1, "preco_unitario": 59.9, "total": 59.9, "peso_kg": 0.4 } ], "notas_internas": "[28/10/2026 00:44 · API] Nota fiscal 1234 emitida", "historico": [ { "status": "pago", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:12-03:00" }, { "status": "aceito", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "separando no ERP", "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "Código de rastreio: AA123456789BR", "em": "2026-10-28T00:44:23-03:00" }, { "status": "cancelado", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:27-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo": { "type": "string", "description": "Código da transportadora (letras e números). null remove." } }, "required": [ "codigo" ] }, "example": { "codigo": "AA123456789BR" } } } } } }, "/pedidos/{id}/notas": { "post": { "tags": [ "Pedidos" ], "summary": "Adicionar Nota Interna", "description": "Acrescenta uma nota interna ao pedido (o cliente não vê). Escopo: pedidos.escrever", "operationId": "adicionar_nota", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2178, "criado_em": "2026-10-28T00:43:00-03:00", "status": "cancelado", "status_nome": "Cancelado", "situacao_pagamento": "aprovado", "situacao_entrega": "cancelada", "cliente": { "id": null, "nome": "Cliente Lançamentos", "email": "marina@exemplo.com.br", "whatsapp": "11999990000", "documento": "" }, "valores": { "subtotal": 59.9, "desconto": 0.0, "frete": 0.0, "total": 59.9 }, "cupom": null, "pagamento": { "forma": "6", "nome": "Pix", "informacao": "", "pago_em": "2026-10-28T00:44:12-03:00", "link": null }, "entrega": { "forma": "retirada", "nome": "Envio - retirada", "codigo_rastreio": "AA123456789BR", "endereco": { "cep": "01001000", "rua": "Rua Teste", "numero": "10", "complemento": "", "bairro": "Centro", "referencia": "", "cidade": "Florianópolis", "estado": "Santa Catarina" } }, "observacao": "Deixar na portaria", "itens": [ { "id": 769, "produto_id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "variacao": "Edição: Brochura", "quantidade": 1, "preco_unitario": 59.9, "total": 59.9, "peso_kg": 0.4 } ], "notas_internas": "[28/10/2026 00:44 · API] Nota fiscal 1234 emitida", "historico": [ { "status": "pago", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:12-03:00" }, { "status": "aceito", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "separando no ERP", "em": "2026-10-28T00:44:22-03:00" }, { "status": "info", "origem": "api", "detalhe": "Código de rastreio: AA123456789BR", "em": "2026-10-28T00:44:23-03:00" }, { "status": "cancelado", "origem": "api", "detalhe": null, "em": "2026-10-28T00:44:27-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "texto": { "type": "string", "description": "Até 1000 caracteres." } }, "required": [ "texto" ] }, "example": { "texto": "NF-e 1234 emitida pelo ERP" } } } } } }, "/clientes": { "get": { "tags": [ "Clientes" ], "summary": "Listar Clientes", "description": "Lista os clientes cadastrados. Escopo: clientes.ler", "operationId": "listar_clientes", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "busca", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Nome, e-mail ou WhatsApp." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail exato." }, { "name": "criado_desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cadastrados a partir desta data." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "12345678909", "tipo_pessoa": "PF", "nascimento": "1990-05-12", "endereco": { "cep": "80010000", "rua": "Rua XV de Novembro", "numero": "100", "complemento": "Ap 31", "bairro": "Centro", "referencia": "", "cidade": "Curitiba", "estado": "Paraná" }, "total_pedidos": 4, "tags": [ "vip" ], "bloqueado": false, "criado_em": "2026-03-02T14:10:00-03:00", "ultimo_login": "2026-10-20T09:12:44-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Clientes" ], "summary": "Cadastrar Cliente", "description": "Cadastra um cliente na loja. Escopo: clientes.escrever", "operationId": "criar_cliente", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "", "tipo_pessoa": "PF", "nascimento": null, "endereco": { "cep": "", "rua": "", "numero": "", "complemento": "", "bairro": "", "referencia": "", "cidade": "", "estado": "" }, "total_pedidos": 0, "tags": [ "atacado" ], "bloqueado": false, "criado_em": "2026-10-28T02:52:29-03:00", "ultimo_login": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Pelo menos 3 letras." }, "whatsapp": { "type": "string", "description": "Com DDD (10 a 13 dígitos)." }, "email": { "type": "string", "description": "" }, "documento": { "type": "string", "description": "CPF ou CNPJ válido." }, "tipo_pessoa": { "type": "string", "description": "PF ou PJ." }, "nascimento": { "type": "string", "description": "AAAA-MM-DD." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Etiquetas do CRM." }, "observacoes": { "type": "string", "description": "Notas internas." }, "endereco": { "type": "object", "description": "{ cep, rua, numero, complemento, bairro, referencia, cidade, estado (sigla) }." }, "bloqueado": { "type": "boolean", "description": "Bloqueia compras." }, "bloqueio_motivo": { "type": "string", "description": "" } }, "required": [ "nome", "whatsapp" ] }, "example": { "nome": "Marina Duarte", "whatsapp": "41999990000", "email": "marina@exemplo.com.br", "tags": [ "atacado" ] } } } } } }, "/clientes/{id}": { "get": { "tags": [ "Clientes" ], "summary": "Obter Cliente", "description": "Retorna um cliente. Escopo: clientes.ler", "operationId": "obter_cliente", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "12345678909", "tipo_pessoa": "PF", "nascimento": "1990-05-12", "endereco": { "cep": "80010000", "rua": "Rua XV de Novembro", "numero": "100", "complemento": "Ap 31", "bairro": "Centro", "referencia": "", "cidade": "Curitiba", "estado": "Paraná" }, "total_pedidos": 4, "tags": [ "vip" ], "bloqueado": false, "criado_em": "2026-03-02T14:10:00-03:00", "ultimo_login": "2026-10-20T09:12:44-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Clientes" ], "summary": "Editar Cliente", "description": "Altera só os campos enviados. Escopo: clientes.escrever", "operationId": "editar_cliente", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "12345678909", "tipo_pessoa": "PF", "nascimento": null, "endereco": { "cep": "", "rua": "", "numero": "", "complemento": "", "bairro": "", "referencia": "", "cidade": "", "estado": "" }, "total_pedidos": 0, "tags": [ "vip", "atacado" ], "bloqueado": false, "criado_em": "2026-10-28T02:52:29-03:00", "ultimo_login": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "tags": [ "vip", "atacado" ], "documento": "12345678909" } } } } } }, "/cupons": { "get": { "tags": [ "Cupons" ], "summary": "Listar Cupons", "description": "Lista os cupons de desconto. Escopo: cupons.ler", "operationId": "listar_cupons", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "codigo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Código exato." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 381, "codigo": "VOLTA15", "nome": "VOLTA15", "descricao": "", "tipo": "porcentagem", "valor": 15.0, "desconto_maximo": null, "pedido_minimo": null, "quantidade_disponivel": 5, "validade": "2027-12-31T23:59:59-03:00", "primeira_compra": false, "frete_gratis": true, "categorias": [ 783 ], "limite_por_cliente": null } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Cupons" ], "summary": "Criar Cupom", "description": "Cria um cupom de desconto. Escopo: cupons.escrever", "operationId": "criar_cupom", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 381, "codigo": "VOLTA15", "nome": "VOLTA15", "descricao": "", "tipo": "porcentagem", "valor": 15.0, "desconto_maximo": null, "pedido_minimo": null, "quantidade_disponivel": 5, "validade": "2027-12-31T23:59:59-03:00", "primeira_compra": false, "frete_gratis": true, "categorias": [ 783 ], "limite_por_cliente": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo": { "type": "string", "description": "3 a 40 letras, números, _ ou - (espaços são removidos, vira maiúsculas). Único na loja." }, "tipo": { "type": "string", "description": "porcentagem ou valor_fixo." }, "valor": { "type": "number", "description": "Porcentagem (até 100) ou reais." }, "quantidade_disponivel": { "type": "integer", "description": "Quantos usos." }, "validade": { "type": "string", "description": "AAAA-MM-DD (vale até 23:59) ou ISO 8601." }, "nome": { "type": "string", "description": "" }, "descricao": { "type": "string", "description": "" }, "desconto_maximo": { "type": "number", "description": "Teto em reais." }, "pedido_minimo": { "type": "number", "description": "" }, "primeira_compra": { "type": "boolean", "description": "" }, "frete_gratis": { "type": "boolean", "description": "" }, "categorias": { "type": "array", "items": { "type": "integer" }, "description": "Só nestas categorias." }, "limite_por_cliente": { "type": "integer", "description": "" } }, "required": [ "codigo", "tipo", "valor", "quantidade_disponivel", "validade" ] }, "example": { "codigo": "VOLTA15", "tipo": "porcentagem", "valor": 15, "quantidade_disponivel": 100, "validade": "2026-12-31", "pedido_minimo": 150 } } } } } }, "/cupons/{id}": { "get": { "tags": [ "Cupons" ], "summary": "Obter Cupom", "description": "Retorna um cupom. Escopo: cupons.ler", "operationId": "obter_cupom", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cupom." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 381, "codigo": "VOLTA15", "nome": "VOLTA15", "descricao": "", "tipo": "porcentagem", "valor": 15.0, "desconto_maximo": null, "pedido_minimo": null, "quantidade_disponivel": 5, "validade": "2027-12-31T23:59:59-03:00", "primeira_compra": false, "frete_gratis": true, "categorias": [ 783 ], "limite_por_cliente": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Cupons" ], "summary": "Editar Cupom", "description": "Altera só os campos enviados. Escopo: cupons.escrever", "operationId": "editar_cupom", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cupom." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 381, "codigo": "VOLTA15", "nome": "VOLTA15", "descricao": "", "tipo": "porcentagem", "valor": 15.0, "desconto_maximo": null, "pedido_minimo": null, "quantidade_disponivel": 5, "validade": "2027-12-31T23:59:59-03:00", "primeira_compra": false, "frete_gratis": true, "categorias": [ 783 ], "limite_por_cliente": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "number", "description": "" }, "quantidade_disponivel": { "type": "integer", "description": "" }, "validade": { "type": "string", "description": "" }, "frete_gratis": { "type": "boolean", "description": "" } }, "required": [] }, "example": { "quantidade_disponivel": 50, "validade": "2027-01-31" } } } } }, "delete": { "tags": [ "Cupons" ], "summary": "Apagar Cupom", "description": "Remove o cupom (pedidos que já usaram não mudam). Escopo: cupons.escrever", "operationId": "apagar_cupom", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cupom." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Listar Webhooks", "description": "Lista os webhooks da loja. Escopo: webhooks.gerenciar", "operationId": "listar_webhooks", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 1, "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ], "ativo": true, "falhas_seguidas": 0, "ultimo_envio": "2026-10-28T00:44:42-03:00", "ultimo_status_http": 200, "criado_em": "2026-10-28T00:43:12-03:00" } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Criar Webhook", "description": "Cadastra um endereço para receber eventos. Escopo: webhooks.gerenciar", "operationId": "criar_webhook", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 1, "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ], "ativo": true, "falhas_seguidas": 0, "ultimo_envio": null, "ultimo_status_http": null, "criado_em": "2026-10-28T00:43:12-03:00", "segredo": "9f2c6a1e5b7d4c3a8e0f1b2d3c4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6a" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "https público (porta 443), sem IP interno." }, "eventos": { "type": "array", "items": { "type": "string" }, "description": "Veja a lista em Webhooks › Eventos (pedidos, estoque, clientes, avaliações, perguntas e carrinhos)." } }, "required": [ "url", "eventos" ] }, "example": { "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ] } } } } } }, "/webhooks/{id}": { "patch": { "tags": [ "Webhooks" ], "summary": "Editar Webhook", "description": "Muda endereço, eventos ou pausa/reativa. Escopo: webhooks.gerenciar", "operationId": "editar_webhook", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do webhook." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 1, "url": "https://erp.exemplo.com.br/webhooks/hotel", "eventos": [ "pedido.criado", "pedido.status_alterado" ], "ativo": true, "falhas_seguidas": 0, "ultimo_envio": "2026-10-28T00:44:42-03:00", "ultimo_status_http": 200, "criado_em": "2026-10-28T00:43:12-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "" }, "eventos": { "type": "array", "items": { "type": "string" }, "description": "" }, "ativo": { "type": "boolean", "description": "true reativa e zera as falhas." } }, "required": [] }, "example": { "ativo": true } } } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Apagar Webhook", "description": "Remove o webhook e cancela entregas pendentes. Escopo: webhooks.gerenciar", "operationId": "apagar_webhook", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do webhook." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/webhooks/{id}/testar": { "post": { "tags": [ "Webhooks" ], "summary": "Testar Webhook", "description": "Envia na hora um evento \"teste\" assinado. Escopo: webhooks.gerenciar", "operationId": "testar_webhook", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do webhook." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "entregue": true, "status_http": 200, "resposta": "{\"ok\":true}" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } } } }, "/webhooks/{id}/entregas": { "get": { "tags": [ "Webhooks" ], "summary": "Listar Entregas", "description": "Histórico de envios do webhook (30 dias). Escopo: webhooks.gerenciar", "operationId": "entregas_webhook", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do webhook." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 4, "evento": "pedido.criado", "situacao": "entregue", "tentativas": 1, "status_http": 200, "resposta": "{\"api\":\"Hotel das Lojas\",\"versao\":\"v1\",\"documentacao\":\"https://docs.hoteldaslojas.com.br\"}", "proxima_tentativa": null, "criado_em": "2026-10-28T00:44:41-03:00", "entregue_em": "2026-10-28T00:44:42-03:00" }, { "id": 3, "evento": "pedido.status_alterado", "situacao": "entregue", "tentativas": 1, "status_http": 200, "resposta": "{\"api\":\"Hotel das Lojas\",\"versao\":\"v1\",\"documentacao\":\"https://docs.hoteldaslojas.com.br\"}", "proxima_tentativa": null, "criado_em": "2026-10-28T00:44:27-03:00", "entregue_em": "2026-10-28T00:44:42-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 4, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/produtos/{id}/imagens": { "get": { "tags": [ "Produtos" ], "summary": "Listar Imagens", "description": "Imagens do produto: a principal (id 0) e a galeria. Escopo: produtos.ler", "operationId": "listar_imagens", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 0, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-025224fc9f14ba31.webp", "principal": true }, { "id": 2464, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/dm-p01b-tnlh34.webp", "principal": false } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "post": { "tags": [ "Produtos" ], "summary": "Enviar Imagem", "description": "Envia uma foto por URL pública ou em base64. Escopo: produtos.escrever", "operationId": "enviar_imagem", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 0, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-025224fc9f14ba31.webp", "principal": true }, { "id": 2464, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/dm-p01b-tnlh34.webp", "principal": false } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Endereço http(s) público da imagem (baixamos na hora). Use url ou base64." }, "base64": { "type": "string", "description": "Conteúdo do arquivo em base64 (aceita o prefixo data:image/...;base64,)." }, "principal": { "type": "boolean", "description": "true torna esta a imagem de capa (a anterior vai para a galeria). A primeira imagem do produto já vira a principal." } }, "required": [] }, "example": { "url": "https://cdn.seuerp.com.br/fotos/cam-001-frente.jpg", "principal": true } } } } } }, "/produtos/{id}/imagens/{imagem_id}": { "patch": { "tags": [ "Produtos" ], "summary": "Tornar Imagem Principal", "description": "Troca a imagem de capa do produto. Escopo: produtos.escrever", "operationId": "imagem_principal", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." }, { "name": "imagem_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Imagem da galeria." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 0, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-025224fc9f14ba31.webp", "principal": true }, { "id": 2464, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/dm-p01b-tnlh34.webp", "principal": false } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "principal": { "type": "boolean", "description": "Envie true." } }, "required": [ "principal" ] }, "example": { "principal": true } } } } }, "delete": { "tags": [ "Produtos" ], "summary": "Remover Imagem", "description": "Tira a imagem do produto. Escopo: produtos.escrever", "operationId": "apagar_imagem", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." }, { "name": "imagem_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Imagem (0 = a principal)." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/produtos/lote": { "patch": { "tags": [ "Produtos" ], "summary": "Alterar Produtos em Lote", "description": "Muda preço, promoção e situação de até 100 produtos numa chamada. Escopo: produtos.escrever", "operationId": "produtos_lote", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "indice": 0, "id": 2291, "sku": "LIV-001", "ok": true }, { "indice": 1, "id": 2292, "sku": "LIV-002", "ok": true }, { "indice": 2, "id": null, "sku": "NAO-EXISTE", "ok": false, "erro": "Produto não encontrado (informe id ou sku)." } ], "resumo": { "total": 3, "atualizados": 2, "com_erro": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object" }, "description": "[{ id ou sku, preco, preco_promocional, ativo, visivel }] (até 100)." } }, "required": [ "itens" ] }, "example": { "itens": [ { "sku": "LIV-001", "preco": 64.9, "preco_promocional": 54.9 }, { "id": 2292, "ativo": false }, { "sku": "NAO-EXISTE", "preco": 10 } ] } } } } } }, "/estoque/lote": { "put": { "tags": [ "Estoque" ], "summary": "Estoque em Lote", "description": "Define o saldo de até 100 produtos ou opções de variação. Escopo: estoque.escrever", "operationId": "estoque_lote", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "indice": 0, "id": 2291, "sku": "LIV-001", "ok": true, "quantidade": 12 }, { "indice": 1, "id": 2291, "sku": "LIV-001", "ok": true, "quantidade": 4, "variacao": "Capa", "opcao": "Dura" } ], "resumo": { "total": 2, "atualizados": 2, "com_erro": 0 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itens": { "type": "array", "items": { "type": "object" }, "description": "[{ produto_id ou sku, quantidade, variacao, opcao }]. Com variacao e opcao, define o saldo daquela opção." }, "motivo": { "type": "string", "description": "Aparece no histórico de estoque (padrão \"Atualização em lote\")." } }, "required": [ "itens" ] }, "example": { "motivo": "Inventário do ERP", "itens": [ { "sku": "LIV-001", "quantidade": 12 }, { "produto_id": 2291, "variacao": "Capa", "opcao": "Dura", "quantidade": 4 } ] } } } } } }, "/pedidos/{id}/pagamentos": { "get": { "tags": [ "Pedidos" ], "summary": "Pagamentos do Pedido", "description": "Transações e avisos recebidos dos meios de pagamento. Escopo: pedidos.ler", "operationId": "pagamentos_pedido", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "pedido_id": 2178, "situacao_pagamento": "aprovado", "pagamento": { "forma": "7", "nome": "Cartão de crédito (Mercado Pago)", "informacao": "3x sem juros", "pago_em": "2026-10-27T15:22:10-03:00", "link": null }, "transacoes": [ { "id": 811, "gateway": "mercadopago", "codigo": "1325478965", "status": "approved", "valor": 189.7, "em": "2026-10-27T15:22:10-03:00" } ], "avisos": [ { "gateway": "mercadopago", "status": "approved", "valor": 189.7, "em": "2026-10-27T15:22:11-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/pedidos/{id}/nota-fiscal": { "get": { "tags": [ "Pedidos" ], "summary": "Obter Nota Fiscal", "description": "Nota fiscal informada para o pedido. Escopo: pedidos.ler", "operationId": "obter_nota_fiscal", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "numero": "1234", "serie": "1", "chave": "35261012345678000199550010000012341000012345", "emitida_em": "2026-10-28T02:53:21-03:00", "valor": 196.7, "url_danfe": "https://erp.exemplo.com.br/nfe/1234.pdf", "url_xml": null, "atualizado_em": "2026-10-28T02:53:21-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "put": { "tags": [ "Pedidos" ], "summary": "Informar Nota Fiscal", "description": "Grava ou substitui a NF-e do pedido (emitida no seu emissor). Escopo: pedidos.escrever", "operationId": "informar_nota_fiscal", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "numero": "1234", "serie": "1", "chave": "35261012345678000199550010000012341000012345", "emitida_em": "2026-10-28T02:53:21-03:00", "valor": 196.7, "url_danfe": "https://erp.exemplo.com.br/nfe/1234.pdf", "url_xml": null, "atualizado_em": "2026-10-28T02:53:21-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "numero": { "type": "string", "description": "Até 12 dígitos." }, "serie": { "type": "string", "description": "" }, "chave": { "type": "string", "description": "Chave de acesso com 44 dígitos." }, "emitida_em": { "type": "string", "description": "Padrão: agora." }, "valor": { "type": "number", "description": "" }, "url_danfe": { "type": "string", "description": "Link https do PDF." }, "url_xml": { "type": "string", "description": "Link https do XML." } }, "required": [ "numero" ] }, "example": { "numero": "1234", "serie": "1", "chave": "35261012345678000199550010000012341000012345", "valor": 196.7, "url_danfe": "https://erp.exemplo.com.br/nfe/1234.pdf" } } } } }, "delete": { "tags": [ "Pedidos" ], "summary": "Remover Nota Fiscal", "description": "Tira a nota fiscal do pedido (ex.: nota cancelada). Escopo: pedidos.escrever", "operationId": "apagar_nota_fiscal", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/clientes/{id}/enderecos": { "get": { "tags": [ "Clientes" ], "summary": "Listar Endereços", "description": "Endereços salvos na conta do cliente. Escopo: clientes.ler", "operationId": "listar_enderecos", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 48, "apelido": "Casa", "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "Ap 5", "bairro": "Bela Vista", "referencia": "", "cidade": "São Paulo", "estado": "SP", "padrao": true, "criado_em": "2026-10-28T02:52:30-03:00" } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "post": { "tags": [ "Clientes" ], "summary": "Adicionar Endereço", "description": "Salva um endereço na conta do cliente. Escopo: clientes.escrever", "operationId": "criar_endereco", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 48, "apelido": "Casa", "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "Ap 5", "bairro": "Bela Vista", "referencia": "", "cidade": "São Paulo", "estado": "SP", "padrao": true, "criado_em": "2026-10-28T02:52:30-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cep": { "type": "string", "description": "" }, "rua": { "type": "string", "description": "" }, "numero": { "type": "string", "description": "" }, "bairro": { "type": "string", "description": "" }, "cidade": { "type": "string", "description": "" }, "estado": { "type": "string", "description": "Sigla." }, "apelido": { "type": "string", "description": "" }, "complemento": { "type": "string", "description": "" }, "referencia": { "type": "string", "description": "" }, "padrao": { "type": "boolean", "description": "O primeiro endereço já é o padrão." } }, "required": [ "cep", "rua", "numero", "bairro", "cidade", "estado" ] }, "example": { "apelido": "Casa", "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "Ap 5", "bairro": "Bela Vista", "cidade": "São Paulo", "estado": "SP" } } } } } }, "/clientes/{id}/enderecos/{endereco_id}": { "patch": { "tags": [ "Clientes" ], "summary": "Editar Endereço", "description": "Altera só os campos enviados. Escopo: clientes.escrever", "operationId": "editar_endereco", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." }, { "name": "endereco_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Endereço." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 48, "apelido": "Casa", "cep": "01310100", "rua": "Av. Paulista", "numero": "1000", "complemento": "Ap 52", "bairro": "Bela Vista", "referencia": "", "cidade": "São Paulo", "estado": "SP", "padrao": true, "criado_em": "2026-10-28T02:52:30-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "complemento": "Ap 52", "padrao": true } } } } }, "delete": { "tags": [ "Clientes" ], "summary": "Remover Endereço", "description": "Apaga um endereço do cliente. Escopo: clientes.escrever", "operationId": "apagar_endereco", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." }, { "name": "endereco_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Endereço." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/clientes/{id}/favoritos": { "get": { "tags": [ "Clientes" ], "summary": "Listar Favoritos", "description": "Produtos que o cliente marcou como favoritos. Escopo: clientes.ler", "operationId": "favoritos", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "sku": "LIV-001", "adicionado_em": "2026-10-21T19:03:00-03:00" } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/frete/cotacao": { "post": { "tags": [ "Frete" ], "summary": "Cotar Frete", "description": "As mesmas opções de entrega que o cliente vê no carrinho. Escopo: frete.ler", "operationId": "cotar_frete", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "cep": "01310100", "subtotal": 119.8, "opcoes": [ { "codigo": "cep149", "nome": "Capital SP", "valor": 12.5, "prazo_dias": 2 }, { "codigo": "co04510", "nome": "Correios PAC", "valor": 36.0, "prazo_dias": 6 }, { "codigo": "co04014", "nome": "Correios SEDEX", "valor": 71.4, "prazo_dias": 2 } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cep": { "type": "string", "description": "CEP de destino." }, "itens": { "type": "array", "items": { "type": "object" }, "description": "[{ produto_id ou sku, quantidade }] (até 50)." } }, "required": [ "cep", "itens" ] }, "example": { "cep": "01310100", "itens": [ { "sku": "LIV-001", "quantidade": 2 } ] } } } } } }, "/frete/faixas-cep": { "get": { "tags": [ "Frete" ], "summary": "Listar Faixas de CEP", "description": "Tabela de frete própria da loja. Escopo: frete.ler", "operationId": "listar_faixas", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 149, "nome": "Capital SP", "cep_inicio": "01000000", "cep_fim": "05999999", "valor": 12.5, "prazo_dias": 2, "gratis_acima": 199.0, "ativo": true, "criado_em": "2026-10-28T02:52:36-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Frete" ], "summary": "Criar Faixa de CEP", "description": "Cria uma faixa de CEP com valor e prazo. Escopo: frete.escrever", "operationId": "criar_faixa", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 149, "nome": "Capital SP", "cep_inicio": "01000000", "cep_fim": "05999999", "valor": 12.5, "prazo_dias": 2, "gratis_acima": 199.0, "ativo": true, "criado_em": "2026-10-28T02:52:36-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "" }, "cep_inicio": { "type": "string", "description": "" }, "cep_fim": { "type": "string", "description": "" }, "valor": { "type": "number", "description": "" }, "prazo_dias": { "type": "integer", "description": "" }, "gratis_acima": { "type": "number", "description": "" }, "ativo": { "type": "boolean", "description": "Padrão true." } }, "required": [ "nome", "cep_inicio", "cep_fim", "valor" ] }, "example": { "nome": "Capital SP", "cep_inicio": "01000000", "cep_fim": "05999999", "valor": 12.5, "prazo_dias": 2, "gratis_acima": 199 } } } } } }, "/frete/faixas-cep/{id}": { "get": { "tags": [ "Frete" ], "summary": "Obter Faixa de CEP", "description": "Retorna uma faixa. Escopo: frete.ler", "operationId": "obter_faixa", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do faixa." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 149, "nome": "Capital SP", "cep_inicio": "01000000", "cep_fim": "05999999", "valor": 12.5, "prazo_dias": 2, "gratis_acima": 199.0, "ativo": true, "criado_em": "2026-10-28T02:52:36-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Frete" ], "summary": "Editar Faixa de CEP", "description": "Altera só os campos enviados. Escopo: frete.escrever", "operationId": "editar_faixa", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do faixa." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 149, "nome": "Capital SP", "cep_inicio": "01000000", "cep_fim": "05999999", "valor": 10.0, "prazo_dias": 2, "gratis_acima": 199.0, "ativo": true, "criado_em": "2026-10-28T02:52:36-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "valor": 10 } } } } }, "delete": { "tags": [ "Frete" ], "summary": "Apagar Faixa de CEP", "description": "Remove a faixa. Escopo: frete.escrever", "operationId": "apagar_faixa", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do faixa." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/carrinhos": { "get": { "tags": [ "Marketing" ], "summary": "Carrinhos Abandonados", "description": "Sacolas de clientes com conta paradas há mais de 1 hora. Escopo: marketing.ler", "operationId": "listar_carrinhos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Atualizados a partir desta data." }, { "name": "cliente_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 31, "cliente": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000" }, "itens": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "variacao": null, "quantidade": 1, "preco_unitario": 59.9, "total": 59.9 } ], "total": 59.9, "atualizado_em": "2026-10-27T18:40:02-03:00", "lembrete_enviado": true, "lembrete_enviado_em": "2026-10-27T20:45:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/carrinhos/{id}": { "get": { "tags": [ "Marketing" ], "summary": "Obter Carrinho", "description": "Retorna um carrinho. Escopo: marketing.ler", "operationId": "obter_carrinho", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do carrinho." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 31, "cliente": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000" }, "itens": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "variacao": null, "quantidade": 1, "preco_unitario": 59.9, "total": 59.9 } ], "total": 59.9, "atualizado_em": "2026-10-27T18:40:02-03:00", "lembrete_enviado": true, "lembrete_enviado_em": "2026-10-27T20:45:00-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/newsletter": { "get": { "tags": [ "Marketing" ], "summary": "Listar Newsletter", "description": "E-mails inscritos para receber novidades. Escopo: marketing.ler", "operationId": "listar_newsletter", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "situacao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "confirmado, aguardando_confirmacao ou descadastrado." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 14, "email": "leitor@exemplo.com.br", "origem": "api", "situacao": "aguardando_confirmacao", "inscrito_em": "2026-10-28T03:01:00-03:00", "confirmado_em": null, "descadastrado_em": null } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Marketing" ], "summary": "Inscrever na Newsletter", "description": "Inscreve um e-mail (a pessoa confirma pelo e-mail). Escopo: marketing.escrever", "operationId": "inscrever_newsletter", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 14, "email": "leitor@exemplo.com.br", "origem": "api", "situacao": "aguardando_confirmacao", "inscrito_em": "2026-10-28T03:01:00-03:00", "confirmado_em": null, "descadastrado_em": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "" } }, "required": [ "email" ] }, "example": { "email": "leitor@exemplo.com.br" } } } } } }, "/newsletter/{id}": { "delete": { "tags": [ "Marketing" ], "summary": "Descadastrar da Newsletter", "description": "Marca o e-mail como descadastrado. Escopo: marketing.escrever", "operationId": "remover_newsletter", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do inscrição." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/promocoes": { "get": { "tags": [ "Marketing" ], "summary": "Listar Promoções", "description": "Promoções automáticas do carrinho. Escopo: marketing.ler", "operationId": "listar_promocoes", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 98, "nome": "Leve 3 pague 2", "tipo": "leve_pague", "categorias": [], "leve": 3, "pague": 2, "quantidade_minima": null, "percentual": null, "valor_minimo": null, "inicio": null, "fim": "2026-11-30T23:59:59-03:00", "ativo": true, "criado_em": "2026-10-28T02:52:31-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Marketing" ], "summary": "Criar Promoção", "description": "Leve X pague Y, desconto por quantidade ou acima de um valor. Escopo: marketing.escrever", "operationId": "criar_promocao", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 98, "nome": "Leve 3 pague 2", "tipo": "leve_pague", "categorias": [], "leve": 3, "pague": 2, "quantidade_minima": null, "percentual": null, "valor_minimo": null, "inicio": null, "fim": "2026-11-30T23:59:59-03:00", "ativo": true, "criado_em": "2026-10-28T02:52:31-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "" }, "tipo": { "type": "string", "description": "leve_pague, progressivo ou valor." }, "leve": { "type": "integer", "description": "leve_pague: leve (2 a 99)." }, "pague": { "type": "integer", "description": "leve_pague: pague (menor que leve)." }, "quantidade_minima": { "type": "integer", "description": "progressivo: a partir de quantas unidades." }, "percentual": { "type": "number", "description": "progressivo e valor: % de desconto." }, "valor_minimo": { "type": "number", "description": "valor: a partir de quantos reais." }, "categorias": { "type": "array", "items": { "type": "integer" }, "description": "Só nestas categorias." }, "inicio": { "type": "string", "description": "" }, "fim": { "type": "string", "description": "" }, "ativo": { "type": "boolean", "description": "Padrão true." } }, "required": [ "nome", "tipo" ] }, "example": { "nome": "Leve 3 pague 2", "tipo": "leve_pague", "leve": 3, "pague": 2, "fim": "2026-11-30T23:59:59-03:00" } } } } } }, "/promocoes/{id}": { "get": { "tags": [ "Marketing" ], "summary": "Obter Promoção", "description": "Retorna uma promoção. Escopo: marketing.ler", "operationId": "obter_promocao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do promoção." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 98, "nome": "Leve 3 pague 2", "tipo": "leve_pague", "categorias": [], "leve": 3, "pague": 2, "quantidade_minima": null, "percentual": null, "valor_minimo": null, "inicio": null, "fim": "2026-11-30T23:59:59-03:00", "ativo": true, "criado_em": "2026-10-28T02:52:31-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Marketing" ], "summary": "Editar Promoção", "description": "Altera só os campos enviados. Escopo: marketing.escrever", "operationId": "editar_promocao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do promoção." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 98, "nome": "Leve 3 pague 2", "tipo": "leve_pague", "categorias": [], "leve": 3, "pague": 2, "quantidade_minima": null, "percentual": null, "valor_minimo": null, "inicio": null, "fim": "2026-11-30T23:59:59-03:00", "ativo": false, "criado_em": "2026-10-28T02:52:31-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "ativo": false } } } } }, "delete": { "tags": [ "Marketing" ], "summary": "Apagar Promoção", "description": "Remove a promoção. Escopo: marketing.escrever", "operationId": "apagar_promocao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do promoção." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/avisos-estoque": { "get": { "tags": [ "Marketing" ], "summary": "Avisos de Estoque", "description": "Pedidos de \"avise-me quando chegar\". Escopo: marketing.ler", "operationId": "avisos_estoque", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "produto_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "pendentes", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true = só quem ainda não foi avisado." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 9, "produto_id": 2291, "email": "leitor@exemplo.com.br", "cliente_id": null, "criado_em": "2026-10-25T14:00:00-03:00", "avisado_em": null } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/clientes/{id}/cashback": { "get": { "tags": [ "Fidelidade" ], "summary": "Saldo de Cashback", "description": "Saldo e extrato de cashback do cliente. Escopo: fidelidade.ler", "operationId": "obter_cashback", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "cliente_id": 512, "saldo": 14.5, "programa_ativo": true, "percentual": 5.0, "validade_dias": 90, "extrato": [ { "id": 102, "tipo": "uso", "valor": -5.5, "restante": 0.0, "pedido_id": null, "expira_em": null, "criado_em": "2026-10-28T02:52:32-03:00" }, { "id": 101, "tipo": "credito", "valor": 20.0, "restante": 14.5, "pedido_id": null, "expira_em": "2027-01-26T02:52:32-03:00", "criado_em": "2026-10-28T02:52:32-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "post": { "tags": [ "Fidelidade" ], "summary": "Lançar Cashback", "description": "Crédito (bônus) ou débito manual no saldo do cliente. Escopo: fidelidade.escrever", "operationId": "lancar_cashback", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "cliente_id": 512, "saldo": 14.5, "programa_ativo": true, "percentual": 5.0, "validade_dias": 90, "extrato": [ { "id": 102, "tipo": "uso", "valor": -5.5, "restante": 0.0, "pedido_id": null, "expira_em": null, "criado_em": "2026-10-28T02:52:32-03:00" }, { "id": 101, "tipo": "credito", "valor": 20.0, "restante": 14.5, "pedido_id": null, "expira_em": "2027-01-26T02:52:32-03:00", "criado_em": "2026-10-28T02:52:32-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tipo": { "type": "string", "description": "credito ou debito." }, "valor": { "type": "number", "description": "Em reais." }, "validade_dias": { "type": "integer", "description": "Só no crédito. Padrão: a validade do programa." } }, "required": [ "tipo", "valor" ] }, "example": { "tipo": "credito", "valor": 20, "validade_dias": 60 } } } } } }, "/cartoes-presente": { "get": { "tags": [ "Fidelidade" ], "summary": "Listar Cartões-presente", "description": "Cartões emitidos e saldos. Escopo: fidelidade.ler", "operationId": "listar_cartoes", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "codigo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 2, "codigo": "7W89-9DLS-962X", "valor": 50.0, "saldo": 50.0, "email": "presenteado@exemplo.com.br", "nome": "Joana", "pedido_origem_id": null, "cancelado": false, "criado_em": "2026-10-28T02:52:32-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Fidelidade" ], "summary": "Emitir Cartão-presente", "description": "Gera um código com saldo (enviado por e-mail). Escopo: fidelidade.escrever", "operationId": "emitir_cartao", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2, "codigo": "7W89-9DLS-962X", "valor": 50.0, "saldo": 50.0, "email": "presenteado@exemplo.com.br", "nome": "Joana", "pedido_origem_id": null, "cancelado": false, "criado_em": "2026-10-28T02:52:32-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "valor": { "type": "number", "description": "De 1 a 10.000 reais." }, "email": { "type": "string", "description": "Recebe o código por e-mail." }, "nome": { "type": "string", "description": "" } }, "required": [ "valor" ] }, "example": { "valor": 50, "email": "presenteado@exemplo.com.br", "nome": "Joana" } } } } } }, "/cartoes-presente/{id}": { "get": { "tags": [ "Fidelidade" ], "summary": "Obter Cartão-presente", "description": "Retorna um cartão. Escopo: fidelidade.ler", "operationId": "obter_cartao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cartão." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2, "codigo": "7W89-9DLS-962X", "valor": 50.0, "saldo": 50.0, "email": "presenteado@exemplo.com.br", "nome": "Joana", "pedido_origem_id": null, "cancelado": false, "criado_em": "2026-10-28T02:52:32-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "delete": { "tags": [ "Fidelidade" ], "summary": "Cancelar Cartão-presente", "description": "O código deixa de valer. Escopo: fidelidade.escrever", "operationId": "cancelar_cartao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cartão." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/avaliacoes": { "get": { "tags": [ "Avaliações" ], "summary": "Listar Avaliações", "description": "Avaliações dos produtos. Escopo: avaliacoes.ler", "operationId": "listar_avaliacoes", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pendente, publicada ou recusada." }, { "name": "produto_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 626, "produto_id": 2271, "cliente_id": 512, "pedido_id": 2150, "nome": "André S.", "nota": 4, "titulo": "Muito útil", "comentario": "Luz quente e não incomoda quem dorme do lado.", "resposta": null, "status": "publicada", "criado_em": "2026-09-18T22:49:56-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/avaliacoes/{id}": { "get": { "tags": [ "Avaliações" ], "summary": "Obter Avaliação", "description": "Retorna uma avaliação. Escopo: avaliacoes.ler", "operationId": "obter_avaliacao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do avaliação." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 626, "produto_id": 2271, "cliente_id": 512, "pedido_id": 2150, "nome": "André S.", "nota": 4, "titulo": "Muito útil", "comentario": "Luz quente e não incomoda quem dorme do lado.", "resposta": null, "status": "publicada", "criado_em": "2026-09-18T22:49:56-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Avaliações" ], "summary": "Moderar Avaliação", "description": "Publica, recusa ou responde. Escopo: avaliacoes.escrever", "operationId": "moderar_avaliacao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do avaliação." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 626, "produto_id": 2271, "cliente_id": 512, "pedido_id": 2150, "nome": "André S.", "nota": 4, "titulo": "Muito útil", "comentario": "Luz quente e não incomoda quem dorme do lado.", "resposta": "Obrigado, André! Boa leitura.", "status": "publicada", "criado_em": "2026-09-18T22:49:56-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "publicada ou recusada." }, "resposta": { "type": "string", "description": "Resposta pública da loja (vazio apaga)." } }, "required": [] }, "example": { "status": "publicada", "resposta": "Obrigado, André! Boa leitura." } } } } } }, "/perguntas": { "get": { "tags": [ "Avaliações" ], "summary": "Listar Perguntas", "description": "Perguntas feitas nas páginas dos produtos. Escopo: avaliacoes.ler", "operationId": "listar_perguntas", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pendente, respondida ou recusada." }, { "name": "produto_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 88, "produto_id": 2291, "cliente_id": null, "nome": "Rafael", "email": "rafael@exemplo.com.br", "pergunta": "Tem em capa dura?", "resposta": "Tem sim, na opção Capa dura.", "status": "respondida", "criado_em": "2026-10-20T10:02:11-03:00", "respondida_em": "2026-10-20T11:15:40-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/perguntas/{id}": { "get": { "tags": [ "Avaliações" ], "summary": "Obter Pergunta", "description": "Retorna uma pergunta. Escopo: avaliacoes.ler", "operationId": "obter_pergunta", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pergunta." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 88, "produto_id": 2291, "cliente_id": null, "nome": "Rafael", "email": "rafael@exemplo.com.br", "pergunta": "Tem em capa dura?", "resposta": "Tem sim, na opção Capa dura.", "status": "respondida", "criado_em": "2026-10-20T10:02:11-03:00", "respondida_em": "2026-10-20T11:15:40-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/perguntas/{id}/resposta": { "post": { "tags": [ "Avaliações" ], "summary": "Responder Pergunta", "description": "Publica a resposta e avisa quem perguntou. Escopo: avaliacoes.escrever", "operationId": "responder_pergunta", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pergunta." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 88, "produto_id": 2291, "cliente_id": null, "nome": "Rafael", "email": "rafael@exemplo.com.br", "pergunta": "Tem em capa dura?", "resposta": "Tem sim, na opção Capa dura.", "status": "respondida", "criado_em": "2026-10-20T10:02:11-03:00", "respondida_em": "2026-10-20T11:15:40-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "resposta": { "type": "string", "description": "Até 2000 caracteres." } }, "required": [ "resposta" ] }, "example": { "resposta": "Tem sim, na opção Capa dura." } } } } } }, "/perguntas/{id}/recusar": { "post": { "tags": [ "Avaliações" ], "summary": "Recusar Pergunta", "description": "A pergunta não aparece no produto. Escopo: avaliacoes.escrever", "operationId": "recusar_pergunta", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pergunta." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 88, "produto_id": 2291, "cliente_id": null, "nome": "Rafael", "email": "rafael@exemplo.com.br", "pergunta": "Tem em capa dura?", "resposta": null, "status": "recusada", "criado_em": "2026-10-20T10:02:11-03:00", "respondida_em": null } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/produtos/{id}/kit": { "get": { "tags": [ "Produtos" ], "summary": "Obter Kit", "description": "Componentes do produto vendido como kit. Escopo: produtos.ler", "operationId": "obter_kit", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "produto_id": 2300, "componentes": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "sku": "LIV-001", "quantidade": 1 }, { "produto_id": 2295, "nome": "Marcador de páginas", "sku": "ACE-004", "quantidade": 2 } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "put": { "tags": [ "Produtos" ], "summary": "Definir Kit", "description": "Define os componentes (vender o kit baixa os componentes). Escopo: produtos.escrever", "operationId": "gravar_kit", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "produto_id": 2300, "componentes": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "sku": "LIV-001", "quantidade": 1 }, { "produto_id": 2295, "nome": "Marcador de páginas", "sku": "ACE-004", "quantidade": 2 } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "componentes": { "type": "array", "items": { "type": "object" }, "description": "[{ produto_id ou sku, quantidade (1 a 99) }] (até 30). Lista vazia: deixa de ser kit." } }, "required": [ "componentes" ] }, "example": { "componentes": [ { "sku": "LIV-001", "quantidade": 1 }, { "sku": "ACE-004", "quantidade": 2 } ] } } } } } }, "/blog": { "get": { "tags": [ "Conteúdo" ], "summary": "Listar Posts do Blog", "description": "Posts do blog da loja. Escopo: conteudo.ler", "operationId": "listar_blog", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "publicado", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 320, "titulo": "Como escolher o próximo livro", "slug": "como-escolher-o-proximo-livro", "resumo": "Cinco perguntas que ajudam na escolha.", "conteudo": "Texto do post...", "capa": null, "publicado": true, "publicado_em": "2026-10-28T09:00:00-03:00", "url": "https://demo73.hoteldaslojas.com.br/blog/como-escolher-o-proximo-livro", "atualizado_em": "2026-10-28T02:52:34-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Conteúdo" ], "summary": "Criar Post", "description": "Cria um post. Escopo: conteudo.escrever", "operationId": "criar_post", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Como escolher o próximo livro", "slug": "como-escolher-o-proximo-livro", "resumo": "Cinco perguntas que ajudam na escolha.", "conteudo": "Texto do post...", "capa": null, "publicado": true, "publicado_em": "2026-10-28T09:00:00-03:00", "url": "https://demo73.hoteldaslojas.com.br/blog/como-escolher-o-proximo-livro", "atualizado_em": "2026-10-28T02:52:34-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titulo": { "type": "string", "description": "Até 140." }, "conteudo": { "type": "string", "description": "Texto simples (mínimo 20 caracteres): parágrafos separados por linha em branco, listas com \"- \"." }, "slug": { "type": "string", "description": "Endereço. Padrão: gerado do título." }, "resumo": { "type": "string", "description": "Até 300." }, "capa": { "type": "string", "description": "URL da imagem ou { \"base64\": \"...\" }. null remove." }, "publicado": { "type": "boolean", "description": "Padrão false (rascunho)." }, "publicado_em": { "type": "string", "description": "Data futura agenda a publicação." } }, "required": [ "titulo", "conteudo" ] }, "example": { "titulo": "Como escolher o próximo livro", "resumo": "Cinco perguntas que ajudam na escolha.", "conteudo": "Primeiro parágrafo do post.\n\n- dica um\n- dica dois", "publicado": true } } } } } }, "/blog/{id}": { "get": { "tags": [ "Conteúdo" ], "summary": "Obter Post", "description": "Retorna um post. Escopo: conteudo.ler", "operationId": "obter_post", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do post." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Como escolher o próximo livro", "slug": "como-escolher-o-proximo-livro", "resumo": "Cinco perguntas que ajudam na escolha.", "conteudo": "Texto do post...", "capa": null, "publicado": true, "publicado_em": "2026-10-28T09:00:00-03:00", "url": "https://demo73.hoteldaslojas.com.br/blog/como-escolher-o-proximo-livro", "atualizado_em": "2026-10-28T02:52:34-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Conteúdo" ], "summary": "Editar Post", "description": "Altera só os campos enviados. Escopo: conteudo.escrever", "operationId": "editar_post", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do post." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Como escolher o próximo livro", "slug": "como-escolher-o-proximo-livro", "resumo": "Cinco perguntas que ajudam na escolha.", "conteudo": "Texto do post...", "capa": null, "publicado": true, "publicado_em": "2026-10-28T09:00:00-03:00", "url": "https://demo73.hoteldaslojas.com.br/blog/como-escolher-o-proximo-livro", "atualizado_em": "2026-10-28T02:52:34-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "publicado": false } } } } }, "delete": { "tags": [ "Conteúdo" ], "summary": "Apagar Post", "description": "Remove o post. Escopo: conteudo.escrever", "operationId": "apagar_post", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do post." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/banners": { "get": { "tags": [ "Conteúdo" ], "summary": "Listar Banners", "description": "Banners do carrossel da página inicial. Escopo: conteudo.ler", "operationId": "listar_banners", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 188, "titulo": "Semana do livro", "imagem_desktop": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "imagem_mobile": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "link": "/categoria?filtro=4", "ativo": true, "ordem": 0, "inicio": null, "fim": "2026-11-07T23:59:59-03:00", "criado_em": "2026-10-28T02:52:35-03:00", "atualizado_em": "2026-10-28T02:52:35-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Conteúdo" ], "summary": "Criar Banner", "description": "Cria um banner. Escopo: conteudo.escrever", "operationId": "criar_banner", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 188, "titulo": "Semana do livro", "imagem_desktop": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "imagem_mobile": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "link": "/categoria?filtro=4", "ativo": true, "ordem": 0, "inicio": null, "fim": "2026-11-07T23:59:59-03:00", "criado_em": "2026-10-28T02:52:35-03:00", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titulo": { "type": "string", "description": "" }, "imagem_desktop": { "type": "string", "description": "URL da imagem ou { \"base64\": \"...\" }." }, "imagem_mobile": { "type": "string", "description": "Padrão: a de desktop." }, "link": { "type": "string", "description": "https://... ou caminho da loja (/categoria...)." }, "ativo": { "type": "boolean", "description": "Padrão true." }, "ordem": { "type": "integer", "description": "" }, "inicio": { "type": "string", "description": "" }, "fim": { "type": "string", "description": "" } }, "required": [ "titulo", "imagem_desktop" ] }, "example": { "titulo": "Semana do livro", "imagem_desktop": "https://cdn.seuerp.com.br/banners/semana-livro.jpg", "link": "/categoria?filtro=4", "fim": "2026-11-07T23:59:59-03:00" } } } } } }, "/banners/{id}": { "get": { "tags": [ "Conteúdo" ], "summary": "Obter Banner", "description": "Retorna um banner. Escopo: conteudo.ler", "operationId": "obter_banner", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do banner." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 188, "titulo": "Semana do livro", "imagem_desktop": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "imagem_mobile": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "link": "/categoria?filtro=4", "ativo": true, "ordem": 0, "inicio": null, "fim": "2026-11-07T23:59:59-03:00", "criado_em": "2026-10-28T02:52:35-03:00", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Conteúdo" ], "summary": "Editar Banner", "description": "Altera só os campos enviados. Escopo: conteudo.escrever", "operationId": "editar_banner", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do banner." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 188, "titulo": "Semana do livro", "imagem_desktop": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "imagem_mobile": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-0252351a21f05ad7.webp", "link": "/categoria?filtro=4", "ativo": true, "ordem": 0, "inicio": null, "fim": "2026-11-07T23:59:59-03:00", "criado_em": "2026-10-28T02:52:35-03:00", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "ativo": false } } } } }, "delete": { "tags": [ "Conteúdo" ], "summary": "Apagar Banner", "description": "Remove o banner. Escopo: conteudo.escrever", "operationId": "apagar_banner", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do banner." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/paginas": { "get": { "tags": [ "Conteúdo" ], "summary": "Listar Páginas", "description": "Páginas institucionais. Escopo: conteudo.ler", "operationId": "listar_paginas", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 320, "titulo": "Trocas e devoluções", "slug": "trocas-e-devolucoes", "conteudo": "Você pode trocar em até 7 dias...", "ativa": true, "ordem": 0, "url": "https://demo73.hoteldaslojas.com.br/pagina/trocas-e-devolucoes", "atualizado_em": "2026-10-28T02:52:35-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Conteúdo" ], "summary": "Criar Página", "description": "Cria uma página. Escopo: conteudo.escrever", "operationId": "criar_pagina", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Trocas e devoluções", "slug": "trocas-e-devolucoes", "conteudo": "Você pode trocar em até 7 dias...", "ativa": true, "ordem": 0, "url": "https://demo73.hoteldaslojas.com.br/pagina/trocas-e-devolucoes", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titulo": { "type": "string", "description": "Até 120." }, "conteudo": { "type": "string", "description": "Texto simples (mínimo 20 caracteres)." }, "slug": { "type": "string", "description": "" }, "ativa": { "type": "boolean", "description": "Padrão true." }, "ordem": { "type": "integer", "description": "" } }, "required": [ "titulo", "conteudo" ] }, "example": { "titulo": "Trocas e devoluções", "conteudo": "Você pode trocar em até 7 dias depois de receber o pedido." } } } } } }, "/paginas/{id}": { "get": { "tags": [ "Conteúdo" ], "summary": "Obter Página", "description": "Retorna uma página. Escopo: conteudo.ler", "operationId": "obter_pagina", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Trocas e devoluções", "slug": "trocas-e-devolucoes", "conteudo": "Você pode trocar em até 7 dias...", "ativa": true, "ordem": 0, "url": "https://demo73.hoteldaslojas.com.br/pagina/trocas-e-devolucoes", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } }, "patch": { "tags": [ "Conteúdo" ], "summary": "Editar Página", "description": "Altera só os campos enviados. Escopo: conteudo.escrever", "operationId": "editar_pagina", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do página." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 320, "titulo": "Trocas e devoluções", "slug": "trocas-e-devolucoes", "conteudo": "Você pode trocar em até 7 dias...", "ativa": true, "ordem": 0, "url": "https://demo73.hoteldaslojas.com.br/pagina/trocas-e-devolucoes", "atualizado_em": "2026-10-28T02:52:35-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "ativa": false } } } } }, "delete": { "tags": [ "Conteúdo" ], "summary": "Apagar Página", "description": "Remove a página. Escopo: conteudo.escrever", "operationId": "apagar_pagina", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do página." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/relatorios/resumo": { "get": { "tags": [ "Relatórios" ], "summary": "Resumo de Vendas", "description": "Faturamento, ticket médio, itens, clientes novos e pedidos por status. Escopo: relatorios.ler", "operationId": "resumo", "security": [ { "chave": [] } ], "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Início (padrão: 30 dias antes de ate)." }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fim (padrão: hoje). Período máximo de 366 dias." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "desde": "2026-09-29T00:00:00-03:00", "ate": "2026-10-28T23:59:59-03:00", "pedidos": 142, "pedidos_cancelados": 6, "faturamento": 18342.7, "faturamento_pago": 17120.4, "ticket_medio": 129.17, "descontos": 812.3, "fretes": 2104.5, "itens_vendidos": 311, "clientes_novos": 58, "pedidos_por_status": { "concluido": 101, "enviado": 17, "pago": 9, "pendente": 9, "cancelado": 6 } } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/relatorios/vendas": { "get": { "tags": [ "Relatórios" ], "summary": "Vendas por Período", "description": "Pedidos e faturamento por dia, semana ou mês. Escopo: relatorios.ler", "operationId": "vendas", "security": [ { "chave": [] } ], "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Início (padrão: 30 dias antes de ate)." }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fim (padrão: hoje). Período máximo de 366 dias." }, { "name": "agrupar", "in": "query", "required": false, "schema": { "type": "string" }, "description": "dia (padrão), semana ou mes." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "periodo": "2026-10-26", "pedidos": 6, "faturamento": 812.4, "ticket_medio": 135.4 }, { "periodo": "2026-10-27", "pedidos": 4, "faturamento": 488.6, "ticket_medio": 122.15 } ], "periodo": { "desde": "2026-10-26T00:00:00-03:00", "ate": "2026-10-27T23:59:59-03:00", "agrupar": "dia" } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/relatorios/produtos-mais-vendidos": { "get": { "tags": [ "Relatórios" ], "summary": "Produtos Mais Vendidos", "description": "Ranking por quantidade ou faturamento. Escopo: relatorios.ler", "operationId": "produtos_mais_vendidos", "security": [ { "chave": [] } ], "parameters": [ { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Início (padrão: 30 dias antes de ate)." }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fim (padrão: hoje). Período máximo de 366 dias." }, { "name": "limite", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "De 1 a 100 (padrão 20)." }, { "name": "ordem", "in": "query", "required": false, "schema": { "type": "string" }, "description": "quantidade (padrão) ou faturamento." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "produto_id": 2291, "nome": "O Farol das Horas Quietas", "sku": "LIV-001", "quantidade": 37, "faturamento": 2216.3, "pedidos": 33 } ], "periodo": { "desde": "2026-09-29T00:00:00-03:00", "ate": "2026-10-28T23:59:59-03:00" } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/estoque/movimentos": { "get": { "tags": [ "Relatórios" ], "summary": "Movimentos de Estoque", "description": "Entradas, saídas, vendas, devoluções e contagens. Escopo: relatorios.ler", "operationId": "movimentos_estoque", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "produto_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "entrada, saida, pedido, devolucao ou inventario." }, { "name": "pedido_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 691, "produto_id": 2291, "quantidade": -3, "saldo_depois": 9, "tipo": "pedido", "pedido_id": 2180, "motivo": "Pedido #2180 (API)", "em": "2026-10-28T02:53:20-03:00" }, { "id": 690, "produto_id": 2291, "quantidade": 2, "saldo_depois": 12, "tipo": "inventario", "pedido_id": null, "motivo": "Inventário do ERP (API) (contado: 12)", "em": "2026-10-28T02:52:20-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 2, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/marketplaces/produtos": { "get": { "tags": [ "Relatórios" ], "summary": "Anúncios nos Marketplaces", "description": "Situação de cada produto em cada canal. Escopo: relatorios.ler", "operationId": "marketplaces_produtos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "canal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Ex.: mercadolivre, shopee." }, { "name": "produto_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "" }, { "name": "situacao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "canal": "mercadolivre", "produto_id": 2291, "publicar": true, "id_anuncio": "MLB4012345678", "link": "https://produto.mercadolivre.com.br/MLB-4012345678", "situacao": "ativo", "erro": null, "preco_enviado": 64.9, "estoque_enviado": 9, "sincronizacao_pendente": false, "atualizado_em": "2026-10-28T02:40:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/marketplaces/pedidos": { "get": { "tags": [ "Relatórios" ], "summary": "Pedidos dos Marketplaces", "description": "Pedidos importados dos canais e o número na loja. Escopo: relatorios.ler", "operationId": "marketplaces_pedidos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "canal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "situacao", "in": "query", "required": false, "schema": { "type": "string" }, "description": "importado ou erro." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "canal": "mercadolivre", "id_externo": "2000009876543", "pedido_id": 2177, "situacao": "importado", "erro": null, "importado_em": "2026-10-27T11:20:00-03:00", "atualizado_em": "2026-10-27T11:20:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/chave": { "get": { "tags": [ "Loja" ], "summary": "Obter Chave", "description": "Mostra a loja e os escopos da chave usada na chamada. Escopo: (qualquer chave)", "operationId": "obter_chave", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "nome": "ERP da loja", "prefixo": "hdl_live_1f12ffe", "loja_id": 220, "loja": "Página Dobrada", "escopos": [ "pedidos.ler", "pedidos.escrever", "estoque.escrever" ], "criada_em": "2026-10-28T03:23:00-03:00", "limite_por_minuto": 120 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } } } } }, "/pagamentos/meios": { "get": { "tags": [ "Pagamentos" ], "summary": "Meios de Pagamento", "description": "Aplicativos de pagamento instalados e formas da própria loja. Escopo: pagamentos.ler", "operationId": "meios_pagamento", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "aplicativos": [ { "meio": "asaas", "nome": "Asaas", "codigo_forma": "24", "no_checkout": true, "configurado": true, "gera_link": true, "modo_teste": false, "ultimo_erro": null } ], "formas_da_loja": [ { "forma": "pix", "nome": "Pix (chave da loja)" }, { "forma": "mercadopago", "nome": "Mercado Pago (checkout da loja)" }, { "forma": "credito_entrega", "nome": "Cartão de crédito na entrega ou retirada" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/pedidos/{id}/cobranca": { "post": { "tags": [ "Pagamentos" ], "summary": "Gerar Link de Pagamento", "description": "Cria a cobrança no meio escolhido e devolve o link para o cliente pagar. Escopo: pagamentos.cobrar", "operationId": "gerar_cobranca", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "pedido_id": 2181, "meio": "asaas", "link": "https://www.asaas.com/c/8x2k4m9p1q", "codigo": "pay_8x2k4m9p1q", "valor": 59.9 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "meio": { "type": "string", "description": "paypal, stripe, pagarme, cielo, asaas, iugu ou picpay (instalado, ligado e configurado na loja)." } }, "required": [ "meio" ] }, "example": { "meio": "asaas" } } } } } }, "/pedidos/{id}/rastreamento": { "get": { "tags": [ "Pedidos" ], "summary": "Rastreamento do Pedido", "description": "Linha do tempo da entrega (Correios). Escopo: pedidos.ler", "operationId": "rastreamento", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "pedido_id": 2180, "codigo": "AA123456789BR", "transportadora": "correios", "link": "https://www.melhorrastreio.com.br/rastreio/AA123456789BR", "eventos": [ { "em": "2026-10-29T14:02:00-03:00", "descricao": "Objeto saiu para entrega ao destinatário", "detalhe": null, "local": "São Paulo / SP" }, { "em": "2026-10-28T18:40:00-03:00", "descricao": "Objeto postado", "detalhe": null, "local": "Curitiba / PR" } ], "situacao_entrega": "em_transito" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/pedidos/{id}/dropshipping": { "get": { "tags": [ "Pedidos" ], "summary": "Dropshipping do Pedido", "description": "Situação do pedido no fornecedor (AliExpress). Escopo: pedidos.ler", "operationId": "dropshipping_pedido", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do pedido." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "pedido_id": 2179, "enviado_ao_fornecedor": true, "pedido_aliexpress": "8199912345678901", "situacao": "enviado", "rastreio": "LP00123456789CN", "erro": null, "atualizado_em": "2026-10-28T10:00:00-03:00", "itens": [ { "produto_id": 2301, "nome": "Luminária de leitura", "quantidade": 1, "produto_aliexpress": "1005004567890123", "custo": 32.5 } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/dropshipping/produtos": { "get": { "tags": [ "Produtos" ], "summary": "Produtos de Dropshipping", "description": "Produtos importados do AliExpress com custo e SKU do fornecedor. Escopo: produtos.ler", "operationId": "dropshipping_produtos", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "produto_id": 2301, "nome": "Luminária de leitura", "sku": "AE1005004567890123", "preco_venda": 69.9, "produto_aliexpress": "1005004567890123", "sku_aliexpress": "14:193#Branca", "custo": 32.5, "atualizado_em": "2026-10-20T11:00:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/produtos/{id}/duplicar": { "post": { "tags": [ "Produtos" ], "summary": "Duplicar Produto", "description": "Copia dados, variações e imagens. Escopo: produtos.escrever", "operationId": "duplicar_produto", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do produto." } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 2496, "sku": "LIV-001", "nome": "O Farol das Horas Quietas", "descricao": "", "marca": "Página Dobrada", "categoria_id": 783, "preco": 59.9, "preco_promocional": 39.9, "preco_final": 39.9, "ativo": true, "visivel": false, "estoque": { "controlado": true, "quantidade": 7, "minimo": 0 }, "peso_kg": 0.0, "dimensoes_cm": { "altura": 0.0, "largura": 0.0, "comprimento": 0.0 }, "imagens": [], "variacoes": [ { "nome": "Edição", "escolha_minima": 1, "escolha_maxima": 1, "opcoes": [ { "nome": "Brochura", "descricao": "", "valor_adicional": 0.0, "cor": null, "estoque": null, "sku": null }, { "nome": "Capa dura", "descricao": "", "valor_adicional": 20.0, "cor": null, "estoque": 4, "sku": "LIV-001-CD" } ] } ], "url": "https://demo73.hoteldaslojas.com.br/produto/2496-livro-teste-api", "criado_em": "2026-10-28T00:43:26-03:00", "atualizado_em": "2026-10-28T00:43:29-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Padrão: o nome com \" (cópia)\"." }, "sku": { "type": "string", "description": "Padrão: REF-{id}." }, "ativo": { "type": "boolean", "description": "Padrão false: a cópia nasce desativada." } }, "required": [] }, "example": { "sku": "LIV-001-BOX" } } } } } }, "/marketplaces/sincronizar": { "post": { "tags": [ "Produtos" ], "summary": "Sincronizar com Marketplaces", "description": "Reenvia preço, estoque e dados aos canais (ou publica/despublica). Escopo: produtos.escrever", "operationId": "sincronizar_marketplaces", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "indice": 0, "id": 2291, "ok": true }, { "indice": 1, "id": 2292, "ok": true } ], "resumo": { "total": 2, "atualizados": 2, "com_erro": 0 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "produtos": { "type": "array", "items": { "type": "integer" }, "description": "ids dos produtos (até 100)." }, "canal": { "type": "string", "description": "mercadolivre, shopee, amazon, magalu, tiktok, shein, americanas, casasbahia, google ou meta." }, "publicar": { "type": "boolean", "description": "Com canal: true publica, false tira o anúncio do canal." } }, "required": [ "produtos" ] }, "example": { "produtos": [ 2291, 2292 ], "canal": "mercadolivre", "publicar": true } } } } } }, "/aplicativos": { "get": { "tags": [ "Aplicativos" ], "summary": "Listar Aplicativos", "description": "Todos os aplicativos da loja e a situação de cada um. Escopo: aplicativos.ler", "operationId": "listar_aplicativos", "security": [ { "chave": [] } ], "parameters": [ { "name": "categoria", "in": "query", "required": false, "schema": { "type": "string" }, "description": "vendas, logistica, dropshipping, pagamento, frete ou marketplace." }, { "name": "instalado", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true = só os instalados." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "slug": "compre-junto", "nome": "Compre junto", "categoria": "vendas", "descricao": "Combos na página do produto, com desconto para quem leva os produtos juntos.", "instalado": true, "ativo": true, "regras_pela_api": true }, { "slug": "mercado-livre", "nome": "Mercado Livre", "categoria": "marketplace", "descricao": "Anúncios, estoque, preço e pedidos sincronizados.", "instalado": true, "ativo": true, "regras_pela_api": false, "canal": "mercadolivre" }, { "slug": "melhor-envio", "nome": "Melhor Envio", "categoria": "frete", "descricao": "Cota Correios, Jadlog, Loggi...", "instalado": true, "ativo": true, "regras_pela_api": false } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/aplicativos/{slug}": { "get": { "tags": [ "Aplicativos" ], "summary": "Obter Aplicativo", "description": "Situação do aplicativo e, nos de vendas e frete, as regras. Escopo: aplicativos.ler", "operationId": "obter_aplicativo", "security": [ { "chave": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Ex.: compre-junto, gestor-de-frete, mercado-livre, asaas." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "slug": "compre-junto", "nome": "Compre junto", "categoria": "vendas", "descricao": "Combos na página do produto, com desconto para quem leva os produtos juntos.", "instalado": true, "ativo": true, "regras_pela_api": true, "configuracao": { "regras": [ { "nome": "Combo leitura", "produto_id": 2291, "itens": [ 2268 ], "desconto_percentual": 10.0 } ] } } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/aplicativos/{slug}/regras": { "put": { "tags": [ "Aplicativos" ], "summary": "Definir Regras do Aplicativo", "description": "Substitui as regras de um aplicativo de vendas ou do gestor de frete. Escopo: aplicativos.escrever", "operationId": "regras_aplicativo", "security": [ { "chave": [] } ], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "compre-junto, brinde-por-valor, brinde-por-produto, limitacao-de-compra, gestor-de-frete ou cartao-presente." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "slug": "compre-junto", "nome": "Compre junto", "categoria": "vendas", "descricao": "Combos na página do produto, com desconto para quem leva os produtos juntos.", "instalado": true, "ativo": true, "regras_pela_api": true, "configuracao": { "regras": [ { "nome": "Combo leitura", "produto_id": 2291, "itens": [ 2268 ], "desconto_percentual": 10.0 } ] } } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "409": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "conflito", "mensagem": "Veja os códigos 409 possíveis deste endpoint em Erros.", "request_id": "req_63b517aca214d1a4" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "regras": { "type": "array", "items": { "type": "object" }, "description": "compre-junto: { nome, produto_id, itens: [produto_id], desconto_percentual (até 90) }. brinde-por-produto: { produto_id, quantidade, brinde_produto_id }. limitacao-de-compra: { produto_id, minimo, maximo, maximo_por_cliente }. gestor-de-frete: { nome, cep_inicio, cep_fim, peso_min, peso_max, valor_min, valor_max, preco, gratis_acima, prazo_dias }." }, "faixas": { "type": "array", "items": { "type": "object" }, "description": "brinde-por-valor: { valor_minimo, brinde_produto_id }." }, "produtos": { "type": "array", "items": { "type": "integer" }, "description": "cartao-presente: produtos que viram cartão-presente quando vendidos." }, "gerais": { "type": "object", "description": "limitacao-de-compra: { minimo_itens_pedido, maximo_itens_pedido, minimo_por_produto, maximo_por_produto } (0 = sem limite)." } }, "required": [] }, "example": { "regras": [ { "nome": "Combo leitura", "produto_id": 2291, "itens": [ 2268 ], "desconto_percentual": 10 } ] } } } } } }, "/frete/entrega-local": { "get": { "tags": [ "Frete" ], "summary": "Listar Entrega Local", "description": "Taxas por região e outras opções de entrega ou retirada. Escopo: frete.ler", "operationId": "listar_entrega_local", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "tipo", "in": "query", "required": false, "schema": { "type": "string" }, "description": "taxa_regiao ou outra_opcao." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 75, "nome": "Centro", "valor": 8.0, "tipo": "taxa_regiao", "link_direto": null }, { "id": 77, "nome": "Retirada no shopping", "valor": 0.0, "tipo": "outra_opcao", "link_direto": "https://demo73.hoteldaslojas.com.br/?local=77" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 2, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Frete" ], "summary": "Criar Entrega Local", "description": "Cria uma taxa por região ou outra opção de entrega. Escopo: frete.escrever", "operationId": "criar_entrega_local", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 77, "nome": "Retirada no shopping", "valor": 0.0, "tipo": "outra_opcao", "link_direto": "https://demo73.hoteldaslojas.com.br/?local=77" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Até 120." }, "valor": { "type": "number", "description": "0 = grátis." }, "tipo": { "type": "string", "description": "taxa_regiao (padrão) ou outra_opcao." } }, "required": [ "nome", "valor" ] }, "example": { "nome": "Retirada no shopping", "valor": 0, "tipo": "outra_opcao" } } } } } }, "/frete/entrega-local/{id}": { "patch": { "tags": [ "Frete" ], "summary": "Editar Entrega Local", "description": "Altera só os campos enviados. Escopo: frete.escrever", "operationId": "editar_entrega_local", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do opção." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 77, "nome": "Retirada no shopping", "valor": 5.0, "tipo": "outra_opcao", "link_direto": "https://demo73.hoteldaslojas.com.br/?local=77" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [] }, "example": { "valor": 5 } } } } }, "delete": { "tags": [ "Frete" ], "summary": "Apagar Entrega Local", "description": "Remove a opção. Escopo: frete.escrever", "operationId": "apagar_entrega_local", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do opção." } ], "responses": { "204": { "description": "Sucesso" }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/marketplaces/categorias": { "get": { "tags": [ "Relatórios" ], "summary": "Categorias nos Marketplaces", "description": "Ligação das categorias da loja com as de cada canal. Escopo: relatorios.ler", "operationId": "marketplaces_categorias", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "canal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "canal": "mercadolivre", "categoria_id": 711, "categoria_canal": "MLB1196", "categoria_canal_nome": "Livros, Revistas e Comics", "atualizado_em": "2026-10-20T09:00:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/marketplaces/log": { "get": { "tags": [ "Relatórios" ], "summary": "Registro dos Marketplaces", "description": "O que aconteceu em cada canal (publicações, erros, pedidos). Escopo: relatorios.ler", "operationId": "marketplaces_log", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "canal", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 512, "canal": "mercadolivre", "texto": "Pedido 2000009876543 importado como #2177", "em": "2026-10-27T11:20:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/relatorios/teste-ab": { "get": { "tags": [ "Relatórios" ], "summary": "Teste A/B da Vitrine", "description": "Vistas, cliques e taxa de clique de cada variante. Escopo: relatorios.ler", "operationId": "teste_ab", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "grupo": "banner-principal", "variante": "a", "vistas": 1200, "cliques": 84, "taxa_clique": 7.0 }, { "grupo": "banner-principal", "variante": "b", "vistas": 1185, "cliques": 110, "taxa_clique": 9.28 } ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/exportacoes/{tipo}": { "get": { "tags": [ "Relatórios" ], "summary": "Exportar Planilha", "description": "Pedidos, clientes ou produtos em CSV (abre no Excel). Escopo: relatorios.ler", "operationId": "exportacoes", "security": [ { "chave": [] } ], "parameters": [ { "name": "tipo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "pedidos, clientes ou produtos." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir desta data." }, { "name": "ate", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados até esta data." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": {} } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/cupons/{id}/usos": { "get": { "tags": [ "Cupons" ], "summary": "Usos do Cupom", "description": "Pedidos em que o cupom foi usado. Escopo: cupons.ler", "operationId": "usos_cupom", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cupom." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "pedido_id": 2175, "em": "2026-10-26T16:10:00-03:00", "status": "concluido", "cliente": { "id": 512, "nome": "Marina Duarte", "email": "marina@exemplo.com.br", "whatsapp": "41999990000", "documento": "" }, "desconto": 15.0, "total": 134.9 } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/cartoes-presente/{id}/usos": { "get": { "tags": [ "Fidelidade" ], "summary": "Usos do Cartão-presente", "description": "Pedidos que usaram o saldo do cartão. Escopo: fidelidade.ler", "operationId": "usos_cartao", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cartão." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 4, "pedido_id": 2176, "valor": 30.0, "estornado": false, "em": "2026-10-27T10:00:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/clientes/{id}/historico": { "get": { "tags": [ "Clientes" ], "summary": "Histórico do Cliente", "description": "Alterações no cadastro: campo, antes, depois e quem mudou. Escopo: clientes.ler", "operationId": "historico_cliente", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do cliente." }, { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "campo": "tags", "antes": "vip", "depois": "vip,atacado (API)", "por": "sistema", "em": "2026-10-28T02:52:30-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/emails": { "get": { "tags": [ "Configurações" ], "summary": "Listar E-mails", "description": "Avisos enviados aos clientes e o texto de cada um. Escopo: configuracoes.ler", "operationId": "listar_emails", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "tipo": "recebido", "nome": "Pedido recebido", "assunto": "Recebemos seu pedido #{pedido}", "texto": "Olá, {nome}!\nRecebemos seu pedido e a loja já foi avisada.", "ativo": true, "personalizado": false } ], "variaveis": [ "{nome}", "{pedido}", "{loja}", "{total}", "{rastreio}", "{produto}" ] } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/emails/{tipo}": { "put": { "tags": [ "Configurações" ], "summary": "Editar E-mail", "description": "Personaliza assunto e texto, ou liga e desliga o aviso. Escopo: configuracoes.escrever", "operationId": "editar_email", "security": [ { "chave": [] } ], "parameters": [ { "name": "tipo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Tipo do aviso (veja Listar E-mails)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "tipo": "recebido", "nome": "Pedido recebido", "assunto": "Recebemos seu pedido #{pedido}!", "texto": "Olá, {nome}!\nRecebemos seu pedido e a loja já foi avisada.", "ativo": true, "personalizado": true } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assunto": { "type": "string", "description": "3 a 150 caracteres." }, "texto": { "type": "string", "description": "3 a 3.000 caracteres, com as variáveis." }, "ativo": { "type": "boolean", "description": "false desliga o aviso." } }, "required": [] }, "example": { "assunto": "Recebemos seu pedido #{pedido}!", "ativo": true } } } } }, "delete": { "tags": [ "Configurações" ], "summary": "Restaurar E-mail Padrão", "description": "Volta o aviso ao texto padrão do Hotel das Lojas. Escopo: configuracoes.escrever", "operationId": "email_padrao", "security": [ { "chave": [] } ], "parameters": [ { "name": "tipo", "in": "path", "required": true, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "tipo": "recebido", "nome": "Pedido recebido", "assunto": "Recebemos seu pedido #{pedido}", "texto": "Olá, {nome}!\nRecebemos seu pedido e a loja já foi avisada.", "ativo": true, "personalizado": false } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } } } } }, "/configuracoes/regras-pedidos": { "get": { "tags": [ "Configurações" ], "summary": "Regras de Pedidos", "description": "Cancelamento automático de pedidos não pagos. Escopo: configuracoes.ler", "operationId": "obter_regras_pedidos", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "cancelar_nao_pagos_horas": 48, "ultimos_cancelados_automaticamente": [ { "pedido_id": 2160, "cancelado_em": "2026-10-25T08:00:00-03:00" } ] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "put": { "tags": [ "Configurações" ], "summary": "Editar Regras de Pedidos", "description": "Prazo para cancelar pedido com pagamento online pendente. Escopo: configuracoes.escrever", "operationId": "editar_regras_pedidos", "security": [ { "chave": [] } ], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "cancelar_nao_pagos_horas": 48, "ultimos_cancelados_automaticamente": [] } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelar_nao_pagos_horas": { "type": "integer", "description": "De 1 a 720 horas, ou null para não cancelar." } }, "required": [ "cancelar_nao_pagos_horas" ] }, "example": { "cancelar_nao_pagos_horas": 48 } } } } } }, "/equipe": { "get": { "tags": [ "Configurações" ], "summary": "Listar Equipe", "description": "Pessoas com acesso ao painel da loja. Escopo: configuracoes.ler", "operationId": "listar_equipe", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 3, "nome": "Carla", "email": "carla@exemplo.com.br", "funcao": "Atendimento", "ativo": true, "verificacao_em_duas_etapas": true, "ultimo_login": "2026-10-27T18:00:00-03:00", "criado_em": "2026-08-01T10:00:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/lgpd/solicitacoes": { "get": { "tags": [ "Configurações" ], "summary": "Solicitações LGPD", "description": "Pedidos de clientes sobre os próprios dados. Escopo: configuracoes.ler", "operationId": "lgpd", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "desde", "in": "query", "required": false, "schema": { "type": "string" }, "description": "" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 6, "cliente_id": 512, "tipo": "exportar", "em": "2026-10-20T09:30:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "400": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "json_invalido", "mensagem": "O corpo precisa ser um objeto JSON válido.", "request_id": "req_8f2a1c9d0b7e6f55" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } } }, "/midias": { "get": { "tags": [ "Mídias" ], "summary": "Listar Mídias", "description": "Biblioteca de imagens da loja. Escopo: midias.ler", "operationId": "listar_midias", "security": [ { "chave": [] } ], "parameters": [ { "name": "pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Página (padrão 1)." }, { "name": "por_pagina", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Itens por página, de 1 a 100 (padrão 20)." }, { "name": "busca", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Título, texto alternativo ou nome do arquivo." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": [ { "id": 4407, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-032333d61439b554.webp", "largura": 500, "altura": 333, "bytes": 8206, "titulo": "Vitrine de outubro", "alt": "Livros na vitrine", "legenda": "", "criado_em": "2026-10-28T03:23:33-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 20, "total": 1, "paginas": 1 } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } } } }, "post": { "tags": [ "Mídias" ], "summary": "Enviar Mídia", "description": "Envia uma imagem para a biblioteca da loja. Escopo: midias.escrever", "operationId": "enviar_midia", "security": [ { "chave": [] } ], "parameters": [], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 4407, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-032333d61439b554.webp", "largura": 500, "altura": 333, "bytes": 8206, "titulo": "Vitrine de outubro", "alt": "Livros na vitrine", "legenda": "", "criado_em": "2026-10-28T03:23:33-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Endereço público da imagem. Use url ou base64." }, "base64": { "type": "string", "description": "Conteúdo do arquivo." }, "titulo": { "type": "string", "description": "" }, "alt": { "type": "string", "description": "Texto alternativo (acessibilidade e Google)." }, "legenda": { "type": "string", "description": "" } }, "required": [] }, "example": { "url": "https://cdn.seuerp.com.br/fotos/vitrine.jpg", "titulo": "Vitrine de outubro", "alt": "Livros na vitrine" } } } } } }, "/midias/{id}": { "patch": { "tags": [ "Mídias" ], "summary": "Editar Mídia", "description": "Altera título, texto alternativo e legenda. Escopo: midias.escrever", "operationId": "editar_midia", "security": [ { "chave": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Identificador do mídia." } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "example": { "dados": { "id": 4407, "url": "https://hoteldaslojas.com.br/base/_uploads/220/2026/10/api-032333d61439b554.webp", "largura": 500, "altura": 333, "bytes": 8206, "titulo": "Vitrine de outubro", "alt": "Livros na vitrine da loja", "legenda": "", "criado_em": "2026-10-28T03:23:33-03:00" } } } } }, "401": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "chave_invalida", "mensagem": "Chave da API inválida ou revogada.", "request_id": "req_1b9c7d2e3f4a5b6c" } } } } }, "403": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "sem_permissao", "mensagem": "Esta chave não tem o escopo \"pedidos.ler\". Crie uma chave com esse escopo no painel da loja (Integração › API).", "request_id": "req_95f4a872c180063c" } } } } }, "404": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "nao_encontrado", "mensagem": "Pedido não encontrado nesta loja.", "request_id": "req_6b6e2da7f1bb1871" } } } } }, "422": { "description": "Erro", "content": { "application/json": { "example": { "erro": { "codigo": "validacao", "mensagem": "Confira os campos enviados.", "request_id": "req_b08d82d702d96001", "campos": { "nome": "Campo obrigatório." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "titulo": { "type": "string", "description": "" }, "alt": { "type": "string", "description": "" }, "legenda": { "type": "string", "description": "" } }, "required": [] }, "example": { "alt": "Livros na vitrine da loja" } } } } } } } }