Onde encontrar o manual da API e dos Webhooks da Braavo

Se a sua loja vai se conectar a um sistema externo (um ERP, um aplicativo próprio ou uma integração sob medida), quem cuida do desenvolvimento vai precisar da documentação técnica da API. Tudo fica em um único endereço público: manual.braavo.com.br, que reúne os recursos da API e a documentação dos Webhooks.

Este artigo é uma visão geral para você entender o assunto antes de passar para a equipe técnica. Os detalhes de cada recurso estão sempre no manual acima.

Como a API funciona

A API da Braavo é REST e toda a troca de dados é feita em JSON. Os endereços (endpoints) usam o mesmo domínio da sua loja, sempre com https. Cada chamada precisa enviar dois cabeçalhos obrigatórios: o Content-Type: application/json e o de autenticação.

As operações seguem o padrão REST:

• POST: para criar um registro e também para as buscas, que enviam os filtros em um corpo JSON.
• PUT: para editar um registro existente.
• DELETE: para remover um registro.

Atenção: todos os parâmetros, inclusive os filtros de busca, vão no corpo da requisição em JSON, e não na URL. Por isso até as consultas enviam um corpo, em vez de usar parâmetros de endereço como em muitas APIs.

Autenticação

A API usa autenticação Basic, com duas credenciais combinadas: o API Token e o API Key. Essas credenciais são geradas dentro do painel, em ERPs > API Braavo!, e o passo a passo está no artigo Como gerar tokens da API Braavo.

Atenção: o API Key aparece uma única vez, no momento da criação. Anote as credenciais ali mesmo, porque depois não há como recuperá-las. Se perder, o caminho é gerar um token novo.

Limite de chamadas

A API aceita por volta de quatro requisições por segundo. O que passar desse ritmo é recusado com um aviso de erro, então a integração precisa respeitar um intervalo entre as chamadas.

Importante: não existe ambiente de testes (sandbox). Toda comunicação acontece em produção, com dados reais. Para testar sem afetar a loja, peça ao suporte o acesso a uma loja de testes.

Webhooks: a loja avisando o seu sistema

Enquanto a API serve para o seu sistema consultar a loja, o webhook faz o caminho contrário: sempre que um registro relevante é criado (como um novo pedido ou um carrinho abandonado), a loja envia automaticamente uma requisição para a URL que você cadastrou.

Dois pontos que a equipe técnica deve ter em mente:

• A URL cadastrada precisa estar no ar, aceitar requisições POST e responder com sucesso (um código da família 2xx) para confirmar o recebimento.
• O webhook traz os dados do evento, mas a recomendação é sempre confirmar a informação consultando o endpoint correspondente na API, usando os dados recebidos. Assim a integração trabalha sempre com o dado oficial e atualizado.