4.20. Listar opt-ins¶
🔗 Endpoint¶
| Método | URL |
|---|---|
/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 é
200comregistrosvazio.
🧪 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=3mesmo depois de cancelado em 4.21: a falha prevalece, e o cancelamento aparece emdataOptout.
🔹 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
cnpje pelaidOperacaodo pedido e localize cada combinação pelacredenciadorae peloarranjo. 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
idem 4.21. Cancelar opt-in. - Headers obrigatórios e convenções gerais: 1.2. Convenções da API.