Atualizar VCN
Use o Sandbox para preparar a integração e validar a autenticação e o contrato.
Atualiza uma VCN CUSTOM sem trocar o cartão (o PAN continua o mesmo): recarrega o teto, prorroga ou encurta a janela e ajusta os controles. VCNs HOTEL e AERIAL não são atualizáveis: os controles delas vêm da reserva.
Antes de chamar
- Envie o
requestore só o que quer mudar, pelo menos um campo além dele; o que não vier não muda. - ⚠️ No período
TOTAL,limit.valueé o teto acumulado da janela, não um incremento: envie o teto vigente mais o crédito. Veja Teto e recarga. - Guarde o teto que volta no
200: ele é a base da próxima recarga. - Para reler o estado e o teto, use Consultar VCN; para encerrar o cartão, Cancelar VCN. Encurtar o
endDatenão encerra.
Erros
400 bad-request-exception— corpo inválido, comerrors[]:requestorausente, nenhum campo além dele, valor abaixo de0.01, chave fora da lista de atualizáveis ouvcnIdinválido. Veja Corpo da requisição.400 invalid-vcn-request— o novoendDatequebra um limite da janela; o motivo vem nomessage. Veja Limites das datas.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.409 vcn-not-updatable— a VCN não éCUSTOM.409 vcn-not-active— a VCN estáBLOCKEDouCANCELLED. Cancelada não volta; bloqueada, acione a Conta Simples. Confira ostatusem Consultar VCN.409 vcn-expired— a janela venceu (a partir do dia seguinte aoendDate). Não recarregue: emita outra em Criar VCN, com a mesma chave.409 vcn-limit-conflict— o teto mudou entre a leitura e a escrita, com ou semexpectedValue. Recalcule a partir do teto mais recente e repita. Veja Recargas em paralelo.500 internal-exception— erro interno, inclusive recusa definitiva do provedor. Acione o suporte com o horário e orequestId.503 vcn-update-unavailable— falha transitória do provedor. Repita a requisição.
Os 409 são avaliados antes do 400 invalid-vcn-request, na ordem da lista.
Regras
Teto e recarga · Janela de uso · Corpo da requisição · Ordem de avaliação
curl -X PATCH "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 "Content-Digest: example_string" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}'
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",
"Content-Digest": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
data = {
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}
response = requests.patch(url, headers=headers, json=data)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "PATCH",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Content-Digest": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
},
body: JSON.stringify({
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
})
});
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
},
"requestor": "automacao-fornecedores"
}`)
req, err := http.NewRequest("PATCH", "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("Content-Digest", "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::Patch.new(uri)
request['Content-Type'] = 'application/json'
request['X-Partner-Id'] = 'ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY'
request['Signature-Input'] = 'example_string'
request['Signature'] = 'example_string'
request['Content-Digest'] = 'example_string'
request['Authorization'] = 'Bearer YOUR_API_TOKEN'
request.body = '{
"limit": {
"value": 350,
"expectedValue": 0.01
},
"requestor": "automacao-fornecedores"
}'
response = http.request(request)
puts response.body
{
"vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
"limit": {
"value": 350,
"currency": "BRL"
},
"endDate": "2027-05-07",
"maxPurchaseQuantity": 10000,
"spendLimitPeriod": "TOTAL",
"updatedAt": "2027-03-04T09:15:40.000Z"
}
{
"code": "bad-request-exception",
"message": "Event failed validation",
"errors": [
{
"field": "body",
"message": "at least one updatable field is required"
}
]
}
{
"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"
}
{
"code": "invalid-vcn-request",
"message": "Unable to issue a VCN for this request: end date must not exceed the funding card expiration"
}
{
"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": "updateVcn"
},
"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": "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": "An unexpected error occurred on the server"
}
{
"code": "vcn-update-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
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.
Hash do corpo da requisição no formato da RFC 9530, com sha-256 ou sha-512, por exemplo sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:. É obrigatório quando a requisição tem corpo e a credencial tem chave pública, e nesse caso o Signature-Input precisa incluir o componente content-digest.
Recarga ou ajuste do teto de gasto.
Novo fim da janela, YYYY-MM-DD, inclusivo, em dia de Brasília; pode subir ou descer. Não pode ser anterior a hoje, tem de ser posterior ao startDate e respeita os limites da emissão. Veja Limites das datas. Para encerrar o cartão, use Cancelar VCN.
Número máximo de autorizações, até 100000.
Novo período do teto: TOTAL, MONTHLY ou DAILY. Omitido, mantém o vigente. Trocar o período não zera o que já foi gasto.
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.
Hash do corpo da requisição no formato da RFC 9530, com sha-256 ou sha-512, por exemplo sha-256=:X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE=:. É obrigatório quando a requisição tem corpo e a credencial tem chave pública, e nesse caso o Signature-Input precisa incluir o componente content-digest.
Body
Recarga ou ajuste do teto de gasto.
Novo fim da janela, YYYY-MM-DD, inclusivo, em dia de Brasília; pode subir ou descer. Não pode ser anterior a hoje, tem de ser posterior ao startDate e respeita os limites da emissão. Veja Limites das datas. Para encerrar o cartão, use Cancelar VCN.
2027-06-30Novo período do teto: TOTAL, MONTHLY ou DAILY. Omitido, mantém o vigente. Trocar o período não zera o que já foi gasto.
TOTALMONTHLYDAILYQuem 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.
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. Inclusivo: o cartão autoriza até o fim desse dia, no horário de Brasília.
Valor efetivo vigente.
Período vigente após a operação — o enviado nesta chamada ou o que já valia.
TOTALMONTHLYDAILYCarimbo desta atualização (UTC).