4.19. Solicitar opt-in¶
🔗 Endpoint¶
| Método | URL |
|---|---|
/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
cnpjecredenciadoras: com ou sem pontuação (12.345.678/0001-95e12345678000195sã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
credenciadoraearranjonulos. Com só uma das listas, a outra dimensão vale "todos" (por exemplo,credenciadorascom dois CNPJs e semarranjos= dois opt-ins, cada um comarranjonulo). - 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¶
- 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 umprotocoloque começa porDEMO-. - Cada combinação passa a aparecer em 4.20. Listar opt-ins com
situacao=1(Pendente) enquanto o pedido está na registradora. - Aceito pela registradora, o opt-in passa a
situacao=2(Ativo), comprotocoloedataExpiracao(validade do opt-in, conforme o prazo configurado na operação). - Recusado pela registradora — ou esgotadas as retentativas de comunicação —, o opt-in fica com
situacao=3(Falhou) e o motivo emmensagemErro. 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.