Ir para o conteúdo

4.20. Listar opt-ins

🔗 Endpoint

Método URL
GET /public/api/v1.1/cartao/optins

🧾 Descrição

Lista, de forma paginada, os opt-ins de um estabelecimento comercial (EC) no seu grupo econômico, com a situação de cada um.

A lista traz todos os opt-ins do EC, de qualquer origem: os pedidos por 4.19. Solicitar opt-in, os feitos pela solicitação de agenda (4.1. Solicitar agenda) e os feitos pela plataforma. Isso porque o opt-in é do estabelecimento: um opt-in pedido por uma rota é reaproveitado pelas outras.

É a fonte de verdade do resultado do 4.19: o opt-in está registrado na registradora quando situacao = 2 (Ativo).


📤 Requisição

🔍 Filtros (query string)

Parâmetro Tipo Obrigatório Descrição
cnpj string Sim CNPJ do estabelecimento comercial, com ou sem pontuação (ex.: 12.345.678/0001-95 ou 12345678000195).
idOperacao integer Não Traz só os opt-ins usados por pesquisas desta operação. Deve ser maior que zero.
situacao integer Não Filtra pela situação do opt-in, de 1 a 5 (ver situacao, abaixo).

📄 Paginação

Parâmetro Tipo Obrigatório Padrão Descrição
indicePagina integer Não 1 Página desejada do resultado.
tamanhoDaPagina integer Não 20 Quantidade de registros por página.

A ordem é fixa: do opt-in mais recente para o mais antigo. Esta rota não aceita ordem nem direcaoOrdem: qualquer valor neles responde 400.

Regras e formatos

  • cnpj: com ou sem pontuação; nas respostas, os CNPJs vêm sempre sem pontuação.
  • Os filtros são combinados com E. Filtros inválidos voltam todos juntos no mesmo 400.
  • EC sem nenhum opt-in no grupo econômico não é erro: a resposta é 200 com registros vazio.

🧪 Exemplo de cURL

curl -X GET "https://api.veflow.com/public/api/v1.1/cartao/optins?cnpj=12.345.678%2F0001-95&idOperacao=1&indicePagina=1&tamanhoDaPagina=20" \
  -H "Authorization: Bearer {seu_token}" \
  -H "GrupoEconomico: {seu_grupo_economico}" \
  -H "Content-Type: application/json"

📥 Responses

✅ 200 OK

EC com um opt-in ativo para uma credenciadora e um arranjo, um opt-in ainda pendente na registradora e um opt-in FULL antigo, já cancelado:

