Ir para o conteúdo

4.19. Solicitar opt-in

🔗 Endpoint

Método URL
POST /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 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 — ali, situacao = 2 (Ativo) indica o opt-in registrado na registradora.

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 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)

{
  "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.
  • 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 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: 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 e de 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 ou pela plataforma —, nada é enviado à registradora para ela: o opt-in existente continua valendo e é o que aparece em 4.20. 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

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

{
  "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, pelo cnpj (e pela idOperacao).


✅ 202 Accepted — fora da janela de operação

{
  "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)

{
  "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.

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:

{
  "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.


❌ 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.


❌ 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).

{
  "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.


🔁 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 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, 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.
  • 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 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, pede um opt-in novo.
  • O resultado do opt-in não é notificado por webhook: acompanhe-o por 4.20. Listar opt-ins.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.