Contexto
Neste artigo, iremos apresentar o fluxo de nossa API de Limites V2, onde é possível realizar o ajuste dos limites do cliente além do limite global, adicionar favorecidos para elevar seu teto operacional e, por fim, consultar os limites do cliente.
Esta API irá substituir totalmente a sua versão anterior, por isso, recomendamos realizarem a migração para a v2 o mais rápido possível!
Também estaremos introduzindo uma nova maneira para cálculo do transaction-hash via HMAC-SHA256 utilizando a concatenação do method e path com a sua Secret Key.
Pré-requisitos
- Estar autenticado com um token Bearer válido;
- Possuir a Secret Key do ambiente para o calculo do hash via HMAC-SHA256;
1. Ajuste de Limites
Diferente da versão anterior, a V2 permite que você gerencie os tetos por categoria. Embora todos os lançamentos ainda sejam validados baseando-se no Limite Global diário da conta, agora você pode definir limites específicos para cada tipo de transação. Isso significa que você determina o valor máximo que cada 'frente' (Pix, TED, Transferencia interna) pode consumir dentro do seu limite total disponível.
Também é possível alterar quando o período noturno irá iniciar através do campo "startNight". Os valores (horários) variam entre 20 e 22.
API de ajuste de limites:
Endpoint PATCH {{url}}/v2/accounts/{{branch}}/{{account}}/limits/
Como informamos anteriormente, o ajuste é parcial; você pode enviar apenas os blocos que deseja alterar (ex: apenas o horário noturno ou apenas o limite para transações Pix)
A baixo podemos ver um exemplo de payload onde está sendo alterado o limite global, limite de transferências pix, limite de transfêrencias internas e também alterando o período noturno para se iniciar as 22:
{
"limits": {
"global": {
"amount": "100000"
}
},
"transactionProductsLimit": {
"instantPayment": {
"amount": "1000"
},
"internalTransfer": {
"amount": "2000"
},
"times": {
"endNight": "06",
"startNight": "22"
}
}
}
Na response será possível notar que os valores que foram informados no body foram alterados:
Para checar todos os tetos por categoria recomendamos darem uma olhada em nossa documentação no final deste artigo!
Regras de Negócio e Validações
- Teto Máximo: Não é permitido ajustar o limite de uma conta para um valor superior ao maxAmount (limite máximo) Caso necessite aumentar o limite máximo de uma conta, é necessário realizar a abertura de um chamado para realizarmos a majoração do limite, para mais detalhes recomendamos nosso artigo: https://ipflagship.freshdesk.com/a/solutions/articles/67000744574
| ⚠️ Observações Importantes Pelo menos um campo interno de cada objeto (limits, transactionFavoredLimit, cashInLimits, etc.) deve ser fornecido na requisição para que o ajuste seja processado; |
2. Consulta de limites
API para consulta:
Endpoint GET {{url}}/v2/accounts/{{branch}}/{{account}}/limits/
Este endpoint retorna a estrutura completa de limites da conta, incluindo os limites globais por período (diurno/noturno/intermediário), limites de produtos (Pix, TED, etc.) e as configurações de horário noturno.
Também é possível realizar a consulta de limites de todas as contas sobre uma agência com o seguinte endpoint:
Endpoint GET {{url}}/v2/accounts/{{branch}}/limits?nextToken=&pageSize
Este endpoint irá retornar o limite de todas as contas sob a agência.
Ao realizar a consulta, você irá notar que na response é retornado 3 campos, o campo amount, maxAmount e lastupdate.
- amount: Limite atual do cliente baseando-se no teto;
- maxAmount: Teto permitido;
- lastUpdate: Informa quando foi a ultima alteração do limite do cliente.
Limites por período
A nova versão traz o horário intermediário, que opera das 07:30 às 17:00. Ele funciona como uma regra prioritária: enquanto estiver ativo, vale o limite definido para ele, e não o limite diurno comum.
Importante notar: se o limite intermediário for atingido (zerar), a conta só poderá realizar novas transações após as 17:00, utilizando o restante do limite global/diurno disponível.
⚠️ Observações Importantes
|
3. Gerenciamento de Favorecidos
O que é uma conta favorecida?
Esta funcionalidade permite que contas de confiança sejam cadastradas para usufruir de regras de limites mais flexíveis, reduzindo contratempos em transações recorrentes de alto valor, mantendo a segurança transacional.
Inclusão de Favorecido
API para inclusão de favorecidos:
Endpoint POST {{url}}/v1/accounts/{{branch}}/{{account}}/favored
Este endpoint vincula uma conta como favorecida, informando sua agência e conta no endpoint.
É possível adicionar um favorecido de duas maneiras diferentes, a primeira é utilizando sua chave PIX:
Exemplo de payload:
{
"nickname": "Joao",
"data": {
"alias": "test2@test.com",
"aliasType": "EMAIL",
"accountType": "PAGAMENTO"
},
"type": "alias"
}
A segunda maneira seria utilizando sua agência e conta:
{
"nickname": "Joao",
"data": {
"branch": "{{branch}}",
"account": "{{account}}",
"accountType": "PAGAMENTO"
},
"type": "bankAccount"
}
Importante citar que o payload muda de acordo com o campo "type". Caso seja enviado com o valor de "alias", o primeiro exemplo será utilizado, agora, caso seja enviado como "bankAccount" o segundo exemplo deverá ser utilizado.
Fluxo de Inclusão e Ativação (Carência)
Para garantir a conformidade e prevenir fraudes em novas associações de contas, a inclusão de favorecidos segue etapas de segurança obrigatórias:
- Período de Carência: Todo novo favorecido incluído via API entra em um estado de espera de 24 horas antes que as isenções de limites passem a valer;
- Comportamento em Carência: Durante as primeiras 24 horas, enquanto o status não é "Ativo", a conta de destino permanece submetida às regras de limites de contas comuns (não favorecidas).
Consulta e remoção de favorecidos
Para consultar as informações de um favorecido basta enviar um GET para o endpoint em questão:
Endpoint GET {{url}}/v1/accounts/{{branch}}/{{account}}/favored/{{favoredId}}
Para remover o privilégio de limite de um favorecido basta enviar um delete para o endpoint em questão:
Endpoint DELETE {{url}}/v1/accounts/{{branch}}/{{account}}/favored/{{favoredId}}
Características das regras
Limite Global
- Sempre validado
Regra por Período (Diurno/Noturno)
- Pula validação se é um favorecido
- Válida diurno ou noturno dependendo do horário
Regra Intermediário
- Válido por intervalo de tempo (07:30 até 17:00)
- Pula validação se é um favorecido
Regra Teto para Produtos
- Um limite para cada tipo de produto
- Pula validação se é um favorecido
Regra Teto para Favorecido
- Pula validação se nao for favorecido
- Um limite para cada tipo cliente(PF,PJ,mesma titularidade) e se é diurno/noturno
⚠️ Observações Importantes
|
Caso tenham mais alguma dúvida recomendamos checarem nossa documentação abaixo onde vocês poderão ver os campos com mais detalhes.
Em anexo vocês também podem ter acesso a nossa collection.
Suporte
Para dúvidas ou acompanhamento de chamados, acesse: Portal de Suporte