O Bluesoft ERP permite cadastrar, consultar e atualizar mais de um convênio para a mesma pessoa responsável por meio da API V2. Cada convênio possui identificação própria e mantém suas configurações e vínculos de participantes de forma independente.

Objetivo

A melhoria atende empresas que mantêm negociações distintas de convênio com a mesma pessoa responsável. Com cadastros separados, é possível identificar cada negociação e gerenciar seus limites, saldos, participantes e configurações de cobrança sem confundir os dados de um convênio com os de outro.

O Que Mudou?

Como Era o Processo Antes?

A integração de convênios estava preparada principalmente para trabalhar com um cadastro de convênio por pessoa responsável. A API V2 já permitia incluir, consultar e realizar manutenções nos convênios e participantes, porém a identificação individual de diferentes convênios da mesma pessoa ainda não estava disponível em todo o fluxo cadastral. Os contratos não recebiam nem retornavam uma descrição própria do convênio, e a listagem não permitia filtrar pelo CPF/CNPJ do responsável.

Com a evolução do cadastro de múltiplos convênios no Bluesoft ERP, tornou-se necessário ampliar também a integração para que cada convênio pudesse ser tratado individualmente.

Como Irá Funcionar a Partir de Agora?

Inclusão

Para incluir um novo convênio, poderá utilizar o caminho abaixo:

  • POST /api/v2/convenios

Integração permitirá informar o campo descricao para identificar o convênio. Com a funcionalidade de múltiplos cadastros ativa, a descrição aceita até 100 caracteres. Se for omitida ou deixada em branco, o ERP utiliza o nome abreviado da pessoa responsável.

Quando a pessoa já possui um convênio, uma inclusão autorizada cria outro registro, com uma convenioKey própria, preservando o convênio anterior. O codigoDeIntegracao não é gerado automaticamente: quando o convênio para venda está habilitado, deve ser informado um codigoDeIntegracao válido e não utilizado por outro convênio.

O POST é assíncrono. A resposta contém um requestId, que permite acompanhar a conclusão ou a rejeição do processamento.

Exemplo de inclusão:
  • POST /api/v2/convenios
{
  "cpfCnpj": "78831730000121",
  "descricao": "Convênio Funcionários",
  "tipoConvenio": "POS_PAGO",
  "limiteCredito": 5000.00
}

Nesse exemplo, o convênio será identificado pela descrição “Convênio Funcionários”, permitindo diferenciá-lo dos demais convênios cadastrados para a mesma pessoa responsável.

Consulta

Para consultar os convênios de uma pessoa, poderá filtrar pelo cpfCnpj do responsável:

  • GET /api/v2/convenios

Quando houver mais de um convênio para a pessoa informada, cada cadastro será retornado individualmente, mantendo sua própria identificação, descrição, configurações e vínculos.

Esse filtro pode ser combinado com os filtros disponíveis para convenioKey, participanteKey, situação e data da última alteração.

Para consultar um convênio específico:

  • GET /api/v2/convenios/{convenioKey}

A resposta apresenta os dados do convênio selecionado, incluindo sua descrição e seus participantes. O nome da pessoa responsável e a descrição do convênio são informações distintas.

Atualização

Para atualizar um convênio específico, deverá ser informada a chave do convênio no caminho da operação:

  • PUT /api/v2/convenios/{convenioKey}

Dessa forma, será atualizado apenas o convênio identificado pela chave informada na rota, sem trocar a pessoa responsável ou modificar os outros convênios dela. Com a funcionalidade de múltiplos cadastros ativa, uma descrição omitida ou em branco na atualização é preenchida com o nome abreviado do responsável.

Para alterar limite ou status de um vínculo de participante já existente no convênio, utilize:

  • PUT /api/v2/convenios/{convenioKey}/editar/{participanteKey}

O mesmo cliente pode participar de convênios diferentes da mesma pessoa responsável, com um vínculo e valores próprios em cada um.

Os métodos PUTs da API V2 são síncronos: diferentemente do POST de inclusão, não retornam requestId.

Condições de uso e permissões

O suporte a múltiplos convênios depende da configuração HABILITAR_MULTI_CADASTRO_CONVENIO_POR_PESSOA ativa. Para utilizar a API V2 de convênios, também é necessário que o parâmetro Controle de convênio por participante esteja habilitado no ERP.

As permissões envolvidas são:

  • 603 — Consultar convênios: acesso às consultas.
  • 604 — Incluir convênios: acesso ao POST e aos PUTs da API V2.
  • 4707 — Incluir mais de um convênio por pessoa: exigida para criar um convênio adicional para alguém que já possui um cadastro.
  • 4047 — Consultar processamento assíncrono: necessária para acompanhar o resultado pelo requestId.

Uma solicitação de inclusão adicional pode receber um requestId e ser rejeitada durante o processamento assíncrono caso as condições para o novo cadastro não sejam atendidas.

Regras de descrição

Com a funcionalidade de múltiplos cadastros ativa, descrições com mais de 100 caracteres são rejeitadas. No POST, acompanhe o motivo da rejeição pelo processamento assíncrono. No PUT, a validação ocorre na própria requisição, pois a atualização é síncrona.

Na consulta, a API V2 retorna a descrição armazenada no convênio. Caso um registro legado não possua descrição cadastrada, a resposta não preenche esse campo automaticamente com o nome abreviado.

Compatibilidade com a API V1

As operações de inclusão e alteração da API V1 — POST /api/convenios e PUT /api/convenios/{cpfCnpj} — estão marcadas como depreciadas. A API V1 permanece disponível para integrações existentes, mas a API V2 deve ser utilizada para novos fluxos de múltiplos convênios.

Quando a configuração de múltiplos convênios estiver desabilitada, uma inclusão adicional será recusada e o convênio existente será preservado.

Para conhecer as funcionalidades relacionadas, consulte as documentações:

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

Disponível a partir da versão r374.03