Atualizar VCN (Em breve)
🚧 Em breve — este endpoint ainda não está disponível em Sandbox nem Produção. A documentação está publicada para você preparar a integração; avisaremos no changelog quando entrar no ar.
Atualiza uma VCN CUSTOM já emitida sem trocar o cartão — o PAN continua o mesmo. É por aqui que se faz a recarga do teto e a prorrogação (ou o encurtamento) da validade. Envie só o que quer mudar (pelo menos um campo); campo não enviado não muda. VCNs AERIAL e HOTEL não são atualizáveis — os controles delas derivam da reserva (409 vcn-not-updatable).
⚠️ limit.value é o teto ACUMULADO da janela — não é saldo nem incremento. O disponível é calculado pela rede do cartão (disponível = teto − consumido). Para adicionar crédito, envie novo total = teto vigente + crédito. Ex.: teto 100.01 e nova venda de R$ 80 → envie 180.01; enviar 80.00 derruba o teto para baixo do que já foi gasto e toda captura passa a ser recusada. A resposta devolve o teto vigente para você fechar o loop; com recargas em paralelo, use limit.expectedValue.
As regras de cada campo estão documentadas no próprio campo, abaixo; o comportamento de cada erro, em Respostas.
curl -X PATCH "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9L2MN" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"limit": {
"value": 350,
"expectedValue": 0.01
}
}'
import requests
import json
url = "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9L2MN"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"limit": {
"value": 350,
"expectedValue": 0.01
}
}
response = requests.patch(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9L2MN", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"limit": {
"value": 350,
"expectedValue": 0.01
}
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"bytes"
"encoding/json"
)
func main() {
data := []byte(`{
"limit": {
"value": 350,
"expectedValue": 0.01
}
}`)
req, err := http.NewRequest("PATCH", "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9L2MN", bytes.NewBuffer(data))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
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/01JQ8ZP4C7D9F1G3H5J7K9L2MN')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
"limit": {
"value": 350,
"expectedValue": 0.01
}
}'
response = http.request(request)
puts response.body
{
"vcnId": "01JQ8ZP4C7D9F1G3H5J7K9L2MN",
"limit": {
"value": 350,
"currency": "BRL"
},
"endDate": "2026-10-27",
"maxPurchaseQuantity": 10000,
"updatedAt": "2026-08-24T09:15:40.000Z"
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "body",
"message": "at least one updatable field must be provided"
}
]
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: validity window must end after it starts"
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: end date must fall within the maximum validity window from issuance"
}
{
"error": "Unauthorized",
"message": "Token de acesso inválido ou expirado.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 401
}
{
"error": "Forbidden",
"message": "Você não tem permissão para realizar esta operação.",
"requestId": "123e4567-e89b-12d3-a456-426614174000",
"code": 403
}
{
"code": "vcn-not-found",
"message": "VCN not found"
}
{
"code": "vcn-expired",
"message": "The VCN validity window has ended; issue a new VCN."
}
{
"code": "vcn-not-active",
"message": "The VCN is not active and cannot be updated."
}
{
"code": "vcn-limit-conflict",
"message": "The current limit does not match expectedValue; re-read the VCN and retry."
}
{
"code": "vcn-not-updatable",
"message": "This VCN type does not accept updates."
}
{
"code": "internal-exception",
"message": "Aconteceu um erro"
}
{
"code": "vcn-provider-unavailable",
"message": "The VCN update could not be completed; retry the request."
}
/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
Recarga ou ajuste do teto de gasto.
Novo fim da janela de uso, YYYY-MM-DD — o mesmo nome do campo na emissão. Pode subir e descer. Deve ser futuro e nunca além de 365 dias da emissão — o teto conta da emissão, então recargas não empurram a validade. Mexer no limit não muda a validade: para os dois, envie os dois campos.
Número máximo de autorizações, até 100000.
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).
01JQ8ZP4C7D9F1G3H5J7K9L2MNBody
Recarga ou ajuste do teto de gasto.
Novo fim da janela de uso, YYYY-MM-DD — o mesmo nome do campo na emissão. Pode subir e descer. Deve ser futuro e nunca além de 365 dias da emissão — o teto conta da emissão, então recargas não empurram a validade. Mexer no limit não muda a validade: para os dois, envie os dois campos.
2026-11-15Responses
Eco do identificador.
Teto vigente após a operação — guarde-o e some o próximo crédito sobre ele.
Fim da janela de uso vigente, YYYY-MM-DD — o mesmo nome e o mesmo formato do campo na emissão.
Valor efetivo vigente.
Carimbo desta atualização (UTC).