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, comstatus: CANCELLED. É por aqui que você descobre por que Revelar respondeu409 vcn-cancelled. - Não existe status de vencida: uma VCN vencida continua
ACTIVE. Compare oendDate, 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—vcnIdinválido no path (fieldpath.vcnId).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— erro interno; repetir a leitura é seguro. Se persistir, acione o suporte com o horário e orequestId.
Regras
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"
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"
}
response = requests.get(url, headers=headers)
print(response.json())
const response = await fetch("https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", {
method: "GET",
headers: {
"Content-Type": "application/json",
"X-Partner-Id": "ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"Signature-Input": "example_string",
"Signature": "example_string",
"Authorization": "Bearer YOUR_API_TOKEN"
}
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
)
func main() {
req, err := http.NewRequest("GET", "https://api-sandbox.contasimples.com/credit-cards/v1/vcns/01JQ8ZP4C7D9F1G3H5J7K9J2MN", nil)
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::Get.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'
response = http.request(request)
puts response.body
{
"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"
}
{
"vcnId": "01JQ8ZK7X4M8N2P5R6T7V8W9XY",
"reference": "ACME-RES-998877",
"type": "HOTEL",
"status": "ACTIVE",
"startDate": "2027-03-01",
"endDate": "2027-04-07",
"limit": {
"value": 1622.5,
"currency": "BRL"
},
"amount": {
"rate": 1250,
"taxes": 187.5,
"fees": 35,
"currency": "BRL"
},
"maxPurchaseQuantity": 3,
"spendLimitPeriod": "TOTAL",
"createdAt": "2027-03-01T13:05:22.000Z",
"updatedAt": "2027-03-01T13:05:22.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": "getVcn"
},
"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"
}
/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).
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.
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.
Responses
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.