A versão 3.1.8 da API do Olist ERP adicionou a categoria financeira ao fluxo dos pedidos, permitindo que sistemas externos definam, consultem, alterem ou removam essa informação. Embora a atualização pareça restrita a um novo campo técnico, ela pode interferir diretamente na classificação das receitas, na organização do fluxo de caixa, na conciliação e na qualidade dos relatórios gerenciais. Para empresas que recebem pedidos de lojas virtuais, marketplaces, hubs, CRM ou integrações personalizadas, a mudança exige uma decisão clara: quem será responsável por determinar a categoria financeira de cada venda — o Olist ERP ou o sistema de origem?
🔎 O que mudou na API 3.1.8 do Olist ERP
A Olist documentou na versão 3.1.8 da API v3 a inclusão do campo pagamento.categoria nos pedidos. A partir dessa atualização, uma integração pode informar o identificador de uma categoria financeira ao criar um pedido, alterar a categoria de um pedido existente, retirar a classificação ou consultar qual categoria está vinculada à venda. A novidade aproxima o fluxo comercial do controle financeiro e reduz a necessidade de correções manuais posteriores, desde que a integração tenha sido configurada com regras consistentes.
Na prática, o campo passa a ser aceito pelo endpoint POST /pedidos, utilizado para criar pedidos, e pelo endpoint PUT /pedidos/{idPedido}, responsável pela atualização de registros existentes. A consulta GET /pedidos/{idPedido} também retorna a categoria, incluindo seu identificador e sua descrição. Para localizar as opções disponíveis na conta, a integração deve consultar GET /categorias-receita-despesa, evitando trabalhar com códigos presumidos ou categorias copiadas de outro ambiente.
Esse cuidado é importante porque a categoria financeira não deve ser tratada como um texto livre. A API espera um identificador válido existente na conta. Caso o sistema externo envie um código inexistente, a Olist informa que a operação retorna erro 400 no campo pagamento.categoria.id. Portanto, além de mapear corretamente os identificadores, a integração precisa registrar e tratar esse retorno para impedir que uma falha de classificação interrompa silenciosamente o processamento de pedidos.
⚙️ O significado de omitir, preencher ou zerar o campo
O ponto mais relevante da atualização está no comportamento diferente adotado conforme a integração omite o campo, envia uma categoria válida ou informa o valor zero. Essa distinção precisa estar documentada no projeto, porque uma pequena alteração no payload pode produzir um resultado financeiro diferente do esperado, ainda que os demais dados do pedido permaneçam corretos.
Ao criar um pedido com POST /pedidos, se a integração não enviar pagamento.categoria.id, o Olist ERP aplica a categoria-padrão de venda configurada na conta. Esse comportamento pode ser adequado para empresas que utilizam uma única classificação para todas as receitas ou preferem centralizar a regra no próprio ERP. Entretanto, se diferentes lojas, marketplaces, unidades de negócio ou tipos de operação precisarem de categorias específicas, depender apenas do padrão poderá concentrar vendas distintas em uma mesma classificação.
Quando a integração envia um identificador válido, o pedido é criado com a categoria escolhida pelo sistema externo. Nesse cenário, a automação pode separar receitas por canal, operação ou regra comercial, desde que as categorias tenham sido previamente definidas no Olist ERP e mapeadas na integração. Já o envio do valor 0 determina que o pedido seja criado sem categoria, comportamento que não deve ser confundido com a simples ausência do campo: omitir faz o ERP aplicar a categoria-padrão, enquanto enviar zero impede essa classificação automática.
Na atualização de um pedido existente por PUT /pedidos/{idPedido}, a lógica também merece atenção. Se pagamento.categoria.id não for enviado, a categoria atual permanece inalterada. Se um identificador válido for informado, a categoria é substituída. Por sua vez, o valor 0 remove a categoria que já estava vinculada. Assim, uma integração que reutilize o mesmo objeto para criar e atualizar pedidos precisa diferenciar claramente os payloads, evitando remover classificações por engano durante atualizações de status, pagamento ou outros dados da venda.
💰 Por que essa mudança importa para a gestão financeira
Em uma operação de e-commerce, o pedido costuma percorrer diversos sistemas antes de aparecer nos relatórios financeiros. A venda pode nascer em um marketplace, passar por um hub, ser registrada no ERP, gerar nota fiscal, movimentar estoque e, posteriormente, alimentar contas a receber, conciliação e análises de resultado. Quando a categoria financeira é aplicada somente depois desse fluxo, cresce o risco de atrasos, classificações genéricas e retrabalho da equipe administrativa.
Com a categoria disponível na API, a classificação pode acompanhar o pedido desde sua criação. Isso abre espaço para uma organização mais coerente entre o canal de venda e os relatórios do ERP. Uma empresa pode, por exemplo, manter categorias separadas para vendas em marketplace, loja virtual própria, atacado, televendas ou operações B2B. Também pode definir regras diferentes para marcas, filiais ou projetos, desde que a estrutura de categorias represente de fato o modelo gerencial do negócio e não produza fragmentação excessiva.
Entretanto, o novo recurso não corrige sozinho uma estrutura financeira mal planejada. Se houver categorias duplicadas, nomes pouco claros ou critérios conflitantes, a automação apenas repetirá essas inconsistências em maior escala. Antes de ativar o envio do campo, é recomendável revisar o plano de categorias, alinhar a nomenclatura com a equipe financeira e definir quais informações realmente precisam aparecer nos relatórios. Para conhecer o papel do sistema na centralização dos processos empresariais, vale consultar o conteúdo da Polivision sobre o que é um sistema ERP e como escolher a solução adequada.
🛒 Quais operações podem ser afetadas
A atualização é especialmente relevante para empresas que criam ou atualizam pedidos por integrações próprias. Isso inclui lojas virtuais conectadas por middleware, hubs de marketplaces, aplicativos privados, portais B2B, sistemas de representantes, CRM, plataformas de televendas e rotinas automatizadas desenvolvidas internamente. Mesmo quando o pedido tem origem em um canal conhecido, pode existir uma camada intermediária responsável por transformar os dados antes de enviá-los ao ERP; é nessa etapa que o novo campo precisa ser avaliado.
Operações multicanal exigem atenção adicional, pois cada canal pode ter regras financeiras diferentes. Vendas realizadas no Mercado Livre, Shopee, Amazon ou TikTok Shop, por exemplo, podem ser analisadas separadamente das vendas da loja própria. Contudo, a categoria financeira não deve substituir outros controles, como canal de venda, intermediador, forma de pagamento, centro de custo ou marcador. Cada informação cumpre uma finalidade distinta, e misturá-las pode comprometer a leitura dos relatórios. A página da Polivision sobre integração de ERP com marketplaces explica como estoque, pedidos, faturamento e canais precisam funcionar de forma coordenada.
Clientes que utilizam o antigo Tiny, atualmente integrado ao ecossistema Olist, também devem observar a atualização quando houver aplicativos ou projetos baseados na API v3. A mudança não significa que todos os usuários precisem alterar imediatamente sua operação manual no ERP. O impacto se concentra, sobretudo, nos fluxos em que outro sistema cria ou edita pedidos. Para empresas que estão implantando ou reorganizando a plataforma, a página de configuração, integração e treinamento do Tiny ERP apresenta os principais pontos que devem ser estruturados para que o sistema acompanhe o crescimento do negócio.
🧭 A primeira decisão: qual sistema será a fonte oficial
Antes de alterar qualquer código, a empresa deve decidir qual aplicação será a fonte oficial da categoria financeira. Há três modelos comuns. No primeiro, o sistema externo escolhe a categoria e envia o identificador ao criar o pedido. No segundo, o sistema externo não envia o campo e permite que o Olist ERP aplique sua categoria-padrão. No terceiro, a categoria é definida depois por uma rotina específica. Ela segue regras que podem considerar canal, vendedor, filial, tipo de cliente ou natureza da operação.
Nenhum desses modelos é universalmente melhor. A escolha depende de onde as regras são mantidas, de quem possui responsabilidade sobre o cadastro financeiro e de quais sistemas conseguem auditar mudanças. O problema surge quando a decisão não é explícita. Se o marketplace ou middleware atribui uma categoria, enquanto o ERP ou outra automação também tenta substituí-la, a classificação pode variar conforme a ordem das integrações. Por isso, o desenho precisa definir propriedade do dado, momento da atualização, critérios de exceção e comportamento em caso de falha.
Também é recomendável evitar o uso de descrições como chave de integração. Nomes de categorias podem ser alterados pela equipe administrativa, conter variações de grafia ou existir em estruturas semelhantes. O identificador retornado pela API é a referência técnica adequada, mas deve ser armazenado com contexto e revisado sempre que houver mudança no cadastro. Em operações com mais de uma conta ou empresa, a equipe não deve presumir que os mesmos códigos representam as mesmas categorias em todos os ambientes; cada conta precisa ser consultada e validada.
🧪 Como testar a implementação com segurança
Uma atualização aparentemente simples deve passar por um roteiro de homologação. O primeiro teste consiste em consultar as categorias de receita e despesa existentes e registrar os identificadores aprovados para uso nos pedidos. Em seguida, deve-se criar um pedido sem enviar o novo campo e confirmar se a categoria-padrão foi aplicada. O segundo cenário deve utilizar uma categoria válida; o terceiro, o valor zero; e o quarto, propositalmente, um identificador inexistente para verificar se o erro 400 é capturado, registrado e encaminhado para tratamento.
Os testes de atualização são igualmente importantes. A equipe deve criar um pedido já categorizado e executar um PUT sem o campo para confirmar a preservação da informação. Depois, deve substituir a categoria por outra válida e, por fim, enviar zero para verificar a remoção. Em todos os casos, é necessário consultar novamente o pedido pelo endpoint de leitura e conferir o resultado no painel do ERP e nos relatórios que utilizam a categoria financeira.
Além do comportamento funcional, o projeto deve observar logs, filas de reprocessamento e alertas. Um pedido não pode desaparecer da operação porque a categoria estava incorreta, tampouco deve ser reenviado indefinidamente e gerar duplicidade. A integração precisa registrar o número do pedido, o identificador enviado, a resposta da API e a ação tomada em caso de rejeição. Quando houver grande volume, recomenda-se iniciar com poucos pedidos, acompanhar os resultados e ampliar gradualmente a ativação.
🛡️ Cuidados para evitar erros de classificação
O primeiro risco é utilizar uma categoria válida, porém inadequada. Nesse caso, a API aceitará o pedido, mas os relatórios poderão apresentar receitas no grupo errado. Como não há erro técnico, a inconsistência tende a ser percebida apenas na conferência financeira. Por isso, os testes devem envolver não somente a equipe de tecnologia, mas também a pessoa responsável pelo financeiro ou pela contabilidade gerencial.
Outro risco está na remoção involuntária da categoria durante uma atualização. Sistemas que montam payloads completos com valores padrão podem enviar 0 mesmo quando o objetivo era alterar somente outra informação. A regra recomendada é transmitir o campo apenas quando houver uma intenção clara de mantê-lo sob responsabilidade da integração. Em operações de atualização parcial, é essencial respeitar o comportamento documentado pela Olist e não assumir que zero e ausência tenham o mesmo significado.
Também convém estabelecer uma rotina periódica de auditoria. Uma amostra de pedidos deve ser comparada entre a origem, a integração e o Olist ERP, verificando canal, valor, pagamento e categoria. Se a empresa utiliza relatórios externos ou ferramentas de BI, a categoria retornada pela API deve ser incorporada de maneira consistente ao modelo de dados. Essa conferência ajuda a identificar mudanças de cadastro, novos canais sem mapeamento e regras que deixaram de representar a operação real.
📋 Checklist recomendado para clientes Polivision
Antes de utilizar o novo campo em produção, a Polivision recomenda confirmar os seguintes pontos:
- identificar todas as integrações que criam ou atualizam pedidos pela API v3;
- consultar as categorias existentes em cada conta do Olist ERP;
- definir qual sistema será responsável pela classificação financeira;
- documentar a diferença entre campo omitido, identificador válido e valor zero;
- mapear categorias por canal, unidade ou tipo de operação somente quando houver necessidade gerencial;
- testar criação, consulta, alteração, preservação e remoção da categoria;
- tratar o erro
400sem perder pedidos ou criar duplicidades; - registrar logs suficientes para auditoria e reprocessamento;
- validar o resultado nos relatórios financeiros com a equipe responsável;
- monitorar uma amostra de pedidos após a entrada em produção.
Esse checklist deve ser adaptado ao porte e à complexidade do cliente. Em uma empresa com uma única origem de vendas, a categoria-padrão pode ser suficiente. Já em uma operação multicanal, com diferentes unidades ou modelos comerciais, o mapeamento explícito tende a oferecer maior visibilidade, desde que seja mantido com disciplina.
🚀 O que muda na implantação do Olist ERP
A atualização da API reforça que uma implantação de ERP não deve se limitar à conexão técnica entre sistemas. É necessário compreender como os dados comerciais serão convertidos em informações financeiras úteis. Durante o diagnóstico, a equipe de implantação deve perguntar quais categorias já existem, como são utilizadas nos relatórios, se há separação por canal e quem pode alterar o cadastro. Essas respostas orientam tanto a configuração do ERP quanto o desenvolvimento das integrações.
Em projetos novos, o ideal é definir a arquitetura antes de liberar o primeiro lote de pedidos. Em ambientes existentes, a revisão pode ser feita sem interromper toda a operação: primeiro mapeiam-se os fluxos atuais, depois são homologadas as novas regras e, somente então, a categoria passa a ser enviada pela API. Essa abordagem reduz o risco de mudanças retroativas ou relatórios inconsistentes durante a transição.
A Polivision atua na implantação, configuração, treinamento e integração de ERPs com lojas virtuais e marketplaces. Se sua empresa utiliza o Olist ERP, integrações próprias ou fluxos que precisam conectar vendas e gestão financeira, fale com a equipe da Polivision para avaliar o desenho da operação, os testes necessários e a melhor forma de incorporar a nova categoria financeira sem comprometer pedidos e relatórios.
✅ Conclusão
A categoria financeira nos pedidos é uma evolução relevante da API v3 do Olist ERP porque permite que a classificação acompanhe a venda desde sua origem. Ao mesmo tempo, a novidade transfere para o projeto de integração uma decisão que antes poderia permanecer restrita ao cadastro interno do ERP. Omitir o campo, enviar um identificador ou enviar zero são ações diferentes e precisam ser tratadas de forma consciente.
Para aproveitar o recurso com segurança, a empresa deve revisar suas categorias, definir a fonte oficial do dado, mapear identificadores, testar todos os cenários e monitorar os primeiros pedidos processados. Quando tecnologia, operação e financeiro participam dessa decisão, a API deixa de ser apenas um conector e passa a contribuir para relatórios mais consistentes, melhor rastreabilidade e uma gestão preparada para crescer.
Fonte externa: Changelog oficial da Olist ERP API v3.1.8
