VCNConsultar VCN

Consultar VCN

Devolve o estado de uma VCN já emitida: status, janela de uso, teto vigente e controles. Não traz os dados do cartão, que ficam em Revelar dados do VCN, nem o eco do bloco de reserva, nem saldo ou consumo: limit.value é o teto, não o disponível.

Antes de chamar

  • Uma VCN cancelada responde 200, com status: CANCELLED. É por aqui que você descobre por que Revelar respondeu 409 vcn-cancelled.
  • Não existe status de vencida: uma VCN vencida continua ACTIVE. Compare o endDate, que é inclusivo, com o dia de hoje em Brasília.
  • Logo depois de emitir, atualizar ou cancelar, a leitura pode atrasar alguns instantes. Veja Leitura logo após escrever.

Erros

  • 400 bad-request-exception — vcnId inválido no path (field path.vcnId).
  • 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 — erro interno; repetir a leitura é seguro. Se persistir, acione o suporte com o horário e o requestId.

Regras

Leitura logo após escrever · Idempotência e reemissão

curl -X GET "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"
{
  "vcnId": "01JQ8ZP4C7D9F1G3H5J7K9J2MN",
  "reference": "SUP-000123",
  "type": "CUSTOM",
  "status": "ACTIVE",
  "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-05T10:20:03.000Z"
}
GET
/credit-cards/v1/vcns/{vcnId}
GET
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).

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.

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.

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.