Agora no Bluesoft ERP, é possível consultar o estado real de todas as principais configurações de convênio diretamente nos endpoints de listagem e de detalhe da API v2 de Convênios (GET /api/v2/convenios). O objetivo desta melhoria é viabilizar que integrações externas consultem a parametrização completa e atualizada de cada convênio gravada no sistema antes de realizar qualquer operação de atualização via endpoint de persistência (PUT /api/v2/convenios/{convenioKey}). Isso evita que dados customizados manualmente no Bluesoft ERP sejam sobrescritos acidentalmente por valores desatualizados provenientes do sistema parceiro.

Como Era o Processo Antes?

Antes, o ciclo de sincronização entre as ferramentas parceiras e o Bluesoft ERP não retornava todas as chaves de configuração que o endpoint de atualização (PUT /api/v2/convenios/{convenioKey}) aceitava receber.

Com isso, a integração parceira realizava chamadas de consulta e recebia apenas um conjunto resumido de dados (como chave, titular, limite e status). Sem conhecer o estado real de configurações logísticas, regras de parcelamento ou parâmetros de faturamento definidos diretamente no ERP por usuários humanos, o sistema externo, ao enviar um payload para atualizar o convênio, corria o risco de reenviar valores fixos ou desatualizados nas propriedades omitidas, apagando as customizações desejadas na base de dados.

Como Irá Funcionar a Partir de Agora?

Agora, os responses das APIs de Consulta e de Detalhe foram completamente equalizados. Todos os campos públicos de configuração suportados no endpoint de persistência passam a constar no contrato de retorno do GET, trazendo os dados reais gravados na base de dados em tempo real. Essa evolução traz total transparência para as integrações que utilizam o controle de empenho via API, consolidando transações mais robustas e eliminando a necessidade de manutenções manuais corretivas por divergência de regras entre os sistemas integrados.

Ao realizar requisições de listagem paginada (GET /api/v2/convenios) ou de busca individual por chave (GET /api/v2/convenios/{convenioKey}), o contrato do response trará os seguintes campos adicionais mapeados:

  • habilitarConvenioCompra (Boolean): Indica se o convênio está habilitado para compras.
  • habilitarConvenioVenda (Boolean): Indica se o convênio está habilitado para vendas.
  • vendaViaTerceiros (Boolean): Indica se é permitida a realização de vendas via terceiros.
  • geracaoAutomaticaDuplicata (Boolean): Indica se a duplicata é gerada automaticamente no faturamento.
  • referenciaEmissao (String/Enum: MES_ATUAL, MES_ANTERIOR): Referência de período utilizada para a emissão da duplicata.
  • rotatividadeSaldo (String/Enum: MENSAL, ACUMULATIVO): Regra de rotatividade do saldo do convênio.
  • tipoFormaPagamentoKey (Integer): Chave de identificação da forma de pagamento padrão para as duplicatas automáticas.
  • diaVencimentoDuplicata (Integer): Dia de vencimento das duplicatas geradas.
  • diaViradaGeracaoDuplicata (Integer): Dia do mês em que a geração de duplicatas é disparada automaticamente.
  • diaCorteApuracao (Integer): Dia limite de fechamento de faturamento para apuração.
  • mesSubsequente (Boolean): Indica se o faturamento do convênio é projetado para o mês seguinte.
  • emitirDuplicataNomeParticipante (Boolean): Indica se o sistema gerará duplicatas individuais segmentadas por participante.
  • diaBase (Integer): Dia base estipulado para a apuração do convênio.
  • diaViradaMes (Integer): Dia programado para a virada de saldo do convênio.
  • convenioParcelado (Boolean): Indica se o convênio permite operações de parcelamento de faturamento.
  • numeroParcelas (Integer): Quantidade máxima de parcelas acordada para o convênio.
  • saldoConvenio (Decimal): Saldo financeiro atualizado disponível para o convênio.
  • dataUltimaAlteracao (LocalDateTime): Registro exato de data e hora da última modificação efetuada nos dados do convênio, retornado estritamente no padrão brasileiro de 24 horas: dd/MM/yyyy HH:mm:ss.

Exemplo de consulta com os novos campos:

Exemplo de obter um convênio com os novos campos:

Observações / Validações

  • null no Retorno de Campos Opcionais: Para garantir a integridade contratual da API, caso algum campo opcional (como tipoFormaPagamentoKey ou diaCorteApuracao) não possua configuração preenchida no ERP, o ERP retornará a propriedade preenchida com o valor JSON null. O sistema não omitirá o campo da estrutura JSON e não converterá dados ausentes de forma incorreta para false, 0 ou textos vazios, assegurando uma leitura limpa.
  • Controle de Performance (Omissão de Participantes na Listagem): Para preservar o desempenho de buscas com grande volume de dados, o campo participantesDoConvenio (que contém o array detalhado de todos os conveniados vinculados) não será serializado no endpoint de listagem paginada (GET /api/v2/convenios). Ele permanece retornando exclusivamente no endpoint detalhado por chave (GET /api/v2/convenios/{convenioKey}).
  • Segurança de Dados Confidenciais: O contrato de resposta de ambos os GETs não expõe campos sensíveis de segurança ou de controle interno, tais como senhas ou dados estruturais de cartões (senha e numeroCartao), garantindo a conformidade com as diretrizes de proteção de dados.
  • Parâmetro de Ativação: O uso dos endpoints v2 de convênio continua condicionado ao parâmetro do sistema “Utilizar controle de empenho via API” estar habilitado no ERP. Caso contrário, requisições às APIs retornarão status HTTP 400 com a mensagem de instrução de ativação.
  • Permissões Necessárias: O consumo das APIs é protegido por controle de permissão por token. Para consultar a listagem ou detalhe de convênios, a integração deve autenticar-se utilizando um token que possua a permissão 603 – Convênios Consultar. Atualizações via PUT exigem a permissão 604 – Incluir Convênio.

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 r371.34