Agora no Bluesoft ERP, é possível consultar o histórico completo de cartões vinculados a um participante ou pessoa conveniada via API

O objetivo desta melhoria é permitir que o integrador consulte e audite a base completa de cartões (ativos, inativos, bloqueados, cancelados, etc.), garantindo visibilidade dos cartões históricos cadastrados no ERP após o faturamento de importações da API.

Como Irá Funcionar a Partir de Agora?

A partir de agora, o endpoint GET /api/v2/convenios/cartao passa a aceitar um parâmetro opcional chamado retornarTodos (booleano). Quando enviado com o valor true, a API retornará todos os cartões cadastrados e vinculados ao participante ou à pessoa. Além disso, a resposta passa a ser estruturada com paginação padrão.

  • Parâmetro de Consulta
    • retornarTodos:retornarTodos=false (ou não informado): Mantém o comportamento padrão, retornando apenas o cartão atual/vigente em formato paginado.
    • retornarTodos=true: Retorna a lista completa com todos os cartões históricos vinculados ao parâmetro informado (participanteKey ou pessoaKey).
  • Parâmetros de Paginação (Opcionais):
    • currentPage: Número da página desejada (Valor Padrão: 0).
    • pageSize: Quantidade de registros por página (Valor Padrão: 30).
  • Exemplo de Requisição:
    • GET /api/v2/convenios/cartao?pessoaKey=253221&retornarTodos=true&currentPage=0&pageSize=30
  • Estrutura de Retorno Paginado:
{
  "currentPage": 0,
  "pageSize": 30,
  "data": [
    {
      "numeroCartao": "0000000000000009",
      "statusCartao": "ATIVO",
      "participanteKey": 1601,
      "convenioKey": 253221,
      "dataAlteracao": "08/07/2026 10:13:03"
    },
    {
      "numeroCartao": "0000000000000004",
      "statusCartao": "INATIVO",
      "participanteKey": 1601,
      "convenioKey": 253221,
      "dataAlteracao": "08/07/2026 10:13:03"
    }
  ]
}

Observações Importantes!

Regras de Identificador Mantidas: Permanece a obrigatoriedade de informar `participanteKey` ou `pessoaKey`. Enviar a requisição sem ambos ou enviando os dois simultaneamente continuará retornando erro de validação (HTTP status 400).

Permissão de Acesso: O acesso ao endpoint continua condicionado ao controle da permissão `4446 – API Convênios Cartão Consultar`.

Preservação de Dados Operacionais: A consulta é puramente de leitura e não altera status, limites, saldos ou qualquer informação operacional do cartão no ERP.

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 r370.59