Agora no Bluesoft ERP, é possível incluir, consultar informações e manutenção de convênios via API
Para ampliar a autonomia nas integrações do Bluesoft ERP, lançamos a versão 2 da API de Convênios. Esta atualização resolve a limitação anterior que impedia a manipulação via integração de convênios configurados com “Controle por Participante”.
Agora, é possível realizar a inclusão, consulta e gestão granular de limites e status dos participantes através de novos endpoints.
O que muda na v2?
A nova rota /api/v2/convenios foi desenhada para suportar estruturas complexas de convênio, introduzindo:
• Processamento Assíncrono: A criação de convênios (POST) agora retorna um requestId para monitoramento, garantindo performance no processamento de grandes listas de participantes.
• Gestão Individualizada: Novos métodos para editar o limite de crédito ou inativar um participante específico sem afetar o restante do convênio.
• Identificação Única: A consulta (GET) passa a retornar o participanteKey, chave indispensável para realizar alterações pontuais em um conveniado.
Regras de Negócio e Validações
Para garantir a integridade dos dados, a API aplica as seguintes regras:
1. Hierarquia de Limites:
◦ Limite Compartilhado (Sim): O sistema ignora os limites individuais e valida o consumo apenas contra o Teto Global do convênio.
◦ Limite Compartilhado (Não): A soma dos limites de crédito de todos os participantes não pode exceder o Limite de Crédito Global do convênio.
2. Código de Integração: Este campo deve ser único no sistema. Atenção: Ele torna-se obrigatório apenas quando a flag habilitarConvenioVenda for enviada como true.
3. Manutenção de Participantes:
◦ Não é permitida a exclusão física de um participante via API, apenas a alteração do status para INATIVO.
◦ O CPF/CNPJ do participante deve estar previamente cadastrado como cliente no ERP.
Resumo dos Endpoints
• POST /api/v2/convenios: Criação de convênio com lista de participantes (Async).
Exemplo de JSON:
{
"convenio": {
"cpfCnpj": "10327704306",
"status": "ATIVO",
"tipoConvenio": "POS_PAGO",
"codigoDeIntegracao": "003",
"limiteCredito": 5000,
"limiteTotalCompartilhado": false,
"habilitarConvenioCompra": false,
"habilitarConvenioVenda": true,
"vendaViaTerceiros": false,
"diaBase": 2,
"valorTolerancia": 150,
"geracaoAutomaticaDuplicata": false,
"periodicidadeDuplicata": "MENSAL",
"diaViradaMes": 3,
"referenciaEmissao": "MES_ATUAL",
"rotatividadeSaldo": "MENSAL",
"convenioParcelado": false,
"numeroParcelas": 2,
"tipoFormaPagamentoKey": 3,
"diaVencimentoDuplicata": 10,
"diaViradaGeracaoDuplicata": 1,
"diaCorteApuracao": 1,
"participantesDoConvenio": [
{
"cpfCnpj": "53804570887",
"limiteCredito": 1000,
"status": "ATIVO"
}
]
}
}• GET /api/v2/convenios/{convenioKey}: Retorna dados completos, incluindo o participanteKey.
• PUT /api/v2/convenios/{convenioKey}: Atualiza dados globais (ex: Teto Global) ou adiciona novos participantes à lista existente.
Exemplo de JSON:
{
"limiteCredito": 12000,
"status": "ATIVO",
"limiteTotalCompartilhado": false,
"codigoDeIntegracao": "CONV-V2-001",
"participantesDoConvenio": [
{
"cpfCnpj": "67565208736",
"limiteCredito": 600,
"status": "ATIVO"
}
]
}• PUT /api/v2/convenios/{convenioKey}/editar/{participanteKey}: Atualiza exclusivamente o limite e o status de um participante específico.
Exemplo de JSON:
{
"limiteCredito": 20,
"status": "INATIVO"
}Esta melhoria visa facilitar a gestão de grandes redes de convênios que necessitam de controle rigoroso sobre os limites individuais via integração.
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.