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
200com o mesmo corpo e o mesmoupdatedAt, sem novo efeito. - Depois do cancelamento, Revelar dados do VCN responde
409 vcn-cancellede, noCUSTOM, Atualizar VCN responde409 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
vcnIdcancelado passa a responder404em todas as rotas.
Erros
400 bad-request-exception—vcnIdinválido no path (fieldpath.vcnId).400 bad-request-exception— corpo inválido, comerrors[]: sem corpo,requestorausente ou fora do limite, ou chave além dorequestor. Veja Corpo da requisição.400 bad-request-exception—X-Partner-Idausente ou fora do formato (fieldheaders.x-partner-id). Veja Identificação da plataforma.403 caller-not-authorized— o partner doX-Partner-Idnão está vinculado à sua credencial (details.reasonPARTNER_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 oDELETEou confira ostatusem Consultar VCN; se continuarACTIVE, acione o suporte com o horário, orequestIde ovcnId.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 mostrarACTIVE, e uma nova emissão na mesma chave responde409 vcn-already-issued. Repita oDELETE; se persistir, acione o suporte (ovcnIdvem nomessage).
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"
}'
import requests
import json
url = "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN"
headers = {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"requestor": "agente@exemplo.test"
}
response = requests.delete(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "DELETE",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"requestor": "agente@exemplo.test"
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"requestor": "agente@exemplo.test"
}`)
req, err := http.NewRequest("DELETE", "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", bytes.NewBuffer(data))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-Partner-Id", "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY")
req.Header.Set("Signature-Input", "example_string")
req.Header.Set("Signature", "example_string")
req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
fmt.Println("Response Status:", resp.Status)
}
require 'net/http'
require 'json'
uri = URI('https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Delete.new(uri)
request['Content-Type'] = 'application/json'
request['X-Partner-Id'] = 'ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY'
request['Signature-Input'] = 'example_string'
request['Signature'] = 'example_string'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
"requestor": "agente@exemplo.test"
}'
response = http.request(request)
puts response.body
{
"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"
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "path.vcnId",
"message": "vcnId is not a valid identifier"
}
]
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "headers.x-partner-id",
"message": "x-partner-id must be a valid partner identifier"
}
]
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"details": {
"reason": "SIGNATURE_REQUIRED"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "unauthorized",
"message": "Authentication failed. Check the API token and the request signature",
"details": {
"reason": "INVALID_SIGNATURE"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "caller-not-authorized",
"message": "The request is not allowed for the current credentials",
"details": {
"requiredScope": "cancelVcn"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "caller-not-authorized",
"message": "The request is not allowed for the current credentials",
"details": {
"reason": "PARTNER_NOT_BOUND"
},
"requestId": "123e4567-e89b-12d3-a456-426614174000"
}
{
"code": "vcn-not-found",
"message": "VCN not found"
}
{
"code": "internal-exception",
"message": "An unexpected error occurred on the server"
}
{
"code": "vcn-cancel-unavailable",
"message": "The VCN cancellation could not be completed; retry the request."
}
{
"code": "vcn-cancellation-not-persisted",
"message": "The VCN was cancelled at the provider but the local record was not updated; reconcile vcnId: 01JQ8ZP4C7D9F1G3H5J7K9J2MN"
}
/credit-cards/v1/vcns/{vcnId}Target server for requests. Edit to use your own host.
Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
Bearer TOKENIdentificador do VCN retornado na emissão (campo vcnId).
The media type of the request body
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.
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.
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.
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.
Request Preview
Response
Response will appear here after sending the request
Authentication
Bearer token. Token Bearer obtido via OAuth 2.0 Client Credentials. Formato: Bearer TOKEN
Path Parameters
Identificador do VCN retornado na emissão (campo vcnId).
01JQ8ZP4C7D9F1G3H5J7K9J2MNHeaders
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.
ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XYO 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.
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
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.
agente@exemplo.testResponses
Eco do identificador consultado.
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.
Vínculo do cartão.
HOTELAERIALCUSTOMACTIVE, 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.
ACTIVEBLOCKEDCANCELLEDIní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.
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.
Teto de gasto vigente — não é saldo nem disponível: o consumo não é devolvido por esta API.
Custo da reserva — presente só em HOTEL/AERIAL; ausente no CUSTOM. É o único campo opcional deste corpo.
Número máximo de autorizações vigente.
Período do teto vigente — sempre presente.
TOTALMONTHLYDAILYInstante 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.
Instante da última alteração — atualização ou cancelamento —, em UTC. Repetir o cancelamento de uma VCN já cancelada não o altera.