{ "openapi": "3.1.0", "info": { "title": "ERP Connect Mobile — API pública", "version": "1.2.2", "description": "API REST/JSON do ERP Connect Mobile: produtos (todos os campos e até 12 fotos), estoque com lote, validade e local, pedidos, cupom, notas fiscais, clientes, fornecedores, financeiro, PDV, cardápio, balança e avisos automáticos (webhooks). Documentação: https://www.erpconnectmobile.com.br/desenvolvedores/" }, "servers": [ { "url": "https://app.erpconnectmobile.com.br/api/v1", "description": "Produção" }, { "url": "https://aylmiszdvdlpdugkwzql.supabase.co/functions/v1/catalogo-api/v1", "description": "Produção (endereço direto)" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "tags": [ { "name": "Conexão", "description": "Teste a chave e veja o que ela pode fazer." }, { "name": "Produtos", "description": "Cadastro completo do produto." }, { "name": "Campos do produto", "description": "Uma rota para cada campo: ler e gravar um campo só." }, { "name": "Fotos e vídeos", "description": "Até 12 fotos por produto; a primeira é a capa." }, { "name": "Códigos de barras", "description": "Vários códigos por produto (EAN, DUN, interno)." }, { "name": "Variações, kits e embalagens", "description": "Como o produto é montado e vendido." }, { "name": "Categorias", "description": "Categorias e subcategorias." }, { "name": "Preços", "description": "Tabelas de preço e preço por quantidade." }, { "name": "Estoque", "description": "Saldo, lote, validade, local, entradas, saídas e balanço." }, { "name": "Clientes", "description": "Cadastro de clientes." }, { "name": "Fornecedores", "description": "Cadastro de fornecedores." }, { "name": "Pedidos", "description": "Ler e criar pedidos, histórico e cancelamento." }, { "name": "Cupom, envio e etiquetas", "description": "Cupom do pedido, frete, rastreio, etiqueta de envio e de produto." }, { "name": "Notas fiscais", "description": "NF-e e NFC-e emitidas, com XML." }, { "name": "Financeiro", "description": "Contas a receber." }, { "name": "Caixa, cardápio e balança", "description": "Vendas do PDV, cardápio para apps de comida e carga de balança." }, { "name": "Eventos e avisos (webhooks)", "description": "Receba avisos automáticos ou leia o feed." } ], "paths": { "/status": { "get": { "operationId": "status", "tags": [ "Conexão" ], "summary": "Testar a chave", "description": "Confirma que a chave funciona e diz a empresa, as permissões e quanto do limite do minuto já foi usado. Use como primeiro teste.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "empresa": { "id": "uuid", "nome": "Minha Empresa" }, "chave": { "nome": "Integração Bling", "escopos": [ "produtos:read", "estoque:read" ] }, "limite": { "por_minuto": 120, "usadas": 3 }, "versao": "1.2.2", "hora_servidor": "2026-11-07T22:22:00Z" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi", "tags": [ "Conexão" ], "summary": "Especificação OpenAPI 3.1", "description": "A API inteira em OpenAPI 3.1 (JSON). Importe no Postman, Insomnia, Swagger ou no gerador de código da sua linguagem. Não precisa de chave.", "security": [], "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/produtos": { "get": { "operationId": "produtos_listar", "tags": [ "Produtos" ], "summary": "Listar produtos", "description": "Lista paginada com todos os campos do produto, as URLs das fotos (até 12) e o saldo. Produto base (componente) só aparece com incluir_base=1.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "busca", "in": "query", "required": false, "description": "Procura no nome, referência e código de barras.", "schema": { "type": "string" } }, { "name": "ativo", "in": "query", "required": false, "description": "true (padrão), false ou todos.", "schema": { "type": "boolean" } }, { "name": "categoria_id", "in": "query", "required": false, "description": "Só desta categoria.", "schema": { "type": "string", "format": "uuid" } }, { "name": "incluir_base", "in": "query", "required": false, "description": "Inclui produtos base (componentes de kit).", "schema": { "type": "boolean" } }, { "name": "campos", "in": "query", "required": false, "description": "Só estes campos, separados por vírgula (resposta menor).", "schema": { "type": "string" }, "example": "id,referencia,preco_venda,estoque" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "072f458d-…", "erp_id": 1234, "referencia": "CP-01", "codigo_barras": "7890000000017", "nome": "Coador de pano nº 3", "marca": "Mesa Posta", "unidade": "UN", "preco_venda": 13.19, "estoque": 70, "estoque_reservado": 2, "disponivel": 68, "ncm": "63079090", "peso_kg": 0.12, "ativo": true, "categoria": "Utilidades", "tipo_produto": "venda", "foto_principal_url": "https://…/produto-1234-capa.jpg", "fotos": [ "https://…/1.jpg", "https://…/2.jpg" ], "updated_at": "2026-11-07T19:22:00-03:00" } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "produtos_criar", "tags": [ "Produtos" ], "summary": "Criar produto", "description": "Cria um produto de venda com o código numérico seguinte da empresa. Aceita qualquer campo gravável (ver Campos do produto). Estoque inicial: use POST /estoque/entradas depois. Se a referência ou o código de barras já existir, devolve 409 com o id do produto existente.\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nome": { "type": "string", "description": "Nome do produto." } }, "required": [ "nome" ], "additionalProperties": true }, "example": { "nome": "Coador de pano nº 3", "referencia": "CP-01", "codigo_barras": "7890000000017", "unidade": "UN", "preco_venda": 13.19, "ncm": "63079090", "peso_kg": 0.12 } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "072f458d-…", "erp_id": 1234, "referencia": "CP-01", "codigo_barras": "7890000000017", "nome": "Coador de pano nº 3", "marca": "Mesa Posta", "unidade": "UN", "preco_venda": 13.19, "estoque": 70, "estoque_reservado": 2, "disponivel": 68, "ncm": "63079090", "peso_kg": 0.12, "ativo": true, "categoria": "Utilidades", "tipo_produto": "venda", "foto_principal_url": "https://…/produto-1234-capa.jpg", "fotos": [ "https://…/1.jpg", "https://…/2.jpg" ], "updated_at": "2026-11-07T19:22:00-03:00" } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "conflito: Já existe (código repetido) ou o estado atual não permite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "patch": { "operationId": "produtos_alterar_varios", "tags": [ "Produtos" ], "summary": "Alterar vários produtos", "description": "Até 200 produtos numa chamada. Cada item leva \"produto\" (identificador) e os campos. Um item com erro não derruba os outros: a resposta diz o resultado de cada um.\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "produtos": [ { "produto": "sku:CP-01", "preco_venda": 14.5 }, { "produto": "ean:7890000000024", "ativo": false } ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": 2, "total": 2, "resultados": [ { "produto": "sku:CP-01", "ok": true }, { "produto": "ean:7890000000024", "ok": true } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}": { "get": { "operationId": "produtos_ler", "tags": [ "Produtos" ], "summary": "Ler um produto", "description": "Todos os campos do produto + fotos (ordem, capa), códigos de barras, variações, composição (kit) e saldo.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "072f458d-…", "erp_id": 1234, "referencia": "CP-01", "codigo_barras": "7890000000017", "nome": "Coador de pano nº 3", "marca": "Mesa Posta", "unidade": "UN", "preco_venda": 13.19, "estoque": 70, "estoque_reservado": 2, "disponivel": 68, "ncm": "63079090", "peso_kg": 0.12, "ativo": true, "categoria": "Utilidades", "tipo_produto": "venda", "foto_principal_url": "https://…/produto-1234-capa.jpg", "fotos": [ "https://…/1.jpg", "https://…/2.jpg" ], "updated_at": "2026-11-07T19:22:00-03:00", "codigos_barras": [ { "codigo": "7890000000017", "principal": true } ], "variacoes": [], "composicao": [] } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "patch": { "operationId": "produtos_alterar", "tags": [ "Produtos" ], "summary": "Alterar produto", "description": "Muda só os campos enviados. Campo que não é gravável é recusado com 422 (nunca ignorado em silêncio).\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "preco_venda": 14.5, "ncm": "63079090" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "072f458d-…", "erp_id": 1234, "referencia": "CP-01", "codigo_barras": "7890000000017", "nome": "Coador de pano nº 3", "marca": "Mesa Posta", "unidade": "UN", "preco_venda": 13.19, "estoque": 70, "estoque_reservado": 2, "disponivel": 68, "ncm": "63079090", "peso_kg": 0.12, "ativo": true, "categoria": "Utilidades", "tipo_produto": "venda", "foto_principal_url": "https://…/produto-1234-capa.jpg", "fotos": [ "https://…/1.jpg", "https://…/2.jpg" ], "updated_at": "2026-11-07T19:22:00-03:00" }, "alterados": [ "preco_venda", "ncm" ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "delete": { "operationId": "produtos_inativar", "tags": [ "Produtos" ], "summary": "Inativar produto", "description": "Produto nunca é apagado (pedidos, notas e lotes apontam para ele): fica inativo. Para reativar, PATCH ativo=true.\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "dados": { "id": "uuid", "ativo": false } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/campos": { "get": { "operationId": "campos_dicionario", "tags": [ "Campos do produto" ], "summary": "Lista de campos do produto", "description": "Todos os campos do produto com tipo, grupo, se é gravável e limite. É a mesma tabela desta documentação.\n\nPermissão: `produtos:read`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "nome": "preco_venda", "tipo": "numero", "grupo": "preco", "gravavel": true, "descricao": "Preço de venda (R$)." } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/campos/{campo}": { "get": { "operationId": "campos_ler", "tags": [ "Campos do produto" ], "summary": "Ler um campo", "description": "Devolve só o valor de um campo. Serve para todo campo da tabela \"Campos do produto\".\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "campo", "in": "path", "required": true, "description": "Nome do campo.", "schema": { "type": "string" }, "example": "preco_venda" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "produto_id": "uuid", "campo": "preco_venda", "valor": 13.19 } } } }, "400": { "description": "campo_desconhecido: O campo não existe na lista.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "put": { "operationId": "campos_gravar", "tags": [ "Campos do produto" ], "summary": "Gravar um campo", "description": "Grava um campo só. Corpo: {\"valor\": …}. Recusa campo só-leitura (403) e valor do tipo errado (422).\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "campo", "in": "path", "required": true, "description": "Nome do campo.", "schema": { "type": "string" }, "example": "ncm" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "valor": "63079090" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "produto_id": "uuid", "campo": "ncm", "valor": "63079090", "anterior": "63079000" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "campo_somente_leitura: O campo não pode ser gravado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/fotos": { "get": { "operationId": "fotos_listar", "tags": [ "Fotos e vídeos" ], "summary": "Listar fotos", "description": "As fotos do produto na ordem (até 12). A de ordem 0 é a capa. URLs públicas, prontas para marketplace.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "ordem": 0, "capa": true, "url": "https://…/1.jpg", "miniatura_url": "https://…/1-thumb.jpg" } ], "maximo": 12 } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "fotos_adicionar", "tags": [ "Fotos e vídeos" ], "summary": "Adicionar foto", "description": "Manda a foto por URL pública (https) OU em base64. JPG, PNG ou WebP, até 10 MB. Entra no fim; a primeira foto do produto vira capa. Com \"capa\": true ela vai para a frente. Também aceita {\"fotos\": [ … ]} com várias.\n\nPermissão: `fotos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "Endereço https da imagem (ou use base64)." }, "base64": { "type": "string", "contentEncoding": "base64", "description": "Imagem em base64 (com ou sem \"data:image/jpeg;base64,\")." }, "capa": { "type": "boolean", "description": "Põe como capa." } }, "additionalProperties": true }, "example": { "url": "https://meusite.com/fotos/coador.jpg", "capa": false } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "uuid", "ordem": 3, "capa": false, "url": "https://…" }, "total_fotos": 4 } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "limite_fotos: O produto já tem 12 fotos.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/fotos/ordem": { "put": { "operationId": "fotos_ordenar", "tags": [ "Fotos e vídeos" ], "summary": "Reordenar fotos", "description": "Manda a lista COMPLETA de ids na ordem nova; o primeiro vira capa.\n\nPermissão: `fotos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "ids": [ "uuid-3", "uuid-1", "uuid-2" ] } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/fotos/{foto}/capa": { "post": { "operationId": "fotos_capa", "tags": [ "Fotos e vídeos" ], "summary": "Trocar a capa", "description": "Põe esta foto na frente (ordem 0); as outras andam uma casa.\n\nPermissão: `fotos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "foto", "in": "path", "required": true, "description": "Id da foto.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/fotos/{foto}": { "delete": { "operationId": "fotos_remover", "tags": [ "Fotos e vídeos" ], "summary": "Apagar foto", "description": "Apaga a foto e o arquivo. Se era a capa, a próxima vira capa.\n\nPermissão: `fotos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "foto", "in": "path", "required": true, "description": "Id da foto.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "total_fotos": 3 } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/videos": { "get": { "operationId": "videos_listar", "tags": [ "Fotos e vídeos" ], "summary": "Listar vídeos", "description": "Vídeos do produto (URL, capa, duração).\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "ordem": 0, "url": "https://…/video.mp4", "capa_url": "https://…", "duracao_s": 18 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/codigos-barras": { "get": { "operationId": "codigos_listar", "tags": [ "Códigos de barras" ], "summary": "Listar códigos", "description": "Todos os códigos do produto (EAN da unidade, DUN da caixa, código interno), com quantas unidades cada um representa.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "codigo": "7890000000017", "simbologia": "EAN13", "unidades": 1, "principal": true }, { "id": "uuid", "codigo": "17890000000014", "simbologia": "DUN14", "unidades": 12, "principal": false } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "codigos_adicionar", "tags": [ "Códigos de barras" ], "summary": "Adicionar código", "description": "Liga mais um código ao produto. Código já usado por outro produto da empresa = 409.\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "codigo": { "type": "string", "description": "O código." }, "unidades": { "type": "integer", "description": "Quantas unidades o código representa (caixa com 12 = 12). Padrão 1." }, "apelido": { "type": "string", "description": "Nome curto (ex.: \"Caixa\")." } }, "required": [ "codigo" ], "additionalProperties": true }, "example": { "codigo": "17890000000014", "unidades": 12, "apelido": "Caixa" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "conflito: Já existe (código repetido) ou o estado atual não permite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/codigos-barras/{codigo}": { "delete": { "operationId": "codigos_remover", "tags": [ "Códigos de barras" ], "summary": "Remover código", "description": "Desliga o código do produto (o código principal do cadastro não sai por aqui: grave outro em codigo_barras).\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "codigo", "in": "path", "required": true, "description": "O código ou o id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/variacoes": { "get": { "operationId": "variacoes_listar", "tags": [ "Variações, kits e embalagens" ], "summary": "Variações", "description": "Variações (cor, tamanho…) com SKU, código de barras e preço diferencial.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "atributo_tipo": "cor", "atributo_valor": "Azul", "sku": "CP-01-AZ", "codigo_barras": "789…", "preco_diferencial": 0 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/composicao": { "get": { "operationId": "composicao_listar", "tags": [ "Variações, kits e embalagens" ], "summary": "Composição do kit", "description": "Se o produto é kit, quais produtos e quantidades ele leva.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "componente_id": "uuid", "componente_erp_id": 55, "nome": "Seda Brown", "quantidade": 2, "unidade": "UN" } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/embalagens": { "get": { "operationId": "embalagens_listar", "tags": [ "Variações, kits e embalagens" ], "summary": "Embalagens", "description": "Formas de venda/compra do produto (unidade, display, caixa) com o fator de conversão.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "nome": "Caixa com 12", "fator_conversao": 12, "tipo": "caixa" } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/categorias": { "get": { "operationId": "categorias_listar", "tags": [ "Categorias" ], "summary": "Listar categorias", "description": "Categorias com as subcategorias dentro.\n\nPermissão: `produtos:read`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "nome": "Utilidades", "ordem": 1, "ativa": true, "subcategorias": [ { "id": "uuid", "nome": "Cozinha" } ] } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "categorias_criar", "tags": [ "Categorias" ], "summary": "Criar categoria", "description": "Cria a categoria (nome repetido devolve a existente com 200).\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "nome": "Utilidades", "descricao": "Casa e cozinha" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/categorias/{categoria}/subcategorias": { "post": { "operationId": "subcategorias_criar", "tags": [ "Categorias" ], "summary": "Criar subcategoria", "description": "Cria a subcategoria dentro da categoria.\n\nPermissão: `produtos:write`.", "parameters": [ { "name": "categoria", "in": "path", "required": true, "description": "Id da categoria.", "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "nome": "Cozinha" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/precos": { "get": { "operationId": "precos_produto", "tags": [ "Preços" ], "summary": "Preços do produto", "description": "Preço de venda, preço por quantidade (atacado) e o preço em cada tabela de preço.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "preco_venda": 13.19, "por_quantidade": [ { "quantidade_minima": 12, "desconto_pct": 5, "preco_fixo": null } ], "tabelas": [ { "tabela_id": "uuid", "nome": "Atacado", "preco": 11.9 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/tabelas-preco": { "get": { "operationId": "tabelas_listar", "tags": [ "Preços" ], "summary": "Tabelas de preço", "description": "Tabelas de preço da empresa.\n\nPermissão: `produtos:read`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "nome": "Atacado", "desconto_pct_padrao": 10, "ativo": true } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/tabelas-preco/{tabela}/itens": { "get": { "operationId": "tabelas_itens", "tags": [ "Preços" ], "summary": "Itens da tabela", "description": "Preço de cada produto na tabela.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "tabela", "in": "path", "required": true, "description": "Id da tabela.", "schema": { "type": "string", "format": "uuid" } }, { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "produto_id": "uuid", "erp_id": 1234, "referencia": "CP-01", "preco": 11.9 } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque": { "get": { "operationId": "estoque_saldos", "tags": [ "Estoque" ], "summary": "Saldos de todos os produtos", "description": "Um número por produto. vendavel = o que dá para vender, já na unidade de venda (o mesmo número que o app manda aos marketplaces): produto em caixa = caixas inteiras, cartela = só as lacradas, kit virtual = prontos + o que dá para montar; já desconta venda de fora ainda sem baixa e o que já foi prometido a cliente (venda que ficou sem estoque). saldo/reservado/disponivel = soma dos lotes, em unidade de estoque. É o que sistemas sem lote/local precisam. Para o detalhe por local e lote, use /estoque/{produto}. Veja \"Cartela de fornecedor e kit virtual\".\n\nPermissão: `estoque:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "produto_id": "uuid", "erp_id": 1234, "referencia": "CP-01", "codigo_barras": "7890000000017", "saldo": 70, "reservado": 2, "disponivel": 68, "tipo_estoque": "simples", "vendavel": 5, "unidades_por_venda": 12, "vendido_fora_sem_baixa": 0, "proxima_validade": "2027-03-01", "atualizado_em": "…" }, { "produto_id": "uuid", "erp_id": 1240, "referencia": "CAD-C12", "codigo_barras": null, "saldo": 12, "reservado": 0, "disponivel": 12, "tipo_estoque": "cartela", "vendavel": 1, "unidades_por_venda": 12, "cartelas_lacradas": 1, "soltas_da_cartela": 3, "vendido_fora_sem_baixa": 0 }, { "produto_id": "uuid", "erp_id": 1241, "referencia": "CAD-UN", "codigo_barras": null, "saldo": 0, "reservado": 0, "disponivel": 0, "tipo_estoque": "kit_virtual", "vendavel": 15, "unidades_por_venda": 1, "prontos": 0, "da_para_montar": 15, "vendido_fora_sem_baixa": 0 } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/{produto}": { "get": { "operationId": "estoque_produto", "tags": [ "Estoque" ], "summary": "Estoque detalhado do produto", "description": "Saldo total + vendável (como em /estoque) + quanto tem em cada local + cada lote (número do lote, validade, local, quantidade, caixas fechadas e unidades soltas). Lote sem local = aguardando endereçamento.\n\nPermissão: `estoque:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "produto_id": "uuid", "saldo": 70, "reservado": 2, "disponivel": 68, "tipo_estoque": "simples", "vendavel": 5, "unidades_por_venda": 12, "vendido_fora_sem_baixa": 0, "por_local": [ { "local_id": "uuid", "local": "A-01-02", "quantidade": 60 }, { "local_id": null, "local": "Sem local (aguardando endereçar)", "quantidade": 10 } ], "lotes": [ { "lote_id": "uuid", "lote": "L2611", "validade": "2027-03-01", "local_id": "uuid", "local": "A-01-02", "quantidade": 60, "caixas_fechadas": 5, "unidades_soltas": 0, "unidades_por_caixa": 12 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/lotes": { "get": { "operationId": "estoque_lotes", "tags": [ "Estoque" ], "summary": "Todos os lotes", "description": "Lotes ativos de todos os produtos. Filtre por vencendo_ate para saber o que vence.\n\nPermissão: `estoque:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "vencendo_ate", "in": "query", "required": false, "description": "Só lotes com validade até esta data.", "schema": { "type": "string", "format": "date" } }, { "name": "local_id", "in": "query", "required": false, "description": "Só deste local.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/movimentos": { "get": { "operationId": "estoque_movimentos", "tags": [ "Estoque" ], "summary": "Movimentos de estoque", "description": "Histórico de entradas, saídas, transferências e ajustes de cada lote, com motivo e pedido, do mais antigo para o mais novo. Cartela aberta para vender kit virtual aparece como abertura_cartela (e fechamento_cartela quando volta lacrada no cancelamento). Para sincronizar, peça \"desde\" a data do último que você leu.\n\nPermissão: `estoque:read`.", "parameters": [ { "name": "desde", "in": "query", "required": false, "description": "Só a partir desta data/hora.", "schema": { "type": "string", "format": "date-time" } }, { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "tipo": "saida", "quantidade": 2, "produto_erp_id": 1234, "lote_id": "uuid", "local_origem_id": "uuid", "local_destino_id": null, "pedido_id": "uuid", "motivo": "Venda", "origem_tipo": "pedido", "criado_em": "…", "estornada_em": null } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/entradas": { "post": { "operationId": "estoque_entrada", "tags": [ "Estoque" ], "summary": "Dar entrada", "description": "Soma estoque criando um lote. Local: o informado → o local onde o produto já está → o local padrão da empresa. No controle por lote a mercadoria nunca fica sem endereço: se nenhum desses existir, a entrada é recusada com estoque_sem_local (mande local_id, veja /locais). No modo simples o local não é exigido. Validade e lote são opcionais. Cartela de fornecedor entra só lacrada (múltiplo do tamanho da cartela, ou \"unidade\": \"venda\" com o número de cartelas); kit virtual e produto base não recebem entrada. Aceita uma entrada ou {\"entradas\": [ … ]} (até 200).\n\nPermissão: `estoque:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "produto": { "type": "string", "description": "Identificador do produto (5 jeitos)." }, "quantidade": { "type": "number", "description": "Quantidade na unidade de estoque (inteiro > 0)." }, "unidade": { "type": "string", "description": "\"estoque\" (padrão) ou \"venda\": a quantidade em caixas/cartelas inteiras." }, "local_id": { "type": "string", "format": "uuid", "description": "Local de destino (ver /locais)." }, "validade": { "type": "string", "format": "date", "description": "Validade do lote (AAAA-MM-DD)." }, "lote": { "type": "string", "description": "Número do lote do fabricante." }, "custo_unitario": { "type": "number", "description": "Custo de cada unidade (R$)." } }, "required": [ "produto", "quantidade" ], "additionalProperties": true }, "example": { "entradas": [ { "produto": "sku:CP-01", "quantidade": 24, "validade": "2027-03-01", "lote": "L2611", "custo_unitario": 6.5 } ] } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": 1, "total": 1, "resultados": [ { "ok": true, "lote_id": "uuid", "local_id": "uuid", "sem_local": false, "quantidade_entrada": 24, "estoque_total": 94 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "produto_sem_estoque_proprio: Kit virtual ou produto base.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "cartela_incompleta: Cartela com quantidade que não fecha cartela inteira (ex.: 15 numa cartela de 12).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/saidas": { "post": { "operationId": "estoque_saida", "tags": [ "Estoque" ], "summary": "Dar saída", "description": "Tira estoque pela validade mais próxima (FEFO), de qualquer local, ou só do local informado. Falta saldo = recusa inteira (nunca tira pela metade). Cada lote mexido fica no histórico com o nome da integração. Kit virtual, produto base e cartela de fornecedor são recusados: a venda deles entra como pedido, e o app decide qual cartela abrir. Com \"previa\": true mostra o que faria sem mexer.\n\nPermissão: `estoque:ajustar`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "produto": { "type": "string", "description": "Identificador do produto." }, "quantidade": { "type": "number", "description": "Quanto tirar." }, "unidade": { "type": "string", "description": "\"estoque\" (padrão) ou \"venda\": a quantidade em caixas/cartelas inteiras." }, "local_id": { "type": "string", "format": "uuid", "description": "Só deste local." }, "motivo": { "type": "string", "description": "Aparece no histórico do app." }, "previa": { "type": "boolean", "description": "Só simula." } }, "required": [ "produto", "quantidade" ], "additionalProperties": true }, "example": { "produto": "ean:7890000000017", "quantidade": 3, "motivo": "Venda no balcão do sistema X" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "aplicado": true, "saldo_antes": 70, "saldo_depois": 67, "lotes": [ { "lote_id": "uuid", "validade": "2027-03-01", "de": 60, "para": 57 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "produto_sem_estoque_proprio: Kit virtual, base ou cartela de fornecedor.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/{produto}/saldo": { "put": { "operationId": "estoque_saldo", "tags": [ "Estoque" ], "summary": "Acertar o saldo (valor absoluto)", "description": "Para sistemas que só conhecem \"quanto tem\". Calcula a diferença: se subiu, cria um lote (local como na entrada); se desceu, tira só a diferença pela validade mais próxima — os outros locais e lotes ficam como estão. Kit virtual, produto base e cartela de fornecedor são recusados. Recomendado mandar \"previa\": true primeiro.\n\nPermissão: `estoque:ajustar`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quantidade": { "type": "number", "description": "Saldo que deve ficar." }, "unidade": { "type": "string", "description": "\"estoque\" (padrão) ou \"venda\": a quantidade em caixas/cartelas inteiras." }, "local_id": { "type": "string", "format": "uuid", "description": "Acerta só este local." }, "motivo": { "type": "string", "description": "Aparece no histórico." }, "previa": { "type": "boolean", "description": "Só simula." } }, "required": [ "quantidade" ], "additionalProperties": true }, "example": { "quantidade": 65, "motivo": "Contagem do sistema X", "previa": true } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "ok": true, "aplicado": false, "saldo_antes": 70, "saldo_depois": 65, "lotes": [ { "lote_id": "uuid", "de": 60, "para": 55 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/estoque/balanco": { "post": { "operationId": "estoque_balanco", "tags": [ "Estoque" ], "summary": "Balanço (vários saldos)", "description": "Mesmo que acertar o saldo, para até 200 produtos. Cada item tem resultado próprio.\n\nPermissão: `estoque:ajustar`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "previa": true, "itens": [ { "produto": "sku:CP-01", "quantidade": 65 }, { "produto": "sku:CP-02", "quantidade": 0 } ] } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/locais": { "get": { "operationId": "locais_listar", "tags": [ "Estoque" ], "summary": "Locais de estoque", "description": "Endereços do depósito (zona, corredor, coluna, linha) e o local padrão da empresa.\n\nPermissão: `estoque:read`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "local_padrao_id": "uuid", "dados": [ { "id": "uuid", "nome": "A-01-02", "zona": "A", "corredor": "01", "coluna": "02", "linha": null, "codigo_barras": "LOC-A0102", "ativo": true } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/clientes": { "get": { "operationId": "clientes_listar", "tags": [ "Clientes" ], "summary": "Listar clientes", "description": "Clientes da empresa.\n\nPermissão: `clientes:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "busca", "in": "query", "required": false, "description": "Nome, fantasia ou documento.", "schema": { "type": "string" } }, { "name": "documento", "in": "query", "required": false, "description": "CNPJ/CPF exato (só dígitos).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "razao_social": "Mercado Bom Preço Ltda", "fantasia": "Bom Preço", "cnpj_cpf": "12345678000190", "inscricao_estadual": "110042490114", "email": "compras@bompreco.com.br", "telefone": "11999990000", "cep": "01001000", "logradouro": "Praça da Sé", "numero": "100", "bairro": "Sé", "cidade": "São Paulo", "uf": "SP", "codigo_municipio": "3550308", "limite_credito": 5000, "ativo": true } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "clientes_criar", "tags": [ "Clientes" ], "summary": "Criar cliente", "description": "Documento já cadastrado = 409 com o id existente.\n\nPermissão: `clientes:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "razao_social": { "type": "string", "description": "razao social" }, "fantasia": { "type": "string", "description": "fantasia" }, "cnpj_cpf": { "type": "string", "description": "cnpj cpf" }, "inscricao_estadual": { "type": "string", "description": "inscricao estadual" }, "ind_ie_dest": { "type": "string", "description": "ind ie dest" }, "email": { "type": "string", "description": "email" }, "telefone": { "type": "string", "description": "telefone" }, "cep": { "type": "string", "description": "cep" }, "logradouro": { "type": "string", "description": "logradouro" }, "numero": { "type": "string", "description": "numero" }, "complemento": { "type": "string", "description": "complemento" }, "bairro": { "type": "string", "description": "bairro" }, "cidade": { "type": "string", "description": "cidade" }, "uf": { "type": "string", "description": "uf" }, "codigo_municipio": { "type": "string", "description": "codigo municipio" }, "limite_credito": { "type": "number", "description": "limite credito" }, "observacao": { "type": "string", "description": "observacao" }, "ativo": { "type": "boolean", "description": "ativo" } }, "required": [ "razao_social" ], "additionalProperties": true }, "example": { "razao_social": "Mercado Bom Preço Ltda", "cnpj_cpf": "12345678000190", "email": "compras@bompreco.com.br", "telefone": "11999990000", "cep": "01001000", "uf": "SP", "cidade": "São Paulo" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "conflito: Já existe (código repetido) ou o estado atual não permite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/clientes/{cliente}": { "get": { "operationId": "clientes_ler", "tags": [ "Clientes" ], "summary": "Ler cliente", "description": "Pelo id ou por doc:CNPJ.\n\nPermissão: `clientes:read`.", "parameters": [ { "name": "cliente", "in": "path", "required": true, "description": "Id ou doc:12345678000190.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "uuid", "razao_social": "Mercado Bom Preço Ltda", "fantasia": "Bom Preço", "cnpj_cpf": "12345678000190", "inscricao_estadual": "110042490114", "email": "compras@bompreco.com.br", "telefone": "11999990000", "cep": "01001000", "logradouro": "Praça da Sé", "numero": "100", "bairro": "Sé", "cidade": "São Paulo", "uf": "SP", "codigo_municipio": "3550308", "limite_credito": 5000, "ativo": true } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "patch": { "operationId": "clientes_alterar", "tags": [ "Clientes" ], "summary": "Alterar cliente", "description": "Muda só os campos enviados.\n\nPermissão: `clientes:write`.", "parameters": [ { "name": "cliente", "in": "path", "required": true, "description": "Id ou doc:CNPJ.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "telefone": "11988887777" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/fornecedores": { "get": { "operationId": "fornecedores_listar", "tags": [ "Fornecedores" ], "summary": "Listar fornecedores", "description": "Fornecedores da empresa.\n\nPermissão: `fornecedores:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "busca", "in": "query", "required": false, "description": "Nome ou documento.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "fornecedores_criar", "tags": [ "Fornecedores" ], "summary": "Criar fornecedor", "description": "Documento já cadastrado = 409.\n\nPermissão: `fornecedores:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "razao_social": { "type": "string", "description": "razao social" }, "fantasia": { "type": "string", "description": "fantasia" }, "cnpj_cpf": { "type": "string", "description": "cnpj cpf" }, "inscricao_estadual": { "type": "string", "description": "inscricao estadual" }, "email": { "type": "string", "description": "email" }, "telefone": { "type": "string", "description": "telefone" }, "whatsapp": { "type": "string", "description": "whatsapp" }, "cep": { "type": "string", "description": "cep" }, "endereco_rua": { "type": "string", "description": "endereco rua" }, "endereco_numero": { "type": "string", "description": "endereco numero" }, "endereco_bairro": { "type": "string", "description": "endereco bairro" }, "endereco_cidade": { "type": "string", "description": "endereco cidade" }, "endereco_estado": { "type": "string", "description": "endereco estado" }, "responsavel_nome": { "type": "string", "description": "responsavel nome" }, "condicao_pagamento": { "type": "string", "description": "condicao pagamento" }, "prazo_medio_dias": { "type": "number", "description": "prazo medio dias" }, "lead_time_dias": { "type": "number", "description": "lead time dias" }, "pedido_minimo_valor": { "type": "number", "description": "pedido minimo valor" }, "observacoes": { "type": "string", "description": "observacoes" }, "ativo": { "type": "boolean", "description": "ativo" } }, "required": [ "razao_social" ], "additionalProperties": true }, "example": { "razao_social": "Distribuidora Exemplo Ltda", "cnpj_cpf": "11222333000181", "telefone": "1133334444" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/fornecedores/{fornecedor}": { "get": { "operationId": "fornecedores_ler", "tags": [ "Fornecedores" ], "summary": "Ler fornecedor", "description": "Pelo id ou doc:CNPJ.\n\nPermissão: `fornecedores:read`.", "parameters": [ { "name": "fornecedor", "in": "path", "required": true, "description": "Id ou doc:CNPJ.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "patch": { "operationId": "fornecedores_alterar", "tags": [ "Fornecedores" ], "summary": "Alterar fornecedor", "description": "Muda só os campos enviados.\n\nPermissão: `fornecedores:write`.", "parameters": [ { "name": "fornecedor", "in": "path", "required": true, "description": "Id ou doc:CNPJ.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos": { "get": { "operationId": "pedidos_listar", "tags": [ "Pedidos" ], "summary": "Listar pedidos", "description": "Pedidos de todos os canais (app, loja, site, marketplaces, API).\n\nPermissão: `pedidos:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "desde", "in": "query", "required": false, "description": "Criados a partir de.", "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "required": false, "description": "rascunho, pendente, confirmado, finalizado, faturado, cancelado (vários com vírgula).", "schema": { "type": "string" } }, { "name": "cliente_id", "in": "query", "required": false, "description": "Só deste cliente.", "schema": { "type": "string", "format": "uuid" } }, { "name": "com_itens", "in": "query", "required": false, "description": "Inclui os itens de cada pedido.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "numero": 812, "id_externo": "ERP-55821", "status": "faturado", "canal": "app", "valor_total": 129.9, "valor_frete": 0, "total_itens": 2, "cliente": { "id": "uuid", "nome": "Bom Preço", "documento": "12345678000190" }, "created_at": "2026-11-07T10:00:00-03:00", "itens": [ { "produto_id": "uuid", "erp_id": 1234, "referencia": "CP-01", "nome": "Coador de pano nº 3", "quantidade": 10, "preco_unitario": 12.99, "valor_total": 129.9 } ] } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "pedidos_criar", "tags": [ "Pedidos" ], "summary": "Criar pedido", "description": "O pedido entra em Processados como venda de outro canal, e o app dá a baixa do estoque pelo motor oficial (lote, cartela, kit). \"id_externo\" é obrigatório e único: reenviar o mesmo devolve o pedido já criado (nunca duplica). Todo item precisa achar o produto; se um não achar, o pedido inteiro é recusado e a resposta diz qual.\n\nPermissão: `pedidos:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_externo": { "type": "string", "description": "Número do pedido no seu sistema." }, "cliente": { "type": "string", "description": "Id do cliente ou doc:CNPJ (opcional)." }, "itens": { "type": "array", "items": { "type": "object" }, "description": "Lista: produto, quantidade, preco_unitario." }, "valor_frete": { "type": "number", "description": "Frete cobrado." }, "observacoes": { "type": "string", "description": "Observações." }, "criado_em": { "type": "string", "format": "date-time", "description": "Quando foi feito no seu sistema." } }, "required": [ "id_externo", "itens" ], "additionalProperties": true }, "example": { "id_externo": "ERP-55821", "cliente": "doc:12345678000190", "itens": [ { "produto": "sku:CP-01", "quantidade": 10, "preco_unitario": 12.99 } ], "observacoes": "Entregar pela manhã" } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "uuid", "numero": 813, "id_externo": "ERP-55821", "status": "finalizado", "valor_total": 129.9 }, "criado": true } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "item_sem_produto: Um item não achou produto: o pedido não entra.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}": { "get": { "operationId": "pedidos_ler", "tags": [ "Pedidos" ], "summary": "Ler pedido", "description": "Pedido completo com itens, cliente, pagamento, frete e notas. Pelo id, pelo número (n:812) ou pelo seu id externo (ext:ERP-55821).\n\nPermissão: `pedidos:read`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID_EXTERNO.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "uuid", "numero": 812, "id_externo": "ERP-55821", "status": "faturado", "canal": "app", "valor_total": 129.9, "valor_frete": 0, "total_itens": 2, "cliente": { "id": "uuid", "nome": "Bom Preço", "documento": "12345678000190" }, "created_at": "2026-11-07T10:00:00-03:00", "itens": [ { "produto_id": "uuid", "erp_id": 1234, "referencia": "CP-01", "nome": "Coador de pano nº 3", "quantidade": 10, "preco_unitario": 12.99, "valor_total": 129.9 } ] } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}/cancelar": { "post": { "operationId": "pedidos_cancelar", "tags": [ "Pedidos" ], "summary": "Cancelar pedido criado pela API", "description": "Só cancela pedido criado pela API e que o app ainda não baixou do estoque. Os outros se cancelam pelo app (o app pergunta o que fazer com cartela e kit).\n\nPermissão: `pedidos:write`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "additionalProperties": true }, "example": { "motivo": "Cliente desistiu" } } } }, "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "conflito: Já existe (código repetido) ou o estado atual não permite.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}/historico": { "get": { "operationId": "pedidos_historico", "tags": [ "Pedidos" ], "summary": "Histórico do pedido", "description": "Cada mudança de status com data e motivo.\n\nPermissão: `pedidos:read`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "status_anterior": "confirmado", "status_novo": "faturado", "motivo": null, "criado_em": "…" } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}/cupom": { "get": { "operationId": "pedidos_cupom", "tags": [ "Cupom, envio e etiquetas" ], "summary": "Cupom do pedido", "description": "Comprovante do pedido (não fiscal) pronto para imprimir: txt com 48 colunas (impressora térmica 80 mm; ?colunas=32 para 58 mm), html (A4 ou térmica pelo navegador) ou json com as linhas.\n\nPermissão: `pedidos:read`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID.", "schema": { "type": "string" } }, { "name": "formato", "in": "query", "required": false, "description": "txt (padrão), html ou json.", "schema": { "type": "string" } }, { "name": "colunas", "in": "query", "required": false, "description": "32, 42 ou 48 (padrão).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}/envio": { "get": { "operationId": "pedidos_envio", "tags": [ "Cupom, envio e etiquetas" ], "summary": "Frete e rastreio", "description": "Transportadora, serviço, valor, prazo, código de rastreio, link de rastreio e o link da etiqueta de envio (PDF) quando já foi gerada.\n\nPermissão: `pedidos:read`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "provedor": "melhor_envio", "transportadora": "Correios", "servico": "PAC", "valor_frete": 22.4, "prazo_dias": 5, "status": "postado", "codigo_rastreio": "AA123456789BR", "rastreio_url": "https://…", "etiqueta_url": "https://…", "volumes": 1, "peso_kg": 0.4 } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/produtos/{produto}/etiqueta": { "get": { "operationId": "produtos_etiqueta", "tags": [ "Cupom, envio e etiquetas" ], "summary": "Etiqueta do produto", "description": "Dados para imprimir a etiqueta de gôndola/produto: nome, preço, código de barras. Em ZPL (impressora Zebra/Elgin/Argox) com ?formato=zpl, ou json.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "produto", "in": "path", "required": true, "description": "O produto, de 5 jeitos: id (uuid), código numérico (1234), sku:REF, ean:CODIGO ou balanca:PLU.", "schema": { "type": "string" }, "example": "sku:CP-01" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou zpl.", "schema": { "type": "string" } }, { "name": "copias", "in": "query", "required": false, "description": "Cópias no ZPL (1 a 500).", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "nome": "Coador de pano nº 3", "referencia": "CP-01", "preco_venda": 13.19, "codigo_barras": "7890000000017", "simbologia": "EAN13", "unidade": "UN" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/etiquetas": { "get": { "operationId": "etiquetas_listar", "tags": [ "Cupom, envio e etiquetas" ], "summary": "Etiquetas salvas", "description": "Modelos de etiqueta feitos no app (código, título, tamanho, quantas vezes impressa).\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/notas": { "get": { "operationId": "notas_listar", "tags": [ "Notas fiscais" ], "summary": "Listar notas", "description": "NF-e (55) e NFC-e (65) emitidas.\n\nPermissão: `notas:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "status", "in": "query", "required": false, "description": "autorizada, cancelada, rejeitada…", "schema": { "type": "string" } }, { "name": "modelo", "in": "query", "required": false, "description": "55 ou 65.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "pedido_id": "uuid", "modelo": "55", "serie": 1, "numero": 43, "chave": "3526…", "status": "autorizada", "valor_total": 129.9, "data_emissao": "…", "destinatario": { "nome": "Bom Preço", "documento": "12345678000190" } } ], "paginacao": { "pagina": 1, "por_pagina": 100, "total": 1, "total_paginas": 1 } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/notas/{nota}": { "get": { "operationId": "notas_ler", "tags": [ "Notas fiscais" ], "summary": "Ler nota", "description": "Pelo id ou pela chave (chave:44 dígitos).\n\nPermissão: `notas:read`.", "parameters": [ { "name": "nota", "in": "path", "required": true, "description": "Id ou chave:CHAVE.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/notas/{nota}/xml": { "get": { "operationId": "notas_xml", "tags": [ "Notas fiscais" ], "summary": "XML autorizado", "description": "O XML da nota com o protocolo da SEFAZ (nfeProc), pronto para mandar ao contador ou ao marketplace.\n\nPermissão: `notas:read`.", "parameters": [ { "name": "nota", "in": "path", "required": true, "description": "Id ou chave:CHAVE.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "404": { "description": "nao_encontrado: O item não existe nesta empresa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "409": { "description": "sem_xml: A nota não foi autorizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pedidos/{pedido}/notas": { "get": { "operationId": "pedidos_notas", "tags": [ "Notas fiscais" ], "summary": "Notas do pedido", "description": "Notas emitidas para o pedido.\n\nPermissão: `notas:read`.", "parameters": [ { "name": "pedido", "in": "path", "required": true, "description": "Id, n:NUMERO ou ext:ID.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/contas-receber": { "get": { "operationId": "financeiro_receber", "tags": [ "Financeiro" ], "summary": "Contas a receber", "description": "Parcelas a receber com vencimento, valor em aberto, pago, forma prevista e boleto (linha digitável).\n\nPermissão: `financeiro:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "alterado_desde", "in": "query", "required": false, "description": "Só o que mudou depois desta data/hora (ISO 8601). Use para sincronizar só a diferença.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-11-07T00:00:00-03:00" }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" }, { "name": "status", "in": "query", "required": false, "description": "aberto, pago, vencido, cancelado.", "schema": { "type": "string" } }, { "name": "vencimento_ate", "in": "query", "required": false, "description": "Vence até.", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/pdv/vendas": { "get": { "operationId": "pdv_vendas", "tags": [ "Caixa, cardápio e balança" ], "summary": "Vendas do caixa", "description": "Vendas do PDV com itens, pagamentos e o cupom de desconto usado (cupom_regra_id).\n\nPermissão: `pdv:read`.", "parameters": [ { "name": "pagina", "in": "query", "required": false, "description": "Página (começa em 1).", "schema": { "type": "integer" }, "example": 1 }, { "name": "por_pagina", "in": "query", "required": false, "description": "Itens por página (1 a 500, padrão 100).", "schema": { "type": "integer" }, "example": 100 }, { "name": "desde", "in": "query", "required": false, "description": "A partir de.", "schema": { "type": "string", "format": "date-time" } }, { "name": "formato", "in": "query", "required": false, "description": "json (padrão) ou csv (planilha, separador ;).", "schema": { "type": "string" }, "example": "csv" } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/cardapio": { "get": { "operationId": "cardapio_ler", "tags": [ "Caixa, cardápio e balança" ], "summary": "Cardápio", "description": "Seções e itens do cardápio com preço, foto e disponibilidade (estoque > 0). Mesmo formato de \"item com complementos\" do padrão Open Delivery (Abrasel).\n\nPermissão: `pdv:read`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": "uuid", "nome": "Lanches", "ordem": 1, "itens": [ { "id": "uuid", "produto_id": "uuid", "nome": "X-Burguer", "preco": 25, "disponivel": true, "foto_url": "https://…", "complementos": [ { "produto_erp_id": 99, "texto": "Bacon" } ] } ] } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/balanca/itens": { "get": { "operationId": "balanca_itens", "tags": [ "Caixa, cardápio e balança" ], "summary": "Carga da balança", "description": "Itens com código de balança (PLU), preço por kg ou por unidade. ?formato=toledo devolve o arquivo ITENSMGV.TXT (Toledo MGV), ?formato=filizola o CADTXT.TXT; json para outros programas.\n\nPermissão: `produtos:read`.", "parameters": [ { "name": "formato", "in": "query", "required": false, "description": "json (padrão), toledo ou filizola.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "codigo_balanca": "01234", "nome": "Queijo minas", "unidade": "KG", "preco": 39.9, "por_peso": true, "validade_dias": null } ] } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/eventos": { "get": { "operationId": "eventos_listar", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Feed de eventos", "description": "Para quem não pode receber aviso automático: leia de tempos em tempos pedindo só o que veio depois do último id lido. Guardamos 30 dias.\n\nPermissão: `eventos:read`.", "parameters": [ { "name": "depois", "in": "query", "required": false, "description": "Último id que você já leu (0 na primeira vez).", "schema": { "type": "integer" } }, { "name": "tipos", "in": "query", "required": false, "description": "Só estes tipos (vírgula), ex.: estoque.alterado,pedido.*", "schema": { "type": "string" } }, { "name": "por_pagina", "in": "query", "required": false, "description": "Até 500.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": [ { "id": 1042, "tipo": "estoque.alterado", "recurso_id": "uuid", "criado_em": "…", "dados": { "saldo": 68 } } ], "ultimo_id": 1042, "tem_mais": false } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/webhooks": { "get": { "operationId": "webhooks_listar", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Listar avisos", "description": "Endereços cadastrados (o segredo não volta).\n\nPermissão: `webhooks:write`.", "parameters": [], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } }, "post": { "operationId": "webhooks_criar", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Cadastrar aviso", "description": "Cadastra um endereço https que recebe um POST a cada evento escolhido (\"*\" = todos, \"pedido.*\" = todos de pedido). O segredo de assinatura volta UMA vez: guarde.\n\nPermissão: `webhooks:write`.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Chave única por operação: repetir a chamada com a mesma chave devolve a mesma resposta, sem gravar de novo (vale 48 h).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "https://… (nome de domínio público, porta 443)." }, "eventos": { "type": "array", "items": { "type": "string" }, "description": "Tipos de evento. Padrão: [\"*\"]." }, "descricao": { "type": "string", "description": "Para você lembrar o que é." } }, "required": [ "url" ], "additionalProperties": true }, "example": { "url": "https://meuerp.com.br/webhooks/erpconnect", "eventos": [ "estoque.alterado", "pedido.*" ] } } } }, "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" }, "example": { "dados": { "id": "uuid", "segredo": "whsec_…", "eventos": [ "estoque.alterado", "pedido.*" ] } } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "422": { "description": "dado_invalido: Algum campo veio errado (o campo é informado).", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/webhooks/{webhook}": { "delete": { "operationId": "webhooks_remover", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Remover aviso", "description": "Para de mandar para o endereço.\n\nPermissão: `webhooks:write`.", "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Id do aviso.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/webhooks/{webhook}/teste": { "post": { "operationId": "webhooks_testar", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Testar aviso", "description": "Manda um evento teste.ping no próximo minuto.\n\nPermissão: `webhooks:write`.", "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Id do aviso.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } }, "/webhooks/{webhook}/entregas": { "get": { "operationId": "webhooks_entregas", "tags": [ "Eventos e avisos (webhooks)" ], "summary": "Entregas do aviso", "description": "Últimas 100 entregas: evento, tentativa, código HTTP que seu servidor respondeu e o erro.\n\nPermissão: `webhooks:write`.", "parameters": [ { "name": "webhook", "in": "path", "required": true, "description": "Id do aviso.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Sucesso", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "description": "Sem chave ou chave inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "403": { "description": "A chave não tem a permissão", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } }, "429": { "description": "Limite por minuto atingido (veja Retry-After)", "content": { "application/json": { "schema": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer erpk_…" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key" } }, "schemas": { "Erro": { "type": "object", "properties": { "erro": { "type": "object", "properties": { "codigo": { "type": "string" }, "mensagem": { "type": "string" }, "campo": { "type": "string" } }, "required": [ "codigo", "mensagem" ] } } }, "Produto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador interno (não muda nunca). (só leitura)", "readOnly": true }, "erp_id": { "type": "integer", "description": "Código numérico do produto na empresa. (só leitura)", "readOnly": true }, "referencia": { "type": "string", "description": "SKU / referência. Também serve para achar o produto: /produtos/sku:CP-01." }, "codigo_barras": { "type": "string", "description": "Código de barras principal (EAN/GTIN). Outros códigos: /codigos-barras." }, "codigo_balanca": { "type": "string", "description": "Código do item na balança (PLU)." }, "tipo_produto": { "type": "string", "description": "venda, kit ou base (componente). Base não aparece nas listas sem ?incluir_base=1. (só leitura)", "readOnly": true }, "nome": { "type": "string", "description": "Nome do produto." }, "descricao": { "type": "string", "description": "Descrição longa." }, "marca": { "type": "string", "description": "Marca." }, "modelo": { "type": "string", "description": "Modelo." }, "variante": { "type": "string", "description": "Variante (cor, tamanho, sabor) quando o produto é uma variação." }, "unidade": { "type": "string", "description": "Unidade de venda (UN, CX, KG, PCT…)." }, "foto_principal_url": { "type": "string", "description": "Foto de capa. Para mudar, use /fotos. (só leitura)", "readOnly": true }, "peso_kg": { "type": "number", "description": "Peso bruto em kg." }, "altura_cm": { "type": "number", "description": "Altura da embalagem em cm." }, "largura_cm": { "type": "number", "description": "Largura em cm." }, "comprimento_cm": { "type": "number", "description": "Comprimento em cm." }, "ncm": { "type": "string", "description": "NCM (8 dígitos)." }, "cest": { "type": "string", "description": "CEST (7 dígitos)." }, "cfop_padrao": { "type": "string", "description": "CFOP padrão de venda." }, "origem_mercadoria": { "type": "string", "description": "Origem (0 a 8, tabela da SEFAZ)." }, "csosn_padrao": { "type": "string", "description": "CSOSN (Simples Nacional)." }, "cst_icms_padrao": { "type": "string", "description": "CST do ICMS (regime normal)." }, "aliquota_icms_padrao": { "type": "number", "description": "Alíquota de ICMS (%)." }, "reducao_bc_icms_pct": { "type": "number", "description": "Redução da base do ICMS (%)." }, "mva_st_pct": { "type": "number", "description": "MVA da substituição tributária (%)." }, "aliquota_icms_st_pct": { "type": "number", "description": "Alíquota do ICMS-ST (%)." }, "fcp_pct": { "type": "number", "description": "Fundo de Combate à Pobreza (%)." }, "cbenef": { "type": "string", "description": "Código de benefício fiscal." }, "cst_pis_padrao": { "type": "string", "description": "CST do PIS." }, "aliquota_pis_padrao": { "type": "number", "description": "Alíquota do PIS (%)." }, "cst_cofins_padrao": { "type": "string", "description": "CST da COFINS." }, "aliquota_cofins_padrao": { "type": "number", "description": "Alíquota da COFINS (%)." }, "cst_ipi_padrao": { "type": "string", "description": "CST do IPI." }, "aliquota_ipi_padrao": { "type": "number", "description": "Alíquota do IPI (%)." }, "preco_venda": { "type": "number", "description": "Preço de venda (R$). Kit não aceita preço pela API (precisa do aval no app)." }, "desconto_max_pct": { "type": "number", "description": "Desconto máximo permitido ao vendedor (%)." }, "custo_medio": { "type": "number", "description": "Custo médio ponderado (R$). (só leitura) Exige custos:read.", "readOnly": true }, "ultimo_custo": { "type": "number", "description": "Custo da última entrada (R$). (só leitura) Exige custos:read.", "readOnly": true }, "margem_padrao_pct": { "type": "number", "description": "Margem padrão (%). (só leitura) Exige custos:read.", "readOnly": true }, "margem_minima_produto": { "type": "number", "description": "Margem mínima (%). (só leitura) Exige custos:read.", "readOnly": true }, "estoque": { "type": "number", "description": "Saldo total (soma dos lotes). Para mudar, use /estoque. (só leitura)", "readOnly": true }, "estoque_reservado": { "type": "number", "description": "Reservado para pedidos. (só leitura)", "readOnly": true }, "proxima_validade": { "type": "string", "format": "date", "description": "Validade mais próxima entre os lotes. (só leitura)", "readOnly": true }, "estoque_minimo": { "type": "number", "description": "Estoque mínimo (alerta de compra)." }, "estoque_ideal": { "type": "number", "description": "Estoque ideal." }, "unidade_compra_nome": { "type": "string", "description": "Nome da unidade de compra (ex.: CX)." }, "unidade_estoque_nome": { "type": "string", "description": "Nome da unidade de estoque (ex.: UN)." }, "fator_conversao_compra": { "type": "number", "description": "Quantas unidades de estoque vêm numa unidade de compra. (só leitura)", "readOnly": true }, "controla_lote_fabricante": { "type": "boolean", "description": "Pede o lote do fabricante na entrada." }, "ativo": { "type": "boolean", "description": "Ativo no sistema." }, "visivel_venda": { "type": "boolean", "description": "Aparece para vender (pedido, catálogo, loja)." }, "visivel_pdv": { "type": "boolean", "description": "Aparece no caixa (PDV)." }, "ativo_marketplace": { "type": "boolean", "description": "Liberado para anunciar em marketplaces." }, "categoria_id": { "type": "string", "format": "uuid", "description": "Categoria (ver /categorias)." }, "subcategoria_id": { "type": "string", "format": "uuid", "description": "Subcategoria (ver /categorias)." }, "categoria": { "type": "string", "description": "Nome da categoria (só leitura; para mudar use categoria_id). (só leitura)", "readOnly": true }, "subcategoria": { "type": "string", "description": "Nome da subcategoria (só leitura). (só leitura)", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "description": "Criado em. (só leitura)", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "description": "Alterado em (use em ?alterado_desde=). (só leitura)", "readOnly": true } } } } }, "x-escopos": [ { "escopo": "produtos:read", "descricao": "Cadastro, fotos, códigos de barras, categorias, preços, etiquetas e balança." }, { "escopo": "produtos:write", "descricao": "Criar e alterar produtos, categorias e códigos de barras." }, { "escopo": "fotos:write", "descricao": "Enviar, ordenar, trocar a capa e apagar as fotos (até 12 por produto)." }, { "escopo": "custos:read", "descricao": "Inclui custo médio, último custo e margens nas respostas. Dado sensível." }, { "escopo": "estoque:read", "descricao": "Saldo, reservado, disponível, por local, por lote e validade, movimentos e locais." }, { "escopo": "estoque:write", "descricao": "Só soma: cria lote novo (com validade, se vier)." }, { "escopo": "estoque:ajustar", "descricao": "Saída, saldo absoluto e balanço. Tira pela validade mais próxima." }, { "escopo": "pedidos:read", "descricao": "Pedidos, itens, histórico, cupom, envio e etiqueta de envio." }, { "escopo": "pedidos:write", "descricao": "Pedido de outro sistema entra em Processados (como venda de marketplace)." }, { "escopo": "clientes:read", "descricao": "Cadastro de clientes." }, { "escopo": "clientes:write", "descricao": "Criar e alterar clientes." }, { "escopo": "fornecedores:read", "descricao": "Cadastro de fornecedores." }, { "escopo": "fornecedores:write", "descricao": "Criar e alterar fornecedores." }, { "escopo": "notas:read", "descricao": "NF-e/NFC-e emitidas: dados, chave, XML autorizado." }, { "escopo": "financeiro:read", "descricao": "Contas a receber." }, { "escopo": "pdv:read", "descricao": "Vendas do PDV e cardápio." }, { "escopo": "eventos:read", "descricao": "Feed de eventos para quem não recebe aviso automático." }, { "escopo": "webhooks:write", "descricao": "Cadastrar, testar e remover endereços de aviso (webhooks)." } ], "x-eventos": [ { "tipo": "produto.criado", "descricao": "Produto novo cadastrado." }, { "tipo": "produto.alterado", "descricao": "Algum campo do cadastro mudou. `campos` diz quais." }, { "tipo": "produto.fotos_alteradas", "descricao": "Foto adicionada, apagada, reordenada ou capa trocada." }, { "tipo": "estoque.alterado", "descricao": "O estoque do produto mudou (venda, entrada, ajuste, nota…). Sai também para a cartela e para cada kit virtual que usa a peça que mexeu, com o vendavel novo." }, { "tipo": "pedido.criado", "descricao": "Pedido novo (de qualquer canal)." }, { "tipo": "pedido.status_alterado", "descricao": "Status do pedido mudou." }, { "tipo": "pedido.cancelado", "descricao": "Pedido cancelado." }, { "tipo": "nota.autorizada", "descricao": "NF-e/NFC-e autorizada pela SEFAZ." }, { "tipo": "nota.cancelada", "descricao": "Nota cancelada." }, { "tipo": "cliente.criado", "descricao": "Cliente novo." }, { "tipo": "cliente.alterado", "descricao": "Cadastro do cliente mudou." }, { "tipo": "envio.atualizado", "descricao": "Frete do pedido mudou: etiqueta gerada, rastreio, postado, entregue." }, { "tipo": "teste.ping", "descricao": "Disparado pelo botão Testar (ou POST /webhooks/{id}/teste)." } ] }