Bem vindo a documentação da API Salesrun. A API Salesrun permite que ERPs parceiros sincronizem cadastros-chave (categorias, produtos, lojas, fornecedores), estoques e movimentações (venda, compra, promoções) para que os algoritmos preditivos da plataforma atuem com dados atualizados e façam recomendações assertivas.
\n\n\nOs recursos estão organizados em REST com respostas JSON e versionamento prefixado (/v1/…).
\n
Ao longo da documentação, mostraremos descrições detalhadas dos métodos que disponibilizamos e também exemplos de aplicações em diversas linguagens de programação.
\nPrecisa de ajuda ou quer tirar dúvidas? Entre em contato com nosso time de desenvolvimento pelo email devs@salesrun.io.
\nAntes de começar a integração você precisa definir a linguagem de programação que irá utilizar ou usa em seu sistema. Após definido, selecione no canto superior direito uma linguagem e os exemplos de aplicações nessa linguagem serão mostrados a direita de seus respectivos tópicos. Se a linguagem que você usará não está presente em nossa documentação, entre em contato para que possamos te ajudar a desenvolver a integração e incluirmos aqui futuramente.
\nVocê também precisará de uma conta na plataforma Salesrun e das credenciais de acesso, que por meio do recurso de autenticação, criará um Token de acesso. Ambos, são gerados e enviados por nossa equipe para você. Se ainda não possui, acesse a plataforma em Minha conta > Credenciais e crie suas credenciais para dar andamento no processo de integração.
Seu client id
\n","type":"text"},{"key":"client_secret","value":"{{client_secret}}","description":"Seu client secret
\n","type":"text"}]},"url":"{{base_url}}/oauth/token/","description":"A partir deste recurso, você obtém o token para realizar as requisições no padrão Oauth2. Envie as credenciais client_id e client_secret e o recurso retornará um token válido por 36.000 segundos. Salve este token e utilize nas requisições enviando no padrão Bearer token, e sempre que o token expirar, basta criar um novo token para realizar suas requisições.
Você pode desenvolver manualmente a integração enviando e recebendo requests para nossa API. Recomendamos utilizar um parâmetro para facilitar a troca da URL base de comunicação.
\nNossa URL base para comunicação com a API é:
\nhttps://integration.salesrun.io/
Utilizamos o padrão RESTful para comunicação entre os sistemas e o padrão de mensagens JSON para enviar e receber os dados.
Todas as respostas inválidas terão um campo de retorno chamado status. Caso o valor seja error um campo chamado description será enviado com a mensagem que indica a falha ocorrida na requisição. O tipo da requisição é importante, já que indica a ação que será executada, portanto:
Alguns cadastros poderão ser realizados em lote, ou seja, será possível inserir/atualizar vários registros em apenas uma requisição. Nesse caso o tipo de requisição será sempre POST ou PUT e toda a lista de registros enviados será processada. Nesse processamento os registros que ainda não existirem serão inseridos e os já existentes serão atualizados.
O Token de autorização e URL da comunicação que fornecemos precisam ser salvos e utilizados em todas as requests para nossa API. Você precisa ter em seu sistema uma área, ou campos, onde você possa salvar essas duas informações importantes para a integração.
\nTodas as requisições para a API devem ser feitas passando o Bearer token de acesso no header da requisição. O valor desse parâmetro é obtido no recurso de criação do Token, através das credenciais de acesso que serão disponibilizadas por nossa equipe ao parceiro para a realização da integração e testes.
Para criar suas credenciais, basta acessar sua conta ativa na plataforma Salesrun e ir até Minha conta > Credenciais e criar uma nova credencial vinculada à um usuário do tipo Administrador.
\nTodas as solicitações da API devem ser feitas por meio de HTTPS. Chamadas feitas por HTTP simples falharão. Solicitações de API sem autenticação também falharão.
Outra coisa importante é saber que cada empresa integrada terá uma conta e suas client_credentials de acesso que também forneceremos posteriormente, que darão também acesso a plataforma.
\n\nAtenção: As chaves de API que disponibilizamos possuem muitos privilégios, portanto, mantenha elas em segurança! Não compartilhe em áreas publicamente acessíveis, como GitHub, código do lado do cliente e assim por diante.
\n
Nós usamos respostas HTTP convencionais para indicar o sucesso ou a falha de uma solicitação da API. Em geral: os códigos no intervalo 2xx indicam sucesso. Os códigos 4xx indicam um erro que falhou, dadas as informações fornecidas (por exemplo, um parâmetro necessário foi omitido, etc.). Códigos 5xx indicam um erro com nossos servidores (raros de acontecer).
Abaixo está uma lista de retorno de Erros da API Salesrun com suas respectivas descrições:
\n","_postman_id":"f7c178d4-a6d3-4da6-8e4b-dd0e926219e6"},{"name":"Catálogo","item":[{"name":"1. Cadastro de Categorias","item":[{"name":"Criar categoria","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{}}}],"id":"5e0d990d-9d6e-4c8c-9023-4af2d33abd94","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"A árvore de categorias da Salesrun segue a estrutura “departamento → grupo → sub-grupo” que muitas redes de varejo usam:
\nCadastre sempre do topo para baixo:
\nDepartamento (categoria sem parent_integration_code).
Grupo informando parent_integration_code do departamento.
Sub-grupo apontando para o grupo.
\nSe você enviar um produto antes de criar sua árvore, a Salesrun criará categorias “órfãs” sem hierarquia. Isso prejudica análises de ruptura e reposição por departamento.
\nPOST /categories\n{\n \"integration_code\": \"DEP_MERCEARIA\", // seu ID interno\n \"name\": \"Mercearia\", // Departamento (nível 0)\n \"parent_integration_code\": null\n}\nPOST /categories\n{\n \"integration_code\": \"GRP_BEBIDAS\",\n \"name\": \"Bebidas\", // Grupo (nível 1)\n \"parent_integration_code\": \"DEP_MERCEARIA\"\n}\nPOST /categories\n{\n \"integration_code\": \"SUB_REFRI\",\n \"name\": \"Refrigerantes\", // Sub-grupo (nível 2)\n \"parent_integration_code\": \"GRP_BEBIDAS\"\n}\n\nUse sempre o integration_code do seu ERP; ele é a chave de idempotência.
Precisa reestruturar? Faça PUT no grupo/sub-grupo para trocar o parent_integration_code.
Não há limite rígido de níveis, mas três são suficientes para 99 % dos ERPs.
\nCategorias ✅
\nProdutos
\nFornecedores
\nPedidos de compra
\nVendas
\nA API de Produtos funciona no conceito um SKU × filial.
\nEnvio inicial: cada requisição POST/PUT deve conter o branch_integration_code da loja ou CD que está reportando o SKU.
Criação automática: se o SKU ainda não existir na conta, ele é criado como “produto global” na primeira chamada.
\nVínculo com a filial: a cada chamada subsequente (mesmo SKU, outra filial) a Salesrun cria ou atualiza o vínculo desse SKU com a nova loja, armazenando parâmetros específicos daquela filial.
\nParâmetros por loja: estoque atual, preço, estoque mínimo, data da última compra, tipo de aquisição, is_purchase_disabled e todas as variáveis operacionais são sempre gravados por filial. Atualize-os enviando novamente o objeto completo ou apenas os campos que mudaram.
Campos gerais do SKU: atributos corporativos (nome, categoria, marca, família, unidade, embalagem, lista de EANs) são únicos para toda a conta; basta enviar a alteração em qualquer branch_integration_code e o cadastro principal será atualizado automaticamente.
Envie um objeto por loja. Se o mesmo SKU existir em 20 lojas, mande 20 objetos, cada um com seu _branch_integration_code_ e parâmetros.
Idempotência – POST com o mesmo par (branch_integration_code, sku) retorna 409 Conflict; use PUT para sobrescrever ou PATCH futuro.
Limite de lote – Máx 500 itens por chamada (POST ou PUT).
\nCurva A de performance – Envie campos de estoque uma vez ao dia ou quando houver movimentação relevante.
\nCategorias & marcas – Se não existirem, serão criadas “on-the-fly”; porém é fortemente recomendado cadastrar antes pelo menos as categorias para evitar problemas de hierarquia.
\nUnicidade de SKU – Um SKU é único na companhia; mesma descrição mas outro código → use modify-sku se precisar renomear.
Atualizar estoque/preço (stock, price, cost_price ) por filial.
\nCaso necessário: ajustar parâmetros de segurança (minimum_stock, safety_stock_day, display_stock).
\nRevisar is_purchase_disabled antes de ciclos automáticos de compra.
Com este modelo, você integra cadastro + estoques + preços em um único payload por filial, garantindo que a Salesrun enxergue cada loja de forma independente, mas ainda consolide a demanda pelo SKU global para projeções corporativas.
\nCategorias ✅
\nProdutos ✅
\nFornecedores
\nPedidos de compra
\nVendas
\nThis endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","suppliers",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"7f21e33c-93b9-4edb-8333-f32ec6891ae2","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"integration_code\": \"C123456\",\n \"name\": \"ABC Supplies Ltd.\",\n \"short_name\": \"ABC Supplies\",\n \"registered_number\": \"12345678000190\",\n \"document\": \"DOC12345\",\n \"postal_code\": \"12345-678\",\n \"address\": \"Rua das Flores, 100\",\n \"address_number\": \"100\",\n \"complement\": \"Sala 201\",\n \"zone\": \"Centro\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"active\": true\n }\n]\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/suppliers/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 11:45:56 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"16"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n}"},{"id":"bf11276b-3839-4d91-9a4b-9a61d83cc603","name":"400 - Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"integration_code\": \"C123456\",\n \"name\": \"ABC Supplies Ltd.\",\n \"short_name\": \"ABC Supplies\",\n \"registered_number\": \"12345678000190\",\n \"document\": \"DOC12345\",\n \"postal_code\": \"12345-678\",\n \"address\": \"Rua das Flores, 100\",\n \"address_number\": \"100\",\n \"complement\": \"Sala 201\",\n \"zone\": \"Centro\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"active\": true\n }\n]\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/suppliers/"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 11:47:33 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"182"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[{"expires":"Invalid Date","domain":"","path":""}],"responseTime":null,"body":"{\n \"error\": \"Any valid company supplier to insert. [{'company_supplier': \\\"Company supplier 'C123456' already exists in 'ABC Supplies Ltd.'\\\"}]\",\n \"status_code\": 400,\n \"code\": \"invalid_data\"\n}"}],"_postman_id":"2ae27099-62f3-4f44-ab2d-4be523c57c26"},{"name":"Atualizar fornecedor","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{}}}],"id":"2402ecf9-bfb2-4f3f-b772-24a711ca97a9","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Um forencedor representa qualquer parceiro que possa abastecer um SKU — indústria, distribuidor, atacadista, trading company.
\nEle precisa existir antes de enviarmos Parâmetros de Compra e Pedidos de Compra, pois esses recursos referenciam o campo supplier_integration_code.
Categorias ✅
\nProdutos ✅
\nFornecedores ✅
\nPedidos de compra
\nVendas
\nOs Pedidos de Compra representam compromissos formais de reposição junto a cada fornecedor. Eles são
\nessenciais para que a Salesrun:
\nprojete a cobertura futura de estoque,
\nevite recomendações duplicadas,
\nmonitore atrasos e sugerir expedições emergenciais.
\nPré-requisitos Fornecedores e parâmetros de compra já devem estar integrados.
\nAutenticação: Bearer Token (scope write para POST/PUT/DELETE, read para GET).
\nRegras – Para POST cada item exige: sku, ordered_quantity e delivered_quantity (mesmo que seja 0).
Pedido criado no ERP → POST /purchase-orders/ (status PENDING).
Fornecedor confirma entrega parcial → PUT /purchase-orders/ atualizando itens (delivered_quantity) e, se aplicável, cabeçalho (status DELAYED).
Pedido 100 % entregue → PUT marcando status FINISHED e preenchendo delivery_date.
Erro de digitação? → DELETE /purchase-orders/{integration_code}/ e re-crie corretamente.
Categorias ✅
\nProdutos ✅
\nFornecedores ✅
\nPedidos de compra ✅
\nVendas
\nOs parâmetros de compra descrevem como cada filial compra de cada fornecedor:
\nLead time (dias entre pedido e entrega)
\nFrequência (ex.: toda 2ª feira, quinzenal, mensal)
\nCategorias elegíveis
\nOpção de criar pedido automático quando chegar a data programada
\nEsses parâmetros alimentam os algoritmos que geram recomendações de pedido e as datas previstas de reposição.
\n¹ Obrigatório se quiser usar interval. ² Obrigatório quando interval_type = WEEK.
Campos obrigatórios marcados no esquema: branch_integration_code, supplier_integration_code, integration_code, lead_time.
Embora opcionais, os parâmetros de compra são altamente recomendados, pois desempenham um papel crucial na auditoria dos pedidos de compra e no funcionamento eficaz da reposição automatizada.
\n","_postman_id":"10610b20-d756-40d7-99b7-4e89f8964770"},{"name":"4. Pooling de Pedidos","item":[],"id":"4f7ec43c-0e8a-4cbc-a02f-6883efb3c14a","description":"Este endpoint implementa uma estratégia de polling para consumo de eventos de novos pedidos de compra sugeridos gerados pela plataforma Salesrun. Ele é utilizado para monitorar continuamente a criação de novos pedidos sugeridos e garantir que o ERP parceiro possa reagir em tempo real.
\nSempre que a Salesrun gerar um novo pedido de compra com base nos dados integrados e nos algoritmos de previsão de demanda, um evento será disponibilizado nesse endpoint.
\nO ERP realiza chamadas periódicas ao GET /v1/purchase-orders/events para verificar se há novos eventos.
Caso um ou mais eventos sejam retornados, o ERP deve:
\nRealizar um GET /v1/purchase-orders/{id} utilizando o purchase_order_id retornado no evento, para obter os detalhes completos do pedido sugerido.
Processar o pedido conforme sua lógica interna (criar no ERP, analisar, etc).
\nFinalizar o ciclo com um POST /v1/purchase-orders/events/ack, informando que o evento foi processado com sucesso. Isso evita reprocessamentos.
This endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","sales-orders","items","batch",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"735f4331-f5d1-42ac-bd25-a91840d75703","name":"400 - Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"integration_code\": \"PO123456\",\n \"sale_number\": \"ORD-2024-001\",\n \"branch_integration_code\": \"C01\",\n \"sale_date\": \"2024-05-01\",\n \"order_status\": \"PENDING\",\n \"total\": 10000.00,\n \"total_discount\": 500.00,\n \"total_addition\": 150.00,\n \"delivery_fee\": 100.00,\n \"invoiced_amount\": 9600.00,\n \"payment_method\": \"Credit Card\",\n \"payment_condition\": \"30 days\",\n \"payment_integration_code\": \"PAY123\",\n \"customer_id\": \"CUST123\",\n \"customer_name\": \"Customer XYZ\",\n \"address\": \"Rua das Flores, 123\",\n \"neighborhood\": \"Centro\",\n \"postal_code\": \"12345-678\",\n \"state\": \"SP\",\n \"city\": \"Metropolis\",\n \"channel\": \"Online\",\n \"salesman\": \"João da Silva\",\n \"salesman_integration_code\": \"SAL123\",\n \"order_add_information\": \"No additional info\",\n \"sku\": \"SKU123\",\n \"ean\": \"EAN234\",\n \"product_name\": \"Produto Exemplo 1\",\n \"quantity_ordered\": 10.000,\n \"quantity_delivered\": 0.000,\n \"value\": 90.00,\n \"discount\": 10.00,\n \"addition\": 0.00,\n \"add_information\": \"Handle with care\",\n \"status\": \"PENDING\",\n \"tags\": [\n {\n \"key\": \"key1\",\n \"value\": \"value1\"\n },\n {\n \"key\": \"key2\",\n \"value\": \"value2\"\n }\n ]\n }\n]\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/sales-orders/items/batch/"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 04 Jun 2025 13:37:16 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"113"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"POST, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Company branch not found for 'branch_integration_code': 'C01'\",\n \"status_code\": 400,\n \"code\": \"invalid_data\"\n}"},{"id":"40b8b8cb-92c8-48c8-9a5a-0c50bd5e53f4","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"integration_code\": \"ORDERITEMID124\",\n \"branch_integration_code\": \"BRANCH02\",\n \"sale_number\": \"S-20240601\",\n \"sale_date\": \"2024-06-01\",\n \"sku\": \"SKU-002\",\n \"quantity_ordered\": 1,\n \"quantity_delivered\": 2,\n \"value\": 100,\n \"status\": \"FINISHED\"\n },\n {\n \"integration_code\": \"ORDERITEMID125\",\n \"branch_integration_code\": \"BRANCH02\",\n \"sale_number\": \"S-20240601\",\n \"sale_date\": \"2024-06-01\",\n \"sku\": \"SKU-003\",\n \"quantity_ordered\": 5,\n \"quantity_delivered\": 5,\n \"value\": 97.5,\n \"status\": \"FINISHED\"\n }\n]\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/sales-orders/items/batch/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 04 Jun 2025 13:44:16 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"63"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"POST, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"status\": 200,\n \"description\": \"Batch items created successfully\"\n}"}],"_postman_id":"eef6e47a-dffc-4e19-981f-bf777551d71f"}],"id":"5ee19d7a-7aeb-418b-9ca4-08c87672d644","description":"Os pedidos de venda registram toda saída de mercadoria e são a base dos modelos de demanda da Salesrun.
\nA API de vendas permite o envio de vendas em formato linha a linha, onde cada item vendido representa um registro único contendo os dados do cabeçalho da venda e do item vendido.
\nEste modelo facilita integrações com sistemas que exportam vendas a partir de estruturas tabulares (como planilhas ou tabelas SQL), além de permitir batches de até 500 linhas por requisição.
\nAutenticação: Authorization: Bearer
Cada objeto representa um item vendido junto com os metadados do pedido.
\nEnvie as vendas em tempo próximo ao real, no máximo D-1
\nPara devoluções ou cancelamentos, utilize order_status: CANCELED enviando o mesmo id da venda no campo order_integration_code.
[\n {\n \"integration_code\": \"ORDER123\",\n \"sale_number\": \"S-20240601\",\n \"branch_integration_code\": \"BRANCH01\",\n \"sale_date\": \"2024-06-01\",\n \"order_status\": \"PENDING\",\n \"order_total\": 250.5,\n \"order_total_discount\": 10,\n \"order_total_addition\": 5,\n \"delivery_fee\": 15,\n \"order_invoiced_amount\": 240.5,\n \"payment_method\": \"credit_card\",\n \"payment_condition\": \"30 days\",\n \"payment_integration_code\": \"PMT001\",\n \"customer_id\": \"123e4567-e89b-12d3-a456-426614174000\",\n \"customer_name\": \"João da Silva\",\n \"address\": \"Rua das Laranjeiras, 123\",\n \"neighborhood\": \"Centro\",\n \"postal_code\": \"12345-678\",\n \"state\": \"SP\",\n \"city\": \"São Paulo\",\n \"channel\": \"Online\",\n \"salesman\": \"Carlos V.\",\n \"salesman_integration_code\": \"SLSM001\",\n \"order_add_information\": \"No order additional information\",\n \"sku\": \"SKU-001\",\n \"ean\": \"7891234567890\",\n \"product_name\": \"Test Product\",\n \"quantity_ordered\": 2,\n \"quantity_delivered\": 2,\n \"value\": 100,\n \"discount\": 5,\n \"addition\": 2,\n \"add_information\": \"No observations\",\n \"status\": \"PENDING\",\n \"tags\": [\n {\n \"key\": \"section\",\n \"value\": \"promo\"\n }\n ]\n }\n]\n\n[\n {\n \"integration_code\": \"ORDERITEMID124\",\n \"branch_integration_code\": \"BRANCH02\",\n \"sale_number\": \"S-20240601\",\n \"sale_date\": \"2024-06-01\",\n \"sku\": \"SKU-002\",\n \"quantity_ordered\": 1,\n \"quantity_delivered\": 2,\n \"value\": 100,\n \"status\": \"FINISHED\"\n },\n {\n \"integration_code\": \"ORDERITEMID125\",\n \"branch_integration_code\": \"BRANCH02\",\n \"sale_number\": \"S-20240601\",\n \"sale_date\": \"2024-06-01\",\n \"sku\": \"SKU-003\",\n \"quantity_ordered\": 5,\n \"quantity_delivered\": 5,\n \"value\": 97.5,\n \"status\": \"FINISHED\"\n }\n]\n\nCategorias ✅
\nProdutos ✅
\nFornecedores ✅
\nPedidos de compra ✅
\nVendas ✅
\nThis endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","campaign",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"b7da8230-a6de-4c97-93de-58eceade2f5f","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"{\n \"branch_integration_code\": \"C01\",\n \"name\": \"PROMO\",\n \"integration_code\": \"P001\",\n \"type\": \"SALE\",\n \"media_type\": \"TV\",\n \"products\": [\n {\n \"sku\": \"11111111\",\n \"integration_code\": \"01\",\n \"current_price\": 150,\n \"promotional_price\": 150,\n \"buy_quantity\": null,\n \"pay_quantity\": null,\n \"start_date\": \"2025-01-17T21:00:52.113Z\",\n \"end_date\": \"2025-01-17T21:00:52.113Z\",\n \"tags\": [\n {\n \"key\": \"key1\",\n \"value\": \"value1\"\n },\n {\n \"key\": \"key2\",\n \"value\": \"value2\"\n }\n ]\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/campaign/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 17:49:38 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"115"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, DELETE, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"request_id\": \"96fa30e8-4ad8-452d-83d4-22f838011c5f\",\n \"description\": \"Campaign saved. Processing products in queue.\"\n}"},{"id":"471ca8a3-c246-43fa-83f3-348f16e6b5e2","name":"400 - Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"{\n \"branch_integration_code\": \"C01\",\n \"name\": \"PROMO\",\n \"integration_code\": \"P001\",\n \"type\": \"SALE\",\n \"media_type\": \"TV\",\n \"products\": [\n {\n \"sku\": \"11111111\",\n \"integration_code\": \"01\",\n \"current_price\": 150,\n \"promotional_price\": 150,\n \"buy_quantity\": null,\n \"pay_quantity\": null,\n \"start_date\": \"2025-01-17T21:00:52.113Z\",\n \"end_date\": \"2025-01-17T21:00:52.113Z\",\n \"tags\": [\n {\n \"key\": \"key1\",\n \"value\": \"value1\"\n },\n {\n \"key\": \"key2\",\n \"value\": \"value2\"\n }\n ]\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/campaign/"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 17:51:20 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"107"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, DELETE, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Branch not found. (branch_integration_code = 'C01')\",\n \"status_code\": 400,\n \"code\": \"branch_not_found\"\n}"}],"_postman_id":"9a0f14e1-4933-4718-b741-48076fcd5e34"},{"name":"Atualizar promoção","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{}}}],"id":"b6884b75-e03c-4983-a4e8-bca86290c158","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","campaign",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"4939a82a-6fd4-4909-b755-b7ec8391f78c","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"{\n \"branch_integration_code\": \"C01\",\n \"name\": \"PROMO\",\n \"integration_code\": \"P001\",\n \"type\": \"SALE\",\n \"media_type\": \"TV\",\n \"products\": [\n {\n \"sku\": \"11111111\",\n \"integration_code\": \"01\",\n \"current_price\": 150,\n \"promotional_price\": 150,\n \"buy_quantity\": null,\n \"pay_quantity\": null,\n \"start_date\": \"2025-01-17T21:00:52.113Z\",\n \"end_date\": \"2025-01-17T21:00:52.113Z\",\n \"tags\": [\n {\n \"key\": \"key1\",\n \"value\": \"value1\"\n },\n {\n \"key\": \"key2\",\n \"value\": \"value2\"\n }\n ]\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/campaign/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 17:49:38 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"115"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, DELETE, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"request_id\": \"96fa30e8-4ad8-452d-83d4-22f838011c5f\",\n \"description\": \"Campaign saved. Processing products in queue.\"\n}"},{"id":"8a0a3b2f-4b7d-408c-9968-d91c5ec1e6a2","name":"400 - Bad Request","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"{\n \"branch_integration_code\": \"C01\",\n \"name\": \"PROMO\",\n \"integration_code\": \"P001\",\n \"type\": \"SALE\",\n \"media_type\": \"TV\",\n \"products\": [\n {\n \"sku\": \"11111111\",\n \"integration_code\": \"01\",\n \"current_price\": 150,\n \"promotional_price\": 150,\n \"buy_quantity\": null,\n \"pay_quantity\": null,\n \"start_date\": \"2025-01-17T21:00:52.113Z\",\n \"end_date\": \"2025-01-17T21:00:52.113Z\",\n \"tags\": [\n {\n \"key\": \"key1\",\n \"value\": \"value1\"\n },\n {\n \"key\": \"key2\",\n \"value\": \"value2\"\n }\n ]\n }\n ]\n}\n","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/campaign/"},"status":"Bad Request","code":400,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Fri, 30 May 2025 17:51:20 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"107"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, PUT, DELETE, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"error\": \"Branch not found. (branch_integration_code = 'C01')\",\n \"status_code\": 400,\n \"code\": \"branch_not_found\"\n}"}],"_postman_id":"b6884b75-e03c-4983-a4e8-bca86290c158"},{"name":"Excluir promoção","id":"a64903ed-f9e8-4a38-b065-c12bdff08ee1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Converte promoções em eventos de demanda que treinam os modelos de ML da Salesrun.
\nImpede que picos promocionais sejam confundidos com tendência orgânica.
\nPermite simular impacto futuro (ex.: Black Friday) nas recomendações de compra.
\nUse sempre /api/v1/campaign/. Cada payload descreve uma promoção e todas as regras de produto dentro dela.
1️⃣ Obrigatório quando _type = SALE_ (desconto).
2️⃣ Obrigatório quando _type = BUY_AND_PAY_ (leve X pague Y).
Campos requeridos confirmados no schema: current_price, start_date, end_date.
Confirme que Produtos das ofertas já estão cadastrados.
\nCrie antes de começar – envie a promo,cão pelo menos 24 h antes de start_date para que o modelo ajuste a previsão.
Atualize preços reais – ao final da promoção, mantenha current_price sincronizado via /products ou nova promoção.
Remova promoções canceladas com DELETE; não deixe ofertas fantasmas no histórico.
\nCom essa integração, a Salesrun reconhecerá cada promoção, ajustará previsões de demanda e recomendará compras suficientes para cobrir o aumento (ou queda) esperado de vendas.
\n","_postman_id":"be8b86a4-ea79-46bd-b074-4398bf76f5dd"},{"name":"Tags","item":[{"name":"Criar tag","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{}}}],"id":"f6bfd8b1-8cb7-42cd-b4fd-8bcfabe4bb65","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","tags",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"40622eb6-1908-4947-a0cb-cc1f68cfe857","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"key\": \"mechanic\",\n \"value\": \"combo\"\n }\n]","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/tags/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 04 Jun 2025 14:49:18 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"16"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n}"}],"_postman_id":"f6bfd8b1-8cb7-42cd-b4fd-8bcfabe4bb65"},{"name":"Listar tags","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{}}}],"id":"4c322196-338f-4970-bbc2-5d0649fed104","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"As tags são metadados utilizados para enriquecer o histórico de vendas e campanhas, permitindo a geração de modelos de previsão customizados na Salesrun.
\nCom a integração:
\nPermite análises detalhadas por tipo de promoção, canal de divulgação e outras mecânicas.
\nEnriquece os eventos de campanha e venda com contexto adicional.
\nAjuda os modelos de ML a entender melhor o impacto de diferentes estratégias promocionais e gerar previsões mais precisas por cluster, canal ou tipo de estímulo.
\nUse sempre /api/v1/tags/. Cada tag é composta por uma chave (key) e um valor (value). Exemplo: { \"key\": \"mechanic\", \"value\": \"combo\" }.
/api/v1/tags/Envia um array de objetos com a seguinte estrutura:
\n[\n {\n \"key\": \"mechanic\",\n \"value\": \"combo\"\n },\n {\n \"key\": \"channel\",\n \"value\": \"whatsapp\"\n }\n]\n\nThis endpoint allows you to create a new category using the HTTP POST method.
\n","urlObject":{"path":["api","v1","product-search",""],"host":["{{base_url}}"],"query":[],"variable":[]}},"response":[{"id":"551eb8c6-05a6-4f27-a1f1-7a6822416f90","name":"200 - OK","originalRequest":{"method":"POST","header":[{"key":"Content-Type","value":"multipart/form-data","disabled":true}],"body":{"mode":"raw","raw":"[\n {\n \"key\": \"mechanic\",\n \"value\": \"combo\"\n }\n]","options":{"raw":{"language":"json"}}},"url":"{{base_url}}/api/v1/tags/"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Date","value":"Wed, 04 Jun 2025 14:49:18 GMT"},{"key":"Content-Type","value":"application/json"},{"key":"Content-Length","value":"16"},{"key":"Connection","value":"keep-alive"},{"key":"Vary","value":"Accept"},{"key":"Allow","value":"GET, POST, HEAD, OPTIONS"},{"key":"X-Frame-Options","value":"DENY"},{"key":"X-Content-Type-Options","value":"nosniff"},{"key":"Referrer-Policy","value":"same-origin"},{"key":"Cross-Origin-Opener-Policy","value":"same-origin"},{"key":"Strict-Transport-Security","value":"max-age=31536000; includeSubDomains"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true\n}"}],"_postman_id":"9f055148-83d3-441d-83da-817b98a465e5"},{"name":"Listar Consultas","event":[{"listen":"test","script":{"id":"deaccb85-5b5c-4e10-88e8-721d27426393","exec":[""],"type":"text/javascript","packages":{},"requests":{}}}],"id":"387ec36b-94a1-40a5-994a-583c42ff9a05","protocolProfileBehavior":{"disableBodyPruning":true,"disabledSystemHeaders":{}},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"As tags são metadados utilizados para enriquecer o histórico de vendas e campanhas, permitindo a geração de modelos de previsão customizados na Salesrun.
\nCom a integração:
\nPermite análises detalhadas por tipo de promoção, canal de divulgação e outras mecânicas.
\nEnriquece os eventos de campanha e venda com contexto adicional.
\nAjuda os modelos de ML a entender melhor o impacto de diferentes estratégias promocionais e gerar previsões mais precisas por cluster, canal ou tipo de estímulo.
\nUse sempre /api/v1/tags/. Cada tag é composta por uma chave (key) e um valor (value). Exemplo: { \"key\": \"mechanic\", \"value\": \"combo\" }.
/api/v1/tags/Envia um array de objetos com a seguinte estrutura:
\n[\n {\n \"key\": \"mechanic\",\n \"value\": \"combo\"\n },\n {\n \"key\": \"channel\",\n \"value\": \"whatsapp\"\n }\n]\n\n