Como integrar Mercado Pago com Tiny ERP para estoque: guia técnico com webhooks e API
Para conectar o Mercado Pago ao Tiny ERP e manter o estoque atualizado em tempo real, o caminho técnico passa por webhooks e chamadas à API: o Mercado Pago envia uma notificação ao seu servidor cada vez que um pagamento muda de status, e o script receptor consulta os detalhes da transação, identifica o produto pelo SKU e aciona a API do Tiny ERP para registrar a baixa no inventário. O processo envolve configurar credenciais em ambas as contas, criar um endpoint HTTPS receptor e desenvolver a lógica de sincronização com mapeamento de produtos.
Ao longo deste artigo, você vai encontrar os pré-requisitos técnicos para iniciar, o passo a passo de configuração de webhooks no Mercado Pago, a lógica de desenvolvimento do script de sincronização com mapeamento de SKU — a etapa que a maioria dos guias ignora —, como testar tudo no ambiente sandbox e as boas práticas de segurança para manter a integração estável no longo prazo. O conteúdo é voltado tanto para quem desenvolve a solução quanto para quem coordena o projeto técnico.
Pré-requisitos para integrar Mercado Pago com Tiny ERP no controle de estoque
Antes de iniciar a integração, é preciso reunir as credenciais de acesso e garantir que ambas as contas estejam configuradas para comunicação via API.
Credenciais do Mercado Pago: access token e configuração da aplicação
O ponto de partida é o portal Mercado Pago Developers, acessível em developers.mercadopago.com.br. Lá, é necessário criar uma aplicação — um registro que representa seu sistema e define quais permissões ele terá. Ao criar a aplicação, o portal gera dois conjuntos de credenciais: as de teste (sandbox) e as de produção.
O access token é a chave principal de autenticação. Ele segue o protocolo OAuth 2.0 e deve ser incluído no cabeçalho de cada requisição à API do Mercado Pago. As credenciais de teste permitem simular pagamentos sem movimentar dinheiro real, por isso é fundamental utilizá-las durante o desenvolvimento antes de ativar as credenciais de produção.
API Key do Tiny ERP e permissões necessárias
No painel do Tiny ERP, a API Key fica disponível na seção de configurações da conta, dentro do módulo de integrações. Ela funciona como o token de autenticação para todas as chamadas à API do Tiny e deve ter permissões habilitadas para os módulos de produtos e estoque.
Um ponto crítico nesta etapa é garantir que cada produto cadastrado no Tiny tenha um código SKU consistente. Esse código será o elo de ligação entre o item vendido via Mercado Pago e o registro no inventário do Tiny. Sem essa consistência, o mapeamento entre os dois sistemas falha e o estoque não é atualizado com precisão.
Como configurar webhooks no Mercado Pago para notificações de pagamento
Um webhook é uma notificação automática que o Mercado Pago envia ao servidor da sua aplicação toda vez que o status de um pagamento muda — por exemplo, de pendente para aprovado. A vantagem em relação ao polling (consulta periódica à API) é que o webhook elimina requisições desnecessárias e garante que a atualização do estoque ocorra logo após a confirmação do pagamento.
Para configurar, acesse a seção “Suas Aplicações” no portal Mercado Pago Developers, selecione a aplicação criada e localize a área de webhooks de notificações de pagamento. Informe a URL do endpoint receptor que você vai criar no seu servidor, selecione o evento payment e salve. A partir desse momento, cada mudança de status de pagamento vai disparar um POST para esse endereço com o ID da transação.
Um detalhe técnico importante: o webhook não envia os dados completos do pagamento, apenas o ID. O script receptor precisa usar esse ID para fazer uma requisição GET ao endpoint /v1/payments/{id} da API do Mercado Pago, usando o access token, para obter os detalhes completos — incluindo status, valor e itens da transação. O endpoint receptor deve estar em HTTPS, pois o Mercado Pago não envia notificações para URLs sem criptografia.
Script de sincronização: do pagamento aprovado à baixa no estoque do Tiny ERP
O script de integração é o núcleo técnico de todo o processo. Ele conecta a notificação de pagamento à atualização do inventário por meio de três etapas sequenciais.
Receber o webhook e consultar os dados do pagamento
O script — desenvolvido em Python, PHP, Node.js ou outra linguagem de sua preferência — precisa expor um endpoint que aceite requisições POST. Ao receber a notificação do Mercado Pago, o primeiro passo é extrair o ID do pagamento do corpo da requisição.
Com esse ID em mãos, o script faz uma chamada GET à API do Mercado Pago:
- Endpoint: /v1/payments/{id}
- Cabeçalho: Authorization: Bearer {access_token}
- Verificação do campo status: só avançar se o valor for “approved”
Se o status não for “approved”, o script deve retornar HTTP 200 para o Mercado Pago (confirmando o recebimento) e encerrar o processamento sem alterar o estoque. Isso evita baixas indevidas para pagamentos pendentes ou recusados.
Mapear o produto vendido ao SKU no Tiny ERP
Esta é a etapa que diferencia uma integração robusta de uma frágil. O objeto de pagamento retornado pela API do Mercado Pago contém o campo external_reference, que pode ser preenchido no momento da criação do pagamento com o SKU do produto. Quem desenvolve o checkout deve garantir que esse campo seja populado com o código que corresponde ao produto no Tiny ERP.
Há duas abordagens para o mapeamento:
- Uso direto do external_reference: o SKU é gravado nesse campo durante a criação do pagamento, e o script o lê sem precisar de nenhuma tabela intermediária.
- Tabela de mapeamento: uma estrutura de dados (banco de dados ou arquivo de configuração) que relaciona o ID do item no Mercado Pago ao código SKU no Tiny ERP — útil quando não é possível controlar o preenchimento do external_reference.
A consistência do SKU entre os dois sistemas é o requisito mais importante desta etapa. Se os códigos divergirem, o script não consegue identificar qual produto deve ter o estoque reduzido.
Atualizar o estoque com a API do Tiny ERP
Com o SKU identificado, o script faz uma chamada à API do Tiny ERP para registrar a baixa no estoque. O Tiny disponibiliza endpoints REST que permitem atualizar a quantidade disponível de um produto a partir do seu código.
A requisição deve incluir a API Key no cabeçalho ou como parâmetro, conforme a versão da API do Tiny em uso. Após enviar a atualização, o script precisa verificar a resposta: um retorno de sucesso confirma que a baixa foi registrada, enquanto um erro deve ser capturado, logado e, se possível, colocado em fila para nova tentativa. Tratar a resposta da API do Tiny não é opcional — é o que garante que nenhuma venda aprovada fique sem reflexo no inventário.
Como testar a integração de estoque no ambiente sandbox
Antes de ativar a integração em produção, todo o fluxo deve ser validado no ambiente de testes. O Mercado Pago oferece um sandbox completo que permite simular pagamentos aprovados, recusados e pendentes usando credenciais de teste e contas de usuário fictícias, sem nenhuma movimentação financeira real.
Para testar, configure o script com as credenciais de sandbox e crie um produto no Tiny ERP com estoque controlado — por exemplo, 10 unidades. Simule um pagamento aprovado pelo sandbox e verifique se o webhook é disparado, se o script processa a notificação e se o estoque no Tiny passa de 10 para 9 unidades. Repita o teste com um pagamento recusado para confirmar que o estoque permanece inalterado nesses casos.
O uso de logs detalhados no script é indispensável durante os testes. Cada etapa — recebimento do webhook, consulta à API do Mercado Pago, mapeamento do SKU e chamada à API do Tiny — deve gerar um registro com timestamp, dados recebidos e resultado da operação. Esses logs são o principal recurso para identificar onde o fluxo falha quando algo não funciona como esperado.
Boas práticas de segurança e manutenção da integração com Tiny ERP
Uma integração funcional em produção exige cuidados que vão além do desenvolvimento inicial. A segurança das credenciais e a resiliência do script determinam a confiabilidade do sistema ao longo do tempo.
Os pontos essenciais a implementar são:
- Armazenamento de credenciais em variáveis de ambiente: nunca incluir o access token do Mercado Pago nem a API Key do Tiny diretamente no código-fonte ou em repositórios versionados.
- HTTPS em todas as chamadas: tanto o endpoint receptor do webhook quanto as chamadas às APIs devem usar conexões criptografadas.
- Validação da origem do webhook: verificar a assinatura digital enviada pelo Mercado Pago no cabeçalho da notificação para confirmar que a requisição é legítima e não uma tentativa de injeção externa.
- Retentativas em caso de falha: implementar uma fila de processamento que reenvie a atualização ao Tiny ERP caso a API retorne erro temporário.
- Monitoramento com alertas: configurar alertas automáticos para falhas de sincronização, de modo que a equipe técnica seja notificada antes que as divergências de estoque se acumulem.
A manutenção contínua da integração evita que pequenas falhas silenciosas gerem discrepâncias entre o estoque real e o registrado no Tiny ERP. Uma revisão periódica dos logs e uma rotina de reconciliação — que compare os pagamentos aprovados com as baixas registradas — são as melhores formas de manter o inventário sempre preciso.
Perguntas frequentes sobre a integração do Mercado Pago com Tiny ERP para estoque
É possível integrar Mercado Pago com Tiny ERP sem programação?
Ferramentas no-code como Pluga e Albato oferecem conectores entre as duas plataformas, com gatilhos e ações pré-configurados que não exigem escrever código. Essas soluções são uma boa opção para quem precisa de uma integração rápida e sem suporte de desenvolvimento. A integração via API própria, como descrita neste guia, oferece mais controle sobre a lógica de mapeamento e o tratamento de erros, mas exige conhecimento técnico para ser implementada.
O que acontece se o webhook do Mercado Pago falhar?
O Mercado Pago possui um sistema de retentativas automáticas para webhooks que não recebem resposta HTTP 200 — o servidor tenta reenviar a notificação em intervalos crescentes. Do lado do servidor receptor, é recomendável implementar uma fila de processamento para lidar com falhas temporárias na API do Tiny ERP. Manter logs detalhados de cada notificação recebida facilita a identificação e a correção de falhas no recebimento.
Como evitar divergências de estoque entre o Mercado Pago e o Tiny ERP?
O primeiro passo é usar o mesmo código SKU em ambas as plataformas para garantir o mapeamento correto em todas as transações. Além disso, vale implementar uma rotina de reconciliação que compare os pagamentos aprovados com as baixas registradas no Tiny. Por fim, os cenários de estorno e cancelamento precisam ser tratados no script para que os itens retornem ao estoque quando uma venda for revertida.
A integração funciona para vendas feitas pelo Mercado Livre?
Não — a integração descrita neste artigo é voltada para pagamentos processados via Mercado Pago fora do ecossistema do Mercado Livre, como em checkouts de lojas próprias. O Tiny ERP possui integração nativa com o Mercado Livre, que já inclui sincronização de estoque e pedidos de forma separada. Para vendas no Mercado Livre, a configuração é diferente e feita no módulo de integrações do próprio Tiny.
Com o fluxo técnico mapeado — de credenciais a testes em sandbox —, o próximo passo é colocar a integração em prática. O portal Mercado Pago Developers reúne a documentação completa da API de pagamentos, os guias de configuração de webhooks e o ambiente de sandbox para testes. Acesse, gere suas credenciais de teste e comece a construir a integração com base nos endpoints e exemplos disponíveis na documentação oficial.
Consulte condições e tarifas em:
