Item 1
Ter uma loja ativa na Cestas App.
Manual da integração
Conecte sua loja ao Bling com o aplicativo público da Cestas App.
Este manual explica como a integração funciona hoje, quais dados técnicos são usados no aplicativo público e como concluir a autorização da conta sem precisar criar um aplicativo privado por loja.
Antes de começar
Pré-requisitos para conectar o aplicativo público
Antes de iniciar a autorização da conta, vale conferir estes pontos para evitar retrabalho no Bling e no painel da loja.
Item 2
Ter uma conta no Bling com permissão para autorizar aplicativos.
Item 3
Usar o aplicativo público da Cestas App, sem criar aplicativo privado por loja.
Item 4
Conferir se os escopos selecionados no Bling batem com o uso da integração.
Item 5
Definir um depósito padrão no painel da integração se quiser enviar o estoque da loja para o Bling.
Como usar
O fluxo recomendado para conectar uma loja
A conexão é iniciada pela própria loja, dentro do painel da Cestas App. Isso garante que a autorização do Bling fique vinculada ao tenant correto.
1. Entre no painel
Acesse o painel da sua loja na Cestas App e abra a área da integração com Bling.
2. Ative o Bling
Habilite a integração, ajuste depósito padrão se necessário e escolha os módulos que devem sincronizar.
3. Autorize a conta
Clique em Conectar com Bling e conclua a autorização OAuth da conta que será usada no ERP.
4. Valide a operação
De volta ao painel, confira o status da conexão, os webhooks e rode o teste de homologação quando precisar.
Dados técnicos
Referência do aplicativo público
Estes são os dados técnicos usados na configuração e na homologação do app público da plataforma.
Link de redirecionamento
https://app.cestas.app/api/storefront/bling/callbackCallback oficial usado no fluxo OAuth da plataforma.
Homepage do aplicativo
https://app.cestas.app/Página principal pública da Cestas App.
Manual do aplicativo
https://app.cestas.app/integracoes/blingManual público da integração e do processo de homologação.
Autenticação e segurança
- OAuth com troca de código por token no callback central da plataforma.
- JWT habilitado nas requisições de token e nas chamadas autenticadas do Bling.
- Refresh token usado quando o access token expira ou é invalidado.
- Cada loja autoriza a própria conta, mantendo separação segura entre tenants.
Escopos utilizados
Pedidos de Venda
Produtos
Controle de Estoque
Clientes e Fornecedores
Depósitos de Estoque
Salvar imagens dos Produtos
Salvar variações de Produtos
Sincronização
O que a integração faz hoje
A operação atual foi desenhada para empurrar dados da loja para o Bling, com controles separados por tipo de sincronização.
Produtos e variações
A loja envia produtos e variações para o Bling quando a sincronização de catálogo está ativa.
Estoque
Os saldos podem seguir nos dois sentidos: da loja para o Bling com depósito padrão e do Bling para a loja via webhook de estoque.
Novos pedidos
Pedidos realizados no site podem ser enviados automaticamente para o ERP.
Status do pedido
Mudanças importantes no fluxo do pedido podem atualizar a situação correspondente no Bling.
Produtos e variações
Quando acontece: Quando um produto ou variante é criado ou atualizado com a sincronização ativa.
Resultado esperado: A loja envia o cadastro correspondente para o Bling.
Estoque
Quando acontece: Quando há ajuste operacional de saldo e o módulo de estoque está habilitado.
Resultado esperado: O estoque pode ser enviado da loja para o Bling e também voltar do Bling para a loja pelos webhooks de estoque.
Pedidos
Quando acontece: Quando um pedido é realizado no site e o envio de pedidos está ativo.
Resultado esperado: O pedido pode ser criado no Bling com os dados principais da venda.
Status do pedido
Quando acontece: Quando o fluxo do pedido muda dentro da operação da loja.
Resultado esperado: A situação correspondente pode ser refletida no Bling.
Limitação atual: nesta versão, a integração não importa catálogo do Bling para dentro da loja. O fluxo principal continua sendo da loja para o ERP.
Homologação
Como validamos o aplicativo público
O painel da integração já executa a sequência oficial de homologação do Bling para ajudar no preparo da revisão.
Sequência coberta
GET, POST, PUT, PATCH e DELETE no fluxo de homologação de produtos, com encadeamento do header x-bling-homologacao entre as etapas.
Renovação de token
Se o Bling invalidar o access token durante a revisão, a integração usa o refresh token automaticamente e continua o teste.
GET
1. Buscar o produto-base
/homologacao/produtosO Bling retorna os dados que devem ser reutilizados nas etapas seguintes do teste.
POST
2. Criar o produto de homologação
/homologacao/produtosA integração envia o body retornado no passo anterior e recebe um id temporário.
PUT
3. Atualizar o produto
/homologacao/produtos/{id}O nome do produto é alterado para validar a etapa de atualização exigida pelo Bling.
PATCH
4. Alterar a situação
/homologacao/produtos/{id}/situacoesA situação é enviada para validar a mudança de estado do produto.
DELETE
5. Remover o produto
/homologacao/produtos/{id}A sequência é concluída removendo o item temporário usado no teste.
Importante: o Bling exige que o fluxo de homologação termine em até 10 segundos, mantendo o encadeamento correto do header de homologação entre as etapas. Se houver falha, refaça a conexão da conta e rode o teste novamente pelo painel.
Publicação
Checklist antes de solicitar revisão no Bling
Depois da homologação técnica, a revisão do aplicativo também observa se os dados públicos estão consistentes.
Checklist 1
Logo condizente com a Cestas App.
Checklist 2
Nome, descrição e descrição curta coerentes com a solução publicada.
Checklist 3
Homepage e manual públicos, sem exigir autenticação.
Checklist 4
Link de redirecionamento igual ao callback oficial da plataforma.
Checklist 5
Escopos compatíveis com a integração.
Checklist 6
Homologação concluída sem falhas antes de solicitar revisão.
Webhooks
Como acompanhar o retorno do Bling
Depois da conexão, a loja também expõe uma URL de webhook no submenu da integração para receber eventos de pedidos, produtos e estoque.
Se você precisar validar eventos recebidos, erros recentes ou a URL atual do webhook, abra a área de webhooks da integração dentro do painel da loja.
Erros comuns
O que revisar quando algo não sai como esperado
Estes são os cenários mais comuns quando a integração está sendo configurada, reconectada ou submetida para análise.
redirect_uri inválida
Confira se o aplicativo público no Bling está usando exatamente o callback da plataforma, sem diferença de domínio, protocolo ou barra.
Escopos insuficientes
Se produtos, estoque ou pedidos não sincronizarem, revise os escopos autorizados no aplicativo e refaça a conexão.
Depósito padrão ausente
Sem um depósito padrão configurado, o envio de estoque da loja para o Bling fica incompleto, mesmo com a integração conectada.
Conta não conectada
Se o painel mostrar integração ativa, mas sem conta autorizada, clique novamente em Conectar com Bling e conclua o OAuth até o retorno ao painel.
Falha na homologação
Execute a homologação pelo painel com a integração ativa. Se houver erro, copie a etapa com falha e envie ao suporte com o nome da loja.
Suporte
Se precisar de ajuda, fale com a gente
Se a conexão falhar, se o callback voltar com erro ou se algum fluxo não sincronizar como esperado, envie os dados abaixo no primeiro contato para agilizar o atendimento.
Contato
E-mail de suporte: [email protected]
Sempre que possível, envie o nome da loja, uma descrição objetiva do problema, prints da tela e o horário aproximado da falha.
Links úteis