--- title: 4.20. Listar opt-ins url: https://docs.vehub.com.br/API/VeFlow%20-%20Cart%C3%A3o%20de%20cr%C3%A9dito/4.%20Agenda%20de%20receb%C3%ADveis/v1.1/4.20.%20Listar%20opt-ins/ --- # 4.20. Listar opt-ins ## 🔗 Endpoint | Método | URL | | ---------------------------------------------------- | -------------------------------- | | ![GET](https://img.shields.io/badge/GET-brightgreen) | `/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](4.19.%20Solicitar%20opt-in.md), os feitos pela solicitação de agenda ([4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md)) 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](4.19.%20Solicitar%20opt-in.md): 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 ```bash 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: ```json { "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](4.21.%20Cancelar%20opt-in.md). | | 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](../../8.%20Enumerações/8.1.%20Enumerações.md#situacao-do-opt-in-situacao). 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](4.19.%20Solicitar%20opt-in.md), antes de solicitar a agenda em [4.1](4.1.%20Solicitar%20agenda.md). | | 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](4.21.%20Cancelar%20opt-in.md): 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 ```json { "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: ```text GET /public/api/v1.1/cartao/optins?situacao=9 ``` O erro segue o formato `ProblemDetails` de [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md): 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](4.19.%20Solicitar%20opt-in.md), 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](4.21.%20Cancelar%20opt-in.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).