{
  "registros": [
    {
      "id": "48210937561029384756102938475610",
      "idOperacao": 1,
      "credenciadora": {
        "cnpj": "10293847560102",
        "nome": "CREDENCIADORA EXEMPLO S.A."
      },
      "arranjo": {
        "sigla": "VCC",
        "nome": "Visa Cartão de Crédito"
      },
      "situacao": 1,
      "protocolo": null,
      "dataExpiracao": null,
      "dataOptout": null,
      "mensagemErro": null
    },
    {
      "id": "91827364501928374650192837465019",
      "idOperacao": 1,
      "credenciadora": {
        "cnpj": "10293847560102",
        "nome": "CREDENCIADORA EXEMPLO S.A."
      },
      "arranjo": {
        "sigla": "MCC",
        "nome": "Mastercard Cartão de Crédito"
      },
      "situacao": 2,
      "protocolo": "202508110000123456",
      "dataExpiracao": "2026-08-11T13:05:27Z",
      "dataOptout": null,
      "mensagemErro": null
    },
    {
      "id": "56473829105647382910564738291056",
      "idOperacao": 1,
      "credenciadora": null,
      "arranjo": null,
      "situacao": 5,
      "protocolo": "202502030000654321",
      "dataExpiracao": "2026-02-03T12:40:02Z",
      "dataOptout": "2025-07-30T17:22:45Z",
      "mensagemErro": null
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 3,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}

🧾 Detalhamento dos Campos

🔹 registros

Campo Tipo Descrição
id string Identificador do opt-in: texto opaco, o código enviado à registradora. Use-o em 4.21. Cancelar opt-in.
idOperacao integer Operação das pesquisas que usam o opt-in (a menor, quando ele é usado por mais de uma operação do EC). Com o filtro idOperacao, considera só as pesquisas dela.
credenciadora object/null Credenciadora do opt-in. Vem null quando o opt-in vale para todas as credenciadoras.
credenciadora.cnpj string CNPJ da credenciadora, sem pontuação.
credenciadora.nome string Nome da credenciadora.
arranjo object/null Arranjo de pagamento do opt-in. Vem null quando o opt-in vale para todos os arranjos. Com credenciadora e arranjo nulos, o opt-in é FULL.
arranjo.sigla string Sigla do arranjo (ex.: MCC).
arranjo.nome string Nome do arranjo, como cadastrado na plataforma.
situacao integer Situação do opt-in, de 1 a 5. Ver situacao, abaixo.
protocolo string/null Protocolo do opt-in na registradora. Vem null enquanto a registradora não o registrou. Em registradora de demonstração, começa por DEMO-.
dataExpiracao string/null Validade do opt-in, em UTC (ISO 8601 com Z). Vem null enquanto o pedido não foi registrado.
dataOptout string/null Instante do cancelamento (opt-out), em UTC (ISO 8601 com Z). Vem null enquanto o opt-in não foi cancelado.
mensagemErro string/null Motivo da falha informado pela registradora ou pela plataforma, quando houver. Texto informativo: não o use em lógica.

🔢 situacao

Os mesmos códigos de 8.1. Enumerações. A situação é calculada na consulta, nesta ordem: o primeiro critério que o opt-in atende define o código.

Código Significado Quando
3 Falhou A registradora recusou o opt-in, ou as retentativas de comunicação se esgotaram. O motivo vem em mensagemErro.
5 Cancelado O opt-out foi realizado (dataOptout preenchida).
4 Expirado A dataExpiracao já passou.
2 Ativo Registrado na registradora, com protocolo, e dentro da validade. É o estado a aguardar, depois de 4.19, antes de solicitar a agenda em 4.1.
1 Pendente Pedido em curso: ainda sem resposta da registradora.

Um opt-in que falhou continua com situacao = 3 mesmo depois de cancelado em 4.21: a falha prevalece, e o cancelamento aparece em dataOptout.

🔹 paginacao

Campo Tipo Descrição
paginaAtual integer Página atual do retorno.
paginaTotal integer Total de páginas disponíveis.
paginaQuantidadeRegistro integer Quantidade máxima de registros por página.
quantidadeRegistros integer Total de registros encontrados.
temPaginaAnterior boolean Indica se há página anterior.
temProximaPagina boolean Indica se há próxima página.

🔹 mensagem

Campo Tipo Descrição
mensagem string/null Mensagem informativa opcional. Nesta rota vem sempre null.

❌ 400 Bad Request

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "cnpj": [
      "O CNPJ do estabelecimento comercial é obrigatório."
    ],
    "situacao": [
      "Campo 'situacao' inválido. Valores aceitos: 1 a 5."
    ]
  },
  "traceId": "00-1f7a3c9e5b2d4806a1c3e5f7092b4d68-7c1e4a9b2d5f8036-00"
}

Requisição que gerou o exemplo:

GET /public/api/v1.1/cartao/optins?situacao=9

O erro segue o formato ProblemDetails de 1.2. Convenções da API: uma chave por parâmetro inválido, em camelCase, com a lista de mensagens. O title pode variar e a ordem das chaves em errors não é fixa; não use nenhum dos dois em lógica.

Outras mensagens:

Parâmetro Mensagem
idOperacao O ID da operação deve ser maior que zero.
ordem Campo 'ordem' não é aceito: os opt-ins saem do mais recente para o mais antigo.
direcaoOrdem Campo 'direcaoOrdem' não é aceito: os opt-ins saem do mais recente para o mais antigo.

CNPJ inválido em cnpj também responde 400, na chave cnpj.


🕒 Observações

  • Opt-in de outro grupo econômico nunca aparece, mesmo para o mesmo CNPJ.
  • Ao acompanhar um pedido feito em 4.19, filtre pelo cnpj e pela idOperacao do pedido e localize cada combinação pela credenciadora e pelo arranjo. Uma combinação que já tinha opt-in vigente aparece com o opt-in existente, não com um novo.
  • Datas em UTC: converta para o horário de Brasília quando for exibir.
  • Para cancelar um opt-in, use o id em 4.21. Cancelar opt-in.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.