VCNCancelar VCN

Cancelar VCN

Encerra uma VCN de forma definitiva, nos três tipos, mesmo com a janela já vencida: o cartão deixa de autorizar compras e não volta a ACTIVE. O corpo leva só o requestor, quem pede o cancelamento. A resposta é o corpo de Consultar VCN com status: CANCELLED, sem o bloco card; janela, teto e contagens não mudam.

Antes de chamar

  • Repetir é seguro: uma VCN já cancelada responde 200 com o mesmo corpo e o mesmo updatedAt, sem novo efeito.
  • Depois do cancelamento, Revelar dados do VCN responde 409 vcn-cancelled e, no CUSTOM, Atualizar VCN responde 409 vcn-not-active.
  • A chave de idempotência fica livre: uma nova emissão com ela em Criar VCN gera outro cartão, com PAN novo, e o vcnId cancelado passa a responder 404 em todas as rotas.

Erros

  • 400 bad-request-exception — vcnId inválido no path (field path.vcnId).
  • 400 bad-request-exception — corpo inválido, com errors[]: sem corpo, requestor ausente ou fora do limite, ou chave além do requestor. Veja Corpo da requisição.
  • 400 bad-request-exception — X-Partner-Id ausente ou fora do formato (field headers.x-partner-id). Veja Identificação da plataforma.
  • 403 caller-not-authorized — o partner do X-Partner-Id não está vinculado à sua credencial (details.reason PARTNER_NOT_BOUND), ou falta à credencial o escopo da rota (details.requiredScope). Veja Identificação da plataforma.
  • 404 vcn-not-found — VCN inexistente, de outra empresa ou substituída por reemissão. Logo após a emissão, repita antes de concluir.
  • 500 internal-exception — recusa definitiva do provedor (a VCN continua válida) ou tempo esgotado interno (o cancelamento pode ter sido concluído). Repita o DELETE ou confira o status em Consultar VCN; se continuar ACTIVE, acione o suporte com o horário, o requestId e o vcnId.
  • 503 vcn-cancel-unavailable — falha transitória do provedor; a VCN continua válida. Repita a requisição.
  • 503 vcn-cancellation-not-persisted — o cartão já foi cancelado no provedor, mas o cancelamento ainda não foi concluído na Conta Simples: Consultar VCN pode mostrar ACTIVE, e uma nova emissão na mesma chave responde 409 vcn-already-issued. Repita o DELETE; se persistir, acione o suporte (o vcnId vem no message).

Regras

Repetir chamadas · Idempotência e reemissão · Corpo da requisição

curl -X DELETE "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN" \
  -H "Content-Type: application/json" \
  -H "X-Partner-Id: ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY" \
  -H "Signature-Input: example_string" \
  -H "Signature: example_string" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "requestor": "agente@exemplo.test"
}'
{
  "vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
  "reference": "SUP-000123",
  "type": "CUSTOM",
  "status": "CANCELLED",
  "startDate": "2027-03-01",
  "endDate": "2027-06-30",
  "limit": {
    "value": 350,
    "currency": "BRL"
  },
  "maxPurchaseQuantity": 10000,
  "spendLimitPeriod": "TOTAL",
  "createdAt": "2027-03-01T14:32:10.000Z",
  "updatedAt": "2027-03-08T11:04:55.000Z"
}
DELETE
/credit-cards/v1/vcns/{vcnId}
DELETE
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
path
vcnIdstring
Required

Identificador do VCN retornado na emissão (campo vcnId).

Content-Typestring
Required

The media type of the request body

Options: application/json
header
X-Partner-Idstring
Required

Identificador da plataforma integradora (partner) pela qual a chamada é feita: ptn_ seguido de um ULID de 26 caracteres. É gerado pela Conta Simples e entregue a você no onboarding. Veja Identificação da plataforma.

Pattern: ^ptn_[0-9A-HJKMNP-TV-Z]{26}$
header
Signature-Inputstring

