4.21. Cancelar opt-in¶
🔗 Endpoint¶
| Método | URL |
|---|---|
/public/api/v1.1/cartao/optins/{idOptin} |
🧾 Descrição¶
Cancela (OPT-OUT) um opt-in do estabelecimento comercial (EC) na registradora.
O cancelamento é síncrono: a plataforma pede o opt-out à registradora durante a chamada e responde com o opt-in no estado final, no mesmo formato de 4.20. Listar opt-ins, acrescido de aceito e motivo.
O opt-out vale para todas as agendas que usam o opt-in
O opt-in é do estabelecimento, não da agenda: o mesmo opt-in é reaproveitado por todas as agendas do EC na operação — as solicitadas por 4.1. Solicitar agenda, as feitas pela plataforma e o pedido de 4.19. Solicitar opt-in. Cancelá-lo vale para todas elas.
- Contratos já registrados com base no opt-in não são desfeitos pela registradora.
- A próxima solicitação de agenda (4.1) ou de opt-in (4.19) da mesma combinação pede um opt-in novo à registradora.
📤 Requisição¶
🧭 Parâmetros de rota¶
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| idOptin | string | Sim | O id do opt-in devolvido em 4.20. Listar opt-ins. Texto opaco. |
Esta rota não tem corpo nem query params. Aceita o header Idempotency-Key — ver Idempotência em 1.2. Convenções da API.
🧪 Exemplo de cURL¶
curl -X DELETE https://api.veflow.com/public/api/v1.1/cartao/optins/91827364501928374650192837465019 \
-H "Authorization: Bearer {seu_token}" \
-H "GrupoEconomico: {seu_grupo_economico}" \
-H "Idempotency-Key: 6b0d4e2a-91c7-4f38-a5d2-0e8c7b3f1a96"
📥 Responses¶
✅ 200 OK — opt-out realizado¶
{
"id": "91827364501928374650192837465019",
"idOperacao": 1,
"credenciadora": {
"cnpj": "10293847560102",
"nome": "CREDENCIADORA EXEMPLO S.A."
},
"arranjo": {
"sigla": "MCC",
"nome": "Mastercard Cartão de Crédito"
},
"situacao": 5,
"protocolo": "202508110000123456",
"dataExpiracao": "2026-08-11T13:05:27Z",
"dataOptout": "2025-09-02T14:18:03Z",
"mensagemErro": null,
"aceito": true,
"motivo": []
}
| Campo | Tipo | Descrição |
|---|---|---|
| aceito | boolean | true quando o opt-in está cancelado ao fim da chamada (inclusive se já estava). Sempre presente. |
| motivo | string[] | Motivos da recusa. Lista vazia ([]) quando aceito = true. |
Os demais campos são o registro do opt-in, com os mesmos significados de 4.20. Listar opt-ins, já no estado final: depois do opt-out, situacao = 5 e dataOptout preenchida.
Casos que também respondem 200 com aceito: true:
- Opt-in já cancelado: a resposta traz o estado atual, sem chamar a registradora de novo. Repetir o cancelamento é seguro.
- Opt-in que falhou (
situacao=3): nunca foi registrado na registradora, então o cancelamento é feito só na plataforma.dataOptoutpassa a vir preenchida, mas asituacaocontinua3— a falha prevalece (ver situacao em 4.20). - Registradora de demonstração: o cancelamento é feito só na plataforma.
✅ 200 OK — aceito: false (nada foi gravado)¶
{
"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,
"aceito": false,
"motivo": [
"O opt-in ainda está em processamento na registradora. Tente novamente quando a situação for ativo ou falhou."
]
}
É um resultado de negócio, não um erro HTTP: o opt-in não foi cancelado, nada foi gravado e a Idempotency-Key não fica guardada — repita o pedido, com a mesma chave, quando a situação permitir. Ver Resultado de negócio em 1.2. Convenções da API.
| Situação | motivo |
|---|---|
Opt-in ainda em processamento (situacao = 1, sem protocolo) | O opt-in ainda está em processamento na registradora. Tente novamente quando a situação for ativo ou falhou. |
| A registradora não confirmou o opt-out | A registradora não confirmou o opt-out. |
| Falha de comunicação com a registradora | O texto do erro devolvido na comunicação. |
O opt-in em processamento é recusado porque o pedido dele pode estar na registradora naquele momento: cancelá-lo só na plataforma deixaria um opt-in vivo na registradora. Aguarde a situacao = 2 (Ativo) ou 3 (Falhou) em 4.20 e repita o cancelamento.
❌ 404 Not Found¶
Retornado quando o idOptin não existe ou pertence a outro grupo econômico. As duas situações respondem igual.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "Not Found",
"status": 404,
"errors": {
"": [
"Opt-in não encontrado."
]
},
"traceId": "00-8d2f6a1c4e7b9035d1a3c5e7f9b2d4a6-3e5a7c9b1d2f4068-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.
🕒 Observações¶
- O cancelamento depende de comunicação com a registradora apenas para o opt-in ativo ou expirado; os demais casos são resolvidos na plataforma.
- Se a chamada responder
aceito: falsepor falha de comunicação, o opt-out pode ter sido processado pela registradora mesmo assim. Confira em 4.20 e repita o cancelamento; persistindo a recusa, acione o suporte informando oiddo opt-in e oprotocolo. - O cancelamento não é notificado por webhook.
- Headers obrigatórios e convenções gerais: 1.2. Convenções da API.