VCNAtualizar VCN

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 requestor e 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 endDate não encerra.

Erros

  • 400 bad-request-exception — corpo inválido, com errors[]: requestor ausente, nenhum campo além dele, valor abaixo de 0.01, chave fora da lista de atualizáveis ou vcnId inválido. Veja Corpo da requisição.
  • 400 invalid-vcn-request — o novo endDate quebra um limite da janela; o motivo vem no message. Veja Limites das datas.
  • 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.
  • 409 vcn-not-updatable — a VCN não é CUSTOM.
  • 409 vcn-not-active — a VCN está BLOCKED ou CANCELLED. Cancelada não volta; bloqueada, acione a Conta Simples. Confira o status em Consultar VCN.
  • 409 vcn-expired — a janela venceu (a partir do dia seguinte ao endDate). 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 sem expectedValue. 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 o requestId.
  • 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"
}'
{
  "vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
  "limit": {
    "value": 350,
    "currency": "BRL"
  },
  "endDate": "2027-05-07",
  "maxPurchaseQuantity": 10000,
  "spendLimitPeriod": "TOTAL",
  "updatedAt": "2027-03-04T09:15:40.000Z"
}
PATCH
/credit-cards/v1/vcns/{vcnId}
PATCH
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.

header
Content-Digeststring

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.

limitobject

Recarga ou ajuste do teto de gasto.

endDatestring

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.

Format: date
maxPurchaseQuantityinteger

Número máximo de autorizações, até 100000.

Min: 1 • Max: 100000
spendLimitPeriodstring

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.

Options: TOTAL, MONTHLY, DAILY
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.

Content-Digeststring

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

application/json
limitobject

Recarga ou ajuste do teto de gasto.

endDatestring

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.

Example:
2027-06-30
maxPurchaseQuantityinteger

Número máximo de autorizações, até 100000.

Example:
10000
spendLimitPeriodstring

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.

Allowed values:TOTALMONTHLYDAILY
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.

limitstring
Required

Teto vigente após a operação — guarde-o e some o próximo crédito sobre ele.

endDatestring
Required

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.

maxPurchaseQuantityinteger
Required

Valor efetivo vigente.

spendLimitPeriodstring
Required

Período vigente após a operação — o enviado nesta chamada ou o que já valia.

Allowed values:TOTALMONTHLYDAILY
updatedAtstring
Required

Carimbo desta atualização (UTC).