Ir para o conteúdo

4.21. Cancelar opt-in

🔗 Endpoint

Método URL
DELETE /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. dataOptout passa a vir preenchida, mas a situacao continua 3 — 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: false por 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 o id do opt-in e o protocolo.
  • O cancelamento não é notificado por webhook.
  • Headers obrigatórios e convenções gerais: 1.2. Convenções da API.