--- title: 4.19. Solicitar opt-in 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.19.%20Solicitar%20opt-in/ --- # 4.19. Solicitar opt-in ## 🔗 Endpoint | Método | URL | | ----------------------------------------------- | -------------------------------- | | ![POST](https://img.shields.io/badge/POST-blue) | `/public/api/v1.1/cartao/optins` | --- ## 🧾 Descrição Solicita o **OPT-IN do estabelecimento comercial (EC)** na registradora, **sem consultar a agenda de recebíveis**. Use esta rota para deixar o opt-in do EC pronto antes de precisar da agenda: quando a agenda for solicitada em [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md) para o **mesmo EC e a mesma operação**, a plataforma **reaproveita** o opt-in já ativo, em vez de pedir outro à registradora. O processamento é **assíncrono**: a resposta confirma o recebimento e devolve o `identificadorProcessamento`. O resultado do opt-in é consultado em [4.20. Listar opt-ins](4.20.%20Listar%20opt-ins.md) — ali, `situacao` = `2` (Ativo) indica o opt-in registrado na registradora. !!! warning "A fonte de verdade é a 4.20" O `202` só confirma que o pedido foi recebido. Para saber se o opt-in foi registrado, consulte [4.20. Listar opt-ins](4.20.%20Listar%20opt-ins.md) e aguarde `situacao` = `2`. **Antes de solicitar a agenda (4.1), espere a `situacao` = `2`**: enquanto o pedido feito por esta rota está pendente na registradora, ele não é reaproveitado, e a 4.1 chamada nesse intervalo pede um opt-in próprio à registradora. O opt-in pode ser solicitado para operação de **garantia** e de **antecipação**. Somente operações cuja registradora é a **B3** (ou uma registradora de **demonstração**) fazem opt-in de cartões por esta rota; nas demais, a resposta é `200` com `aceito: false`. --- ## 📤 Requisição ### 📋 Payload (JSON) ```json { "idOperacao": 0, "cnpj": "", "credenciadoras": [""], "arranjos": [""] } ``` ### 🧾 Detalhamento dos Campos | Campo | Tipo | Obrigatório | Descrição | | -------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | idOperacao | number | Sim | ID da operação atrelada (valor definido pelo time de implantação). Deve ser maior que zero. | | cnpj | string | Sim | CNPJ do estabelecimento comercial, com ou sem pontuação. Nas respostas ele volta sempre sem pontuação. | | credenciadoras | string[] | Não | CNPJs das credenciadoras, com ou sem pontuação. Se omitido ou vazio, o opt-in vale para **todas** as credenciadoras. CNPJ desconhecido, ou de credenciadora não habilitada na operação, recusa a solicitação com `400`. | | arranjos | string[] | Não | Siglas dos arranjos de pagamento (ex.: `"MCC"`, `"VCC"`). Se omitido ou vazio, o opt-in vale para **todos** os arranjos. Sigla desconhecida recusa a solicitação com `400`. | **Regras e formatos** * `cnpj` e `credenciadoras`: com ou sem pontuação (`12.345.678/0001-95` e `12345678000195` são o mesmo CNPJ); nas respostas, sempre sem pontuação — ver **Formatos** em [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). * **Um opt-in por combinação.** A plataforma pede um opt-in para cada combinação de credenciadora × arranjo informada. Com as duas listas omitidas, é um único opt-in para todas as credenciadoras e todos os arranjos (**FULL**), que aparece em [4.20](4.20.%20Listar%20opt-ins.md) com `credenciadora` e `arranjo` nulos. Com só uma das listas, a outra dimensão vale "todos" (por exemplo, `credenciadoras` com dois CNPJs e sem `arranjos` = dois opt-ins, cada um com `arranjo` nulo). * Os filtros são validados como em [4.1. Solicitar agenda](4.1.%20Solicitar%20agenda.md): cada sigla de arranjo e cada CNPJ de credenciadora não reconhecidos geram **uma mensagem própria**, todas no mesmo `400`, e nada é gravado. Para saber quais credenciadoras são aptas na operação e quais siglas existem, consulte as rotas de [credenciadoras](../../8.%20Enumerações/8.1.%20Enumerações.md#credenciadoras) e de [arranjos](../../8.%20Enumerações/8.1.%20Enumerações.md#arranjos). * **Opt-in já ativo é reaproveitado.** Se o EC já tem, na mesma operação, um opt-in vigente para a combinação — feito por esta rota, pela [4.1](4.1.%20Solicitar%20agenda.md) ou pela plataforma —, nada é enviado à registradora para ela: o opt-in existente continua valendo e é o que aparece em [4.20](4.20.%20Listar%20opt-ins.md). Se outra solicitação de opt-in do mesmo EC ainda está em curso para a combinação, esta aguarda a dela. --- ## 🧪 Exemplo de cURL ```bash curl -X POST https://api.veflow.com/public/api/v1.1/cartao/optins \ -H "Authorization: Bearer {seu_token}" \ -H "GrupoEconomico: {seu_grupo_economico}" \ -H "Idempotency-Key: 3c8f2a51-7d4e-4b9a-8e16-5a2b0c9d7f41" \ -H "Content-Type: application/json" \ -d '{ "idOperacao": 1, "cnpj": "12.345.678/0001-95", "credenciadoras": ["10293847560102"], "arranjos": ["MCC","VCC"] }' ``` No exemplo, a plataforma pede dois opt-ins: credenciadora `10293847560102` com o arranjo `MCC`, e a mesma credenciadora com o arranjo `VCC`. --- ## 📥 Responses ### ✅ 202 Accepted ```json { "identificadorProcessamento": "a1b2c3d4-1111-2222-3333-444455556666", "mensagem": "Solicitação de opt-in recebida com sucesso!" } ``` | Campo | Tipo | Descrição | | -------------------------- | ------ | ------------------------------------------------------------------------------- | | identificadorProcessamento | string | GUID do processamento assíncrono, para acompanhamento e suporte. | | dataAgendamento | string | Só fora da janela de operação: data (`YYYY-MM-DD`) em que o pedido será enviado à registradora. Omitido dentro da janela. | | mensagem | string | Mensagem de confirmação. É apenas informativa: não a use em lógica. | A resposta não traz o `id` do opt-in: ele só existe depois que o pedido é processado. Consulte o resultado em [4.20. Listar opt-ins](4.20.%20Listar%20opt-ins.md), pelo `cnpj` (e pela `idOperacao`). --- ### ✅ 202 Accepted — fora da janela de operação ```json { "identificadorProcessamento": "a1b2c3d4-1111-2222-3333-444455556666", "dataAgendamento": "2025-08-11", "mensagem": "Solicitação de opt-in recebida e agendada para a próxima janela da registradora." } ``` Retornado quando a requisição chega fora da janela de operação da registradora. A solicitação não é recusada: fica agendada, e `dataAgendamento` informa a data da **próxima janela** — que pode ser o **próprio dia**, se a chamada vier antes da abertura. Com registradora de **demonstração**, não há janela: o pedido é processado na hora. --- ### ✅ 200 OK — `aceito: false` (nada foi gravado) ```json { "aceito": false, "motivo": [ "Registradora da operação está inativa." ] } ``` É um **resultado de negócio**, não um erro HTTP: nenhum pedido de opt-in é registrado e a `Idempotency-Key` não fica guardada — ver **Resultado de negócio** em [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). | Situação | `motivo` | | --------------------------------------------------------------- | ------------------------------------------------------------ | | Registradora da operação inativa | `Registradora da operação está inativa.` | | Registradora da operação não é a B3 nem de demonstração | `A registradora da operação não faz opt-in de cartões.` | | Campo | Tipo | Descrição | | ------ | -------- | -------------------------------------------- | | aceito | boolean | Sempre `false` neste caso. | | motivo | string[] | Lista de textos que explica a recusa. | --- ### ❌ 400 Bad Request Filtros inválidos voltam todos na mesma resposta, uma mensagem por problema, na chave vazia `""` de `errors`: ```json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1", "title": "Ocorreram um ou mais erros de validação.", "status": 400, "traceId": "00-5d1e8b3f2a7c4e9d0b6a1f3c8e2d7b45-9a4c2e7f1b3d5a60-00", "errors": { "": [ "Arranjo não encontrado: XYZ.", "Credenciadora não habilitada para a operação: 11222333000181." ] } } ``` Mensagens possíveis nesse bloco: | Situação | Mensagem | | ------------------------------------------------ | ----------------------------------------------------------------------------- | | Sigla de arranjo desconhecida | `Arranjo não encontrado: {sigla}.` | | CNPJ de credenciadora desconhecido | `Credenciadora não encontrada: {cnpj}.` | | Credenciadora não habilitada na operação | `Credenciadora não habilitada para a operação: {cnpj}.` | O `400` também é devolvido quando a operação não é de cartões (nem garantia nem antecipação), com a mensagem `A operação informada não permite operações de cartão.`. Erros de formato (`idOperacao` ou `cnpj` ausentes, `idOperacao` menor que `1`, CNPJ inválido) seguem o mesmo `ProblemDetails`, com a mensagem na chave do campo (`idOperacao`, `cnpj`) — ver **Formato de Erro** em [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). --- ### ❌ 403 Forbidden Retornado quando a consulta do estabelecimento na registradora não é permitida para o grupo econômico. A mensagem é genérica, nada é gravado e o pedido não deve ser repetido: fale com o time de implantação. O `403` também é o da credencial sem permissão para o recurso ou para o grupo econômico — ver [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). --- ### ❌ 404 Not Found Retornado quando a operação não existe no grupo econômico (`Operação não encontrada para o ID informado.`) ou quando a operação não tem registradora vinculada (`Registradora não vinculada à operação`). ```json { "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5", "title": "Not Found", "status": 404, "errors": { "": [ "Operação não encontrada para o ID informado." ] }, "traceId": "00-3e33b5aff74e6fc562a6de0caf23cb0a-baaa64d4c648c670-00" } ``` --- ### ❌ 422 Unprocessable Entity Retornado **somente** para `Idempotency-Key` reusada com outra requisição depois de um sucesso, ou enquanto a primeira chamada com a chave ainda processa — ver **Idempotência** em [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). --- ## 🔁 Depois do `202` 1. A plataforma envia o pedido à registradora dentro da janela de operação (ou na data de `dataAgendamento`). Em registradora de demonstração, o opt-in é registrado na hora, com um `protocolo` que começa por `DEMO-`. 2. Cada combinação passa a aparecer em [4.20. Listar opt-ins](4.20.%20Listar%20opt-ins.md) com `situacao` = `1` (Pendente) enquanto o pedido está na registradora. 3. Aceito pela registradora, o opt-in passa a `situacao` = `2` (Ativo), com `protocolo` e `dataExpiracao` (validade do opt-in, conforme o prazo configurado na operação). 4. Recusado pela registradora — ou esgotadas as retentativas de comunicação —, o opt-in fica com `situacao` = `3` (Falhou) e o motivo em `mensagemErro`. Corrija o que for preciso e envie um novo pedido. Falhas de comunicação com a registradora são retentadas automaticamente pela plataforma, sempre com o mesmo pedido: a retentativa não gera um segundo opt-in. **Recuperação.** Se o opt-in de uma combinação não aparecer em [4.20](4.20.%20Listar%20opt-ins.md), ou ficar em `situacao` = `1` por muito tempo dentro da janela de operação, envie um **novo** `POST optins` com os mesmos dados e **outra** `Idempotency-Key` (a chave da primeira chamada devolveria a resposta guardada, sem processar de novo). O novo pedido retoma o que já tiver sido reservado ou reaproveita o opt-in vigente: ele **não duplica** o opt-in. --- ## 🕒 Observações * As solicitações são processadas **dentro da janela de operação da registradora da operação** (horário publicado: 09:00 às 18:00 em dias úteis; vale o horário cadastrado na registradora, inclusive o de véspera de feriado) — ver **Janela de Operação** em [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md). * O opt-in é do **estabelecimento**, não da chamada: o mesmo opt-in pode ser usado por várias agendas do EC na operação. O cancelamento em [4.21. Cancelar opt-in](4.21.%20Cancelar%20opt-in.md) vale para todas elas. * Opt-in expirado (`situacao` = `4`) ou cancelado (`situacao` = `5`) não é reaproveitado: a próxima solicitação, por esta rota ou pela [4.1](4.1.%20Solicitar%20agenda.md), pede um opt-in novo. * O resultado do opt-in não é notificado por webhook: acompanhe-o por [4.20. Listar opt-ins](4.20.%20Listar%20opt-ins.md). * Headers obrigatórios e convenções gerais: [1.2. Convenções da API](../../1.%20Início/1.2.%20Convenções%20da%20API.md).