A bol API é o fundamento técnico que permite aos vendedores automatizar os processos de negócios no bol.com. Seja para gerenciar pedidos, preços ou campanhas publicitárias - a bol API torna possível gerenciar tudo de forma programática, sem precisar clicar manualmente no portal de vendas. Neste artigo, explicamos como a bol API funciona, quais endpoints estão disponíveis, como começar e quando é melhor optar por uma integração pronta.
O que é a bol API e por que é importante?
API significa Interface de Programação de Aplicativos - uma interface técnica que permite que sistemas de software se comuniquem entre si. A bol API permite que os vendedores conectem seu próprio software ou ferramentas de terceiros à plataforma bol.com. Isso significa que você pode automatizar completamente processos como gerenciamento de pedidos, atualizações de estoque, ajustes de preços e confirmações de envio.
Para vendedores com mais de 50 produtos ou vários canais de venda, a bol API é quase indispensável. Trabalhar manualmente por meio do Painel do Vendedor (SDD) é demorado e propenso a erros. Com uma conexão de API, você não só economiza horas por semana, mas também minimiza erros que podem levar a pontuações de desempenho ruins.
De Plaza API para Retailer API
O bol.com substituiu completamente a antiga Plaza API pela mais moderna Retailer API. A Plaza API não é mais suportada e novas conexões só são possíveis por meio da Retailer API. Esta oferece melhor desempenho, mais endpoints, segurança aprimorada e documentação mais completa. Se você ainda usa uma conexão Plaza antiga, é essencial migrar o mais rápido possível.
As três APIs do bol.com explicadas
O bol.com oferece três APIs separadas que cobrem todo o espectro de funcionalidades do vendedor. Cada API tem seu próprio objetivo e conjunto de endpoints.
| API | Função principal | Endpoints principais | Adequado para |
|---|---|---|---|
| Retailer API | Gerenciamento de pedidos e produtos completo | Pedidos, Envios, Devoluções, Ofertas, Estoque, Comissão | Todos os vendedores |
| Offer API | Gerenciamento de ofertas e preços | Ofertas (CRUD), Preços, Atualizações de estoque, Conteúdo de produto | Vendedores com grandes catálogos |
| Advertiser API | Campanhas publicitárias e relatórios | Campanhas, Grupos de anúncios, Palavras-chave, Relatórios de desempenho | Vendedores com orçamento publicitário |
Bol Retailer API
A Retailer API é a mais completa e mais usada API do bol.com. Com ela, você pode automatizar quase todos os processos de venda: desde obter novos pedidos e confirmar envios até processar devoluções e obter relatórios de comissão. A Retailer API também suporta o gerenciamento de sua oferta de produtos, atualizações de níveis de estoque e obtenção de relatórios de desempenho.
Bol Offer API
A Offer API se concentra especificamente no gerenciamento de sua oferta de produtos. Com ela, você pode fazer upload de novos produtos, ajustar ofertas existentes, alterar preços e atualizar níveis de estoque. Para vendedores com centenas ou milhares de produtos, essa API é essencial para manter preços e estoque sincronizados em tempo real com seu sistema ERP ou WMS.
Bol Advertiser API
Com a Advertiser API, você automatiza suas campanhas de Sponsored Products. Você pode criar campanhas, gerenciar grupos de anúncios, ajustar ofertas e obter relatórios de desempenho detalhados - incluindo impressões, cliques, conversões e ACoS (Custo de Venda Publicitária). Isso é particularmente valioso se você executar várias campanhas ao mesmo tempo e quiser otimizar rapidamente com base em dados.
Endpoints e funcionalidades principais
A API da bol oferece dezenas de endpoints. Aqui está uma visão geral dos endpoints mais utilizados por categoria, para que você possa avaliar rapidamente quais são necessários.
| Categoria | Endpoint | Método | Descrição |
|---|---|---|---|
| Pedidos | /orders | GET | Obter todos os pedidos em aberto |
| Pedidos | /orders/{orderId} | GET | Visualizar detalhes de um pedido específico |
| Envio | /orders/{orderId}/shipment | PUT | Confirmar envio com rastreamento |
| Devoluções | /returns | GET | Obter devoluções em aberto |
| Devoluções | /returns/{returnId} | PUT | Tratar devolução (aceitar/recusar) |
| Ofertas | /offers | POST | Criar nova oferta de produto |
| Ofertas | /offers/{offerId} | PUT | Alterar preço, estoque ou condição |
| Estoque | /offers/{offerId}/stock | PUT | Atualizar nível de estoque |
| Comissão | /commission | GET | Obter porcentagens de comissão por categoria |
| Insights | /insights/performance | GET | Obter pontuações de desempenho e KPIs |
Autenticação e segurança
A API da bol utiliza OAuth 2.0 para autenticação. Isso significa que você primeiro precisa criar credenciais de API (ID do cliente e segredo do cliente) em sua conta de vendas da bol.com. Com essas credenciais, você solicita um token de acesso temporário que você envia com cada chamada de API.
Configurar autenticação passo a passo
- Entrar no portal de parceiros - Acesse sua conta de vendas na bol.com partner login e navegue até Configurações > Configurações de API
- Criar credenciais de API - Clique em "Criar novas credenciais de API" e armazene seu ID do cliente e segredo do cliente com segurança
- Solicitar token de acesso - Envie uma solicitação POST para o endpoint de token com suas credenciais (codificadas em Base64) para receber um token de portador
- Usar token - Adicione o token como cabeçalho de autorização em cada chamada de API
- Renovar token - Os tokens de acesso expiram após um determinado período; implemente a renovação automática de token em sua aplicação
Nunca armazene suas credenciais de API em repositórios de código público ou documentos compartilhados. Use variáveis de ambiente ou um gerenciador de segredos. Se você suspeitar de um vazamento, pode revogar suas credenciais imediatamente por meio do portal de parceiros.
Limites de taxa e boas práticas
A bol.com impõe limites de taxa estritos para proteger os servidores de API. Se você enviar muitas solicitações em um curto período de tempo, receberá um erro HTTP 429 (Muitas Solicitações). É importante projetar sua aplicação para respeitar os limites de taxa.
| Aspecto | Limite | Recomendação |
|---|---|---|
| Solicitações por minuto | Variável por endpoint | Implemente backoff exponencial em erros 429 |
| Operações em massa | Máximo de 1.000 itens por lote | Divida atualizações grandes em lotes menores |
| Validade do token | Vida útil limitada | Cache tokens e renove proativamente antes do vencimento |
| Limite diário | Dependente do tipo de conta | Monitore seu uso de API por meio do portal de parceiros |
| Solicitações concorrentes | Número limitado de solicitações simultâneas | Use uma fila de solicitações com controle de taxa |
Boas práticas para uso de API
- Utiliza webhooks - Em vez de fazer polling contínuo para novos pedidos, configure webhooks para que o bol.com notifique o seu servidor sobre alterações
- Implemente lógica de retry - Em caso de erros temporários (códigos de status 5xx), tente o pedido novamente com backoff exponencial
- Cache respostas - Armazene dados solicitados com frequência (como porcentagens de comissão) localmente para evitar chamadas de API desnecessárias
- Registre todas as chamadas de API - Mantenha um registro detalhado para depuração e monitoramento do uso da API
- Valide a entrada - Verifique os dados antes de enviá-los para a API para evitar mensagens de erro desnecessárias
Construir sozinho vs. integração pronta
Uma das decisões mais importantes para os vendedores é se devem construir software próprio na API do bol ou usar uma ferramenta existente. Ambas as opções têm prós e contras que dependem fortemente do seu conhecimento técnico, orçamento e escala.
| Critério | Construir sozinho | Ferramenta pronta |
|---|---|---|
| Custo inicial | €5.000–€15.000+ (tempo de desenvolvimento) | €0–€50/mês |
| Prazo | 2–6 meses | Disponível imediatamente |
| Manutenção | Necessária continuamente (atualizações de API) | Incluída pelo fornecedor |
| Flexibilidade | Permite trabalho personalizado completo | Limitado às funções oferecidas |
| Risco | Alto (dependência do desenvolvedor) | Baixo (plataforma comprovada) |
| Escalabilidade | Depende da arquitetura | Geralmente bem escalável |
| Suporte | Responsabilidade própria | Help desk e documentação disponíveis |
| Atualizações de API | Implementar sozinho | Atualizado automaticamente |
Quando construir sozinho é sensato
Construir sozinho só é sensato se você tiver um fluxo de trabalho muito específico que nenhuma ferramenta existente suporta, se tiver uma equipe de desenvolvimento dedicada que possa manter a conexão a longo prazo e se estiver disposto a arcar com os custos contínuos de manutenção e atualizações de API. Na prática, isso se aplica a menos de 5% dos vendedores.
Por que a maioria dos vendedores escolhe uma ferramenta
Para a grande maioria dos vendedores, uma ferramenta pronta é a escolha mais inteligente. Ferramentas como o Boloo oferecem integrações abrangentes com a API do bol sem que você precise programar. Você obtém acesso a funções como um rastreador de produtos, explorador de palavras-chave, painel de vendas e faturamento automático - todos construídos na API oficial do bol.
Erros comuns ao trabalhar com a API do bol
Muitos vendedores e desenvolvedores cometem os mesmos erros quando trabalham com a API do bol pela primeira vez. Conhecer esses erros pode ajudá-lo a economizar tempo e dinheiro valiosos.
- Não implementar tratamento de erros - A API pode estar temporariamente indisponível ou retornar respostas inesperadas. Sem um bom tratamento de erros, todo o seu sistema pode travar
- Ignorar limites de taxa - Muitos pedidos em um curto período de tempo levam ao bloqueio. Implemente sempre limitação de taxa e backoff exponencial
- Codificar credenciais - Colocar chaves de API no código-fonte é um risco de segurança grave. Use sempre variáveis de ambiente
- Não testar no sandbox - A Bol.com oferece um ambiente de teste. Use-o para testar sua integração antes de ir ao vivo
- Seguir documentação desatualizada - A API é atualizada regularmente. Consulte sempre a documentação oficial no portal de desenvolvedores da Bol.com
- Não configurar monitoramento - Sem monitoramento, você só nota problemas quando os clientes reclamam. Configure alertas para erros e atrasos
Como a Boloo utiliza a API da Bol de forma otimizada
A Boloo é totalmente construída sobre a API oficial da Bol e oferece aos vendedores uma interface de usuário amigável sobre a complexidade técnica. Onde você precisaria chamar endpoints e processar dados com a API bruta, a Boloo faz isso automaticamente em segundo plano.
- Product Tracker - Monitora concorrentes e alterações de preços via a Retailer API
- Product Database - Pesquise todo o sortimento da Bol.com com filtros avançados
- Keyword Verkenner - Analise volumes de busca e tendências via dados da API
- Ranking Checker - Acompanhe sua posição nos resultados de busca automaticamente
- Listing Generator AI - Otimiza suas páginas de produtos com base em insights da API
- Sales Dashboard - Dados de vendas e pedidos em tempo real via a Retailer API
- Winstcalculator - Calcula margens incluindo porcentagens de comissão atuais
- Automatische Facturatie - Gera faturas automaticamente para novos pedidos
- E-mail Campagnes - Envie campanhas direcionadas com base em dados de clientes
- LVB Box Size Checker - Otimiza custos de envio com os tamanhos de caixa certos
A vantagem de uma ferramenta como a Boloo é que você aproveita todas as possibilidades da API da Bol sem precisar ter conhecimento técnico. Atualizações da API são processadas automaticamente e você pode começar a otimizar suas vendas imediatamente.
Perguntas frequentes sobre a API da Bol
Onde encontro a documentação oficial da API da Bol?
A documentação oficial está disponível no portal de desenvolvedores da Bol.com. Aqui você encontrará descrições detalhadas de todos os endpoints, código de exemplo, um ambiente de teste e logs de alterações com as últimas atualizações. A documentação é atualizada regularmente com novos lançamentos.
Qual é a diferença entre a Retailer API e a antiga Plaza API?
A Plaza API foi totalmente descontinuada e não é mais suportada. A Retailer API é a sucessora com melhor desempenho, mais endpoints, autenticação OAuth 2.0 aprimorada e funcionalidade mais ampla. Todas as novas conexões devem ser construídas via a Retailer API. Conexões existentes da Plaza não funcionam mais.
Preciso ter conhecimento de programação para usar a API da Bol?
Para trabalhar diretamente com a API, você precisa ter conhecimento de programação em uma linguagem como Python, PHP, JavaScript ou C#. Não tem formação técnica? Então é melhor escolher uma ferramenta pronta para usar, como o Boloo, que cuida da integração da API para você, sem que você precise escrever código.
Há custos associados ao uso da API da bol?
O uso da API da bol em si é gratuito. Você não paga custos adicionais por chamadas de API. Os custos estão no desenvolvimento e manutenção do seu próprio software, ou na assinatura de uma ferramenta que usa a API para você. A bol.com apenas cobra a comissão de venda regular.
Com que frequência a API da bol é atualizada?
A bol.com atualiza regularmente a API com novos endpoints, funcionalidades melhoradas e patches de segurança. Grandes atualizações são anunciadas antecipadamente por meio do Portal do Desenvolvedor, com um período de migração. É importante seguir esses registros de alterações se você mantém uma conexão própria - com uma ferramenta pronta para usar, isso é tratado automaticamente.
Posso usar a API da bol para várias contas de venda?
Sim, você pode usar a API para várias contas de venda. Cada conta tem suas próprias credenciais de API. Ferramentas como o Boloo suportam a gestão de várias contas a partir de um único painel de controle, o que simplifica significativamente a visão geral para vendedores com várias marcas ou lojas.
Começa grátis com o Boloo
Usa as ferramentas do Boloo para vender de forma mais inteligente no bol.com. Experimenta grátis.
Experimenta o Boloo grátis
