Agora no Bluesoft ERP, é possível consumir as operações públicas de convênio nas rotas principais da API de clientes, permitindo que o integrador opere tanto por CPF/CNPJ quanto por número do cartão de convênio usando os mesmos endpoints unificados. O objetivo desta melhoria é otimizar e simplificar o trabalho técnico do integrador das APIs do ERP. Dessa forma, não é mais necessário conhecer, implementar e manter dois fluxos distintos de chamadas para operações que, do ponto de vista do negócio, representam a exata mesma jornada (como consultar limites, validar senha, realizar e cancelar empenhos).

Como Era o Processo Antes?

Antes, o processo de integração exigia a manutenção de rotas diferentes para operações equivalentes, dependendo exclusivamente da forma de identificação do conveniado (por CPF/CNPJ ou pelo número do cartão). O fluxo por cartão utilizava o número no próprio caminho da URL, enquanto o fluxo por CPF/CNPJ utilizava parâmetros no corpo da requisição ou na URL. Isso fazia com que o integrador precisasse programar e manter dois caminhos distintos em sua aplicação, o que demandava maior esforço de desenvolvimento.

Agora, unificamos o consumo das operações de convênio diretamente nas rotas principais /api/clientes, introduzindo um novo campo opcional e condicional chamado numeroCartao.

Essa mudança agilizará todo o processo de desenvolvimento e manutenção das integrações, centralizando o fluxo lógico e permitindo o reaproveitamento das regras de negócio em um único endpoint. Isso garante um código mais limpo, estruturado e organizado para as aplicações parceiras.

Como Irá Funcionar a Partir de Agora?

O sistema passará a avaliar a presença do campo numeroCartao na requisição para decidir qual fluxo executar internamente. Caso seja enviado, o ERP validará o cartão; caso não, manterá a validação padrão por CPF/CNPJ.

  • Consulta de Limite de Convênio (GET /api/clientes/limite-convenio): A rota passa a aceitar os parâmetros de query cpfCnpj e/ou numeroCartao. Ao informar o número do cartão, o sistema validará se ele existe e está ativo, identificando o CPF/CNPJ vinculado de forma automática para consultar e retornar os saldos e limites disponíveis.
  • Validar Senha (POST /api/clientes/validar-senha): O corpo da requisição ganha o campo opcional numeroCartao. Quando informado, aciona a validação do cartão. O campo cpfCnpj continua sendo obrigatório nesta rota para confirmar e validar o vínculo correto entre o cartão e o conveniado.
  • Realizar Empenho (POST /api/clientes/empenho-convenio): A requisição passa a aceitar o campo opcional numeroCartao no corpo da requisição. O sistema validará se o cartão está ativo e pertence ao conveniado informado antes de efetivar o mesmo processamento atual de empenho e redução do saldo/limite líquido. O campo cpfCnpj continua sendo obrigatório.
  • Cancelar Empenho (POST /api/clientes/cancelar-empenho-convenio): Semelhante à operação de empenho, o cancelamento agora aceita o numeroCartao opcionalmente (mantendo a obrigatoriedade do cpfCnpj), executando as validações do cartão antes de liberar o valor que estava previamente reservado no limite do conveniado.

Observações / Validações

  • Compatibilidade dos Endpoints Legados: Os endpoints legados específicos por cartão (ex: GET /api/clientes/limite-convenio/{numeroCartao}/limite) continuarão disponíveis e com o mesmo comportamento atual, sem qualquer alteração de contrato. Integrações já existentes não sofrerão nenhum impacto.
  • Permissões de Acesso Centralizadas: Para consumir a rota principal informando o número do cartão, o sistema exigirá as mesmas permissões da rota padrão por CPF/CNPJ (‘3183’, ‘3184’, ‘3185’ e ‘3186’). As permissões da série ‘4393’ a ‘4396’ continuarão válidas somente para as rotas legadas.
  • Manutenção de Regras de Negócio: Esta unificação não cria e não altera as regras de negócio do convênio. Todos os cálculos de limite, validações de saldo, regras de tolerância, geração de checksum ou rotatividade de saldo continuam inalterados, preservando as mensagens de erro já conhecidas.
  • Segurança de Vínculo: Se o cpfCnpj e o numeroCartao forem enviados na mesma requisição, o sistema garantirá a segurança da operação rejeitando-a imediatamente caso o cartão informado pertença a um CPF/CNPJ diferente.

Para conhecer mais sobre como é a utilização dessa ferramenta, clique aqui.

Para saber mais sobre a utilização das APIs do ERP, clique aqui.

Disponível a partir da versão r372.01