A Marcha oferece API e webhooks?
Sim. A Marcha tem integração por API e envio de eventos por webhook. A referência técnica oficial é https://docs.somosmarcha.com/, é lá que ficam a autenticação, os recursos que a sua conta pode chamar e os eventos que o seu contrato recebe.
Os dois resolvem problemas diferentes e costumam ser usados juntos. A API é você falando com a Marcha: criar uma cobrança, consultar o estado de uma transação, buscar dados para conciliar. O webhook é a Marcha falando com você: quando o estado de uma transação muda, a Marcha faz uma chamada para uma URL sua avisando da mudança.
A diferença prática é quem inicia a conversa. Sem webhook, seu sistema precisa ficar perguntando "já pagou?" de tempos em tempos. Isso gasta requisição, atrasa a liberação e piora conforme o volume cresce. Com webhook, a notificação chega quando o fato acontece.
Quando usar cada um
| O que você quer fazer | O que usar |
|---|---|
| Cobrar dentro do seu próprio checkout, sem tirar o cliente do seu site | API |
| Saber que um pagamento foi confirmado sem ficar consultando | Webhook |
| Conferir o estado atual de uma transação específica | Consulta pela API |
| Liberar acesso, emitir nota ou disparar envio automaticamente | Webhook para acordar o processo, API para confirmar o estado antes de agir |
| Fechar o caixa do dia e bater com o extrato | Consulta pela API, não webhook |
Essa última linha é o hábito que evita boa parte dos problemas: use o webhook como gatilho, não como fonte da verdade. Ao receber o evento, confirme o estado pela API antes de liberar mercadoria ou acesso.
Como começar
- Abra https://docs.somosmarcha.com/ e leia a parte de autenticação antes de qualquer outra, ela define o formato de todas as chamadas seguintes.
- Gere as credenciais de integração na área de configurações da sua conta e guarde-as fora do código, em variável de ambiente ou cofre de segredos.
- Verifique na documentação se há ambiente de teste liberado para o seu contrato e use-o antes de tocar em produção.
- Suba um endpoint público em HTTPS para receber os webhooks e cadastre essa URL na sua conta.
- Confira na documentação como verificar a autenticidade dos eventos recebidos e aplique essa verificação antes de processar qualquer coisa.
- Guarde o corpo bruto de todo evento recebido desde o primeiro dia. Quando algo der errado, esse log é o que sustenta o chamado.
O que exatamente a sua conta pode chamar e quais eventos ela recebe depende do arranjo contratado e dos meios de pagamento habilitados, os dois aparecem no contrato e na configuração da conta. A documentação é a fonte oficial. Dúvida de integração que a documentação não cobre: WhatsApp.
Obrigado pelo retorno.
Nesta categoria