Idempotência

A idempotência garante que, não importa quantas vezes você invoque a mesma operação com os mesmos parâmetros, você terá o mesmo resultado final. Isso é especialmente útil para operações sensíveis que podem envolver perda de dinheiro ou uma experiência ruim para os clientes em cenários como cobranças duplicadas não intencionais ou pagamentos a uma conta bancária.

Com o produto de Débito Direto da Belvo, você pode fornecer uma Idempotency-Key nos cabeçalhos de uma solicitação HTTP para mitigar o risco de chamadas duplicadas a um recurso. Recomendamos usar um UUID gerado como chave.

Métodos suportados

Atualmente, as chaves de idempotência são suportadas para a seguinte operação da API:

Criar uma Solicitação de Pagamento

Ciclo de vida de uma chave de idempotência

Após uma chamada de API bem-sucedida (com um código de status HTTP 200 ou 201), nosso sistema armazena em cache a resposta juntamente com sua chave de idempotência correspondente. Quaisquer solicitações repetidas usando a mesma chave dentro de 24 horas retornarão o resultado em cache em vez de executar a operação novamente.

Política de expiração

As chaves de idempotência têm um Tempo de Vida (TTL) de 24 horas após o timestamp da solicitação inicial. Após esse período, uma chave reutilizada é tratada como uma nova solicitação, acionando uma nova operação e armazenando a nova resposta.

Mensagens de erro de idempotência

Você receberá um erro relacionado à sua chave de idempotência nos seguintes casos:

Caso	Descrição	Código HTTP	Mensagem de erro
Uso Concorrente da Chave	Você envia a mesma chave de idempotência para solicitações concorrentes	`400`	`Concurrent use of idempotency key`
Alteração dos Parâmetros da Solicitação	Você faz uma solicitação com uma chave não expirada com um payload diferente da solicitação inicial.	`400`	`Different input for unexpired idempotency key`

Lista de IPs Permitidos

Na Belvo, a segurança dos seus dados e operações é uma prioridade máxima. Por isso, oferecemos um recurso opcional, mas altamente recomendado, de lista de IPs permitidos para nossa API de Débito Direto.

Este recurso adiciona uma camada extra de segurança, pois garante que cada solicitação à API se origine de um endereço IP pré-aprovado, em conjunto com suas chaves de API. Mesmo que suas chaves de API sejam comprometidas, o risco de acesso não autorizado é significativamente reduzido, já que apenas solicitações de IPs confiáveis serão reconhecidas.

Solicitações de endereços IP não aprovados

Solicitações feitas de endereços IP não aprovados receberão um erro 401 Unauthorized.

Como configurar a lista de IPs permitidos

Para configurar a lista de IPs permitidos, entre em contato com support-directdebit@belvo.com com as seguintes informações:

Nome da empresa
Lista de IPs que você deseja permitir

Exemplo de Corpo de Email

Olá,

Gostaria de solicitar que os seguintes endereços IP sejam permitidos para minha integração com o Belvo Direct Debit:

- ip_address_1
- ip_address_2

Obrigado,

your_company_name

Nossa equipe entrará em contato caso precise de mais informações ou assim que os IPs forem permitidos.