O que foi assinado e os parâmetros da assinatura, no formato da RFC 9421. Uma credencial com chave pública precisa enviar este header em todas as chamadas, inclusive as de leitura, ou a requisição é recusada com 401. A assinatura cobre os componentes @method, @path e @query, e também content-digest quando houver corpo. created e alg são obrigatórios, e o created vale por 300 segundos. O formato completo, com exemplos, está em Assinatura de Requisições.

header
Signaturestring

A assinatura da base definida pela RFC 9421, em base64, entre : e com o mesmo rótulo usado no Signature-Input, por exemplo sig=:SGVsbG8gd29ybGQ=:. Vai sempre junto com o Signature-Input.

requestorstring
Required

Quem pede a emissão, a atualização ou o cancelamento, para auditoria. Envie o e-mail de um usuário ou, numa chamada automatizada, um identificador do seu sistema. Texto livre de 1 a 100 caracteres.

Min length: 1 • Max length: 100
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN

Path Parameters

vcnIdstring
Required

Identificador do VCN retornado na emissão (campo vcnId).

Example:
01JQ8ZP4C7D9F1G3H5J7K9J2MN

Headers

X-Partner-Idstring
Required

Identificador da plataforma integradora (partner) pela qual a chamada é feita: ptn_ seguido de um ULID de 26 caracteres. É gerado pela Conta Simples e entregue a você no onboarding. Veja Identificação da plataforma.

Example:
ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY
Signature-Inputstring

O que foi assinado e os parâmetros da assinatura, no formato da RFC 9421. Uma credencial com chave pública precisa enviar este header em todas as chamadas, inclusive as de leitura, ou a requisição é recusada com 401. A assinatura cobre os componentes @method, @path e @query, e também content-digest quando houver corpo. created e alg são obrigatórios, e o created vale por 300 segundos. O formato completo, com exemplos, está em Assinatura de Requisições.

Signaturestring

A assinatura da base definida pela RFC 9421, em base64, entre : e com o mesmo rótulo usado no Signature-Input, por exemplo sig=:SGVsbG8gd29ybGQ=:. Vai sempre junto com o Signature-Input.

Body

application/json
requestorstring
Required

Quem pede a emissão, a atualização ou o cancelamento, para auditoria. Envie o e-mail de um usuário ou, numa chamada automatizada, um identificador do seu sistema. Texto livre de 1 a 100 caracteres.

Example:
agente@exemplo.test

Responses

vcnIdstring
Required

Eco do identificador consultado.

referencestring
Required

Chave de idempotência da VCN, como texto, nos três tipos: o reservationId no HOTEL, o recordLocator no AERIAL e o reference enviado no CUSTOM.

typestring
Required

Vínculo do cartão.

Allowed values:HOTELAERIALCUSTOM
statusstring
Required

ACTIVE, BLOCKED ou CANCELLED. CANCELLED é definitivo e vem de Cancelar VCN. Não há status de vencida: compare o endDate com o dia de hoje em Brasília.

Allowed values:ACTIVEBLOCKEDCANCELLED
startDatestring
Required

Início da janela de uso, YYYY-MM-DD, em dia de calendário no horário de Brasília — o mesmo valor devolvido na emissão.

endDatestring
Required

Fim da janela de uso vigente, YYYY-MM-DD, inclusivo: o cartão autoriza até o fim desse dia, no horário de Brasília. Reflete a última atualização; o cancelamento não o altera.

limitstring
Required

Teto de gasto vigente — não é saldo nem disponível: o consumo não é devolvido por esta API.

amountstring

Custo da reserva — presente só em HOTEL/AERIAL; ausente no CUSTOM. É o único campo opcional deste corpo.

maxPurchaseQuantityinteger
Required

Número máximo de autorizações vigente.

spendLimitPeriodstring
Required

Período do teto vigente — sempre presente.

Allowed values:TOTALMONTHLYDAILY
createdAtstring
Required

Instante da emissão, em UTC. O dia da emissão em startDate é contado no horário de Brasília: numa emissão entre 21h e 24h (Brasília), as duas datas diferem.

updatedAtstring
Required

Instante da última alteração — atualização ou cancelamento —, em UTC. Repetir o cancelamento de uma VCN já cancelada não o altera.