Guia de VCN

Visão geral

A VCN (Virtual Card Number) é um cartão virtual de uso restrito, emitido a partir do cartão de funding da sua empresa, o cartão corporativo de onde ela sai. Cada VCN tem uma janela de uso, um teto de gastos e um número máximo de autorizações (maxPurchaseQuantity). PAN, CVV e validade voltam na emissão.

Tipos

Escolha o type pelo que o cartão vai pagar. O tipo define o identificador que você envia e de onde vem o teto:

Só o CUSTOM é atualizável: os controles de HOTEL e AERIAL vêm da reserva.

Ciclo de vida

As seções abaixo detalham as regras de cada etapa.

Identificação da plataforma (X-Partner-Id)

Toda chamada de VCN informa, no header X-Partner-Id, a plataforma integradora (partner) pela qual ela é feita. O header é obrigatório em todas as rotas de VCN.

• Credencial com mais de um partner: uma credencial pode estar vinculada a mais de uma plataforma. Envie, em cada chamada, o X-Partner-Id da plataforma daquela operação. A chave de idempotência vale por partner: a mesma chave em outro partner não colide (veja Idempotência e reemissão).

curl -X GET https://api-sandbox.contasimples.com/credit-cards/v1/vcns/{vcnId}/reveal \
  -H "Authorization: Bearer {TOKEN}" \
  -H "User-Agent: {nome-do-seu-app}/{versao}" \
  -H "X-Partner-Id: ptn_01JQ8ZK7X4M8N2P5R6T7V8W9XY"

Janela de uso

A VCN só autoriza compras dentro da janela startDate–endDate. As duas datas são dias de calendário no horário de Brasília — exceção à regra geral de datas em UTC da API —, e "hoje" é o dia corrente em Brasília.

• A janela abre às 00:00 do startDate e fecha no fim do dia do endDate: o endDate é inclusivo.
• Sem startDate, a janela começa no dia da emissão, e o cartão já nasce utilizável.
• createdAt e updatedAt são instantes em UTC. Numa emissão entre 21h e 24h de Brasília, createdAt cai no dia seguinte ao startDate.
• A janela não é a validade física do cartão, que vem em card.expirationDate.

Fim padrão por tipo

Sem endDate no pedido, o fim é o padrão do tipo. O padrão não acompanha o startDate: se o início cair no dia do padrão ou depois, a janela fica invertida e a emissão é recusada — nesse caso, informe o endDate.

Limites das datas

Fora os casos marcados, a recusa é 400 invalid-vcn-request, sem errors[], com o motivo no message. No teto do cartão de funding, o motivo é end date must not exceed the funding card expiration: encurte a janela ou acione a Conta Simples.

Vencimento e encerramento

• A VCN vence a partir do dia seguinte ao endDate. No próprio dia do endDate ela ainda aceita atualização, e uma nova emissão na mesma chave ainda responde 409.
• Vencida, Atualizar VCN responde 409 vcn-expired: não recarregue, emita outra.
• Não existe status de vencida: uma VCN vencida continua ACTIVE. Compare o endDate com o dia de hoje em Brasília.
• Encurtar o endDate não encerra o cartão. Para encerrar, use Cancelar VCN.
• Recargas não empurram a validade, e mudar a validade não mexe no teto: para os dois, envie limit e endDate.
• O startDate de uma VCN emitida não muda.

Idempotência e reemissão

Cada tipo tem uma chave de idempotência, e ela é também o identificador que você envia:

• A resposta devolve a chave em reference, como texto, nos três tipos. No pedido, só o CUSTOM envia reference.
• A chave vale por empresa, type e plataforma integradora (o X-Partner-Id da chamada): a mesma chave em outro type ou em outro partner não colide.
• Enquanto a VCN da chave está viva (ACTIVE ou BLOCKED, dentro da janela), uma nova emissão responde 409 vcn-already-issued, sem os dados do cartão e sem o vcnId. Guarde o vcnId do 201 junto com a chave.
• No CUSTOM, esse 409 é o caminho esperado: o cartão daquela reference já existe. Recarregue-o em Atualizar VCN; cada reference nova cria um cartão novo.
• A chave fica livre depois do vencimento ou do cancelamento. Uma nova emissão com ela gera outro cartão, com PAN novo, e o vcnId anterior passa a responder 404 em todas as rotas.
• Não use dados pessoais na chave: ela é gravada e devolvida nas respostas.

Teto e recarga

• HOTEL e AERIAL: o teto é derivado do custo, amount.rate + amount.taxes + amount.fees, que precisa ser maior que zero. No HOTEL, soma-se a margem de extras quando allowExtraCharges é true: o valor de extraChargesMargin ou, sem ele, a margem padrão — hoje R$ 150,00 por diária por hóspede, sujeita a mudança. Para controlar o teto, informe extraChargesMargin.
• CUSTOM: o teto é o limit.value informado, a partir de 0.01. Só o CUSTOM é atualizável; os controles de HOTEL e AERIAL vêm da reserva.
• O teto não é saldo: o disponível é calculado pela rede do cartão (disponível = teto − consumido), e a API não devolve o consumo.

Recarga no período TOTAL

⚠️ No período TOTAL, o padrão, limit.value é o teto acumulado da janela, não um incremento. Para adicionar crédito, envie teto vigente + crédito.

Exemplo: teto 100.01 e uma nova venda de R$ 80,00 → envie 180.01. Se enviar 80.00, o teto fica abaixo do que já foi gasto, e toda nova autorização passa a ser recusada.

O teto vigente volta no 201 de Criar VCN, no 200 de Atualizar VCN e em Consultar VCN: guarde o último que receber.

Período do teto

• A conta de recarga acima só vale para TOTAL. Com MONTHLY ou DAILY, limit.value é o teto de cada mês ou dia.
• O período não interage com maxPurchaseQuantity, que conta autorizações.
• Em Atualizar VCN, spendLimitPeriod omitido mantém o período vigente, e trocar o período não zera o que já foi gasto: um cartão que passa de TOTAL para MONTHLY não ganha o mês limpo.

Recargas em paralelo

• Envie limit.expectedValue com o teto que você acredita estar vigente: a atualização só grava se ele bater.
• Se não bater — ou se outra atualização da mesma VCN gravar no meio, o que também acontece sem expectedValue e em chamadas seguidas muito próximas —, a resposta é 409 vcn-limit-conflict. Recalcule o total a partir do teto mais recente e repita. Releia o teto em Consultar VCN; a leitura pode levar alguns instantes para refletir a última atualização.

Repetir chamadas

As regras gerais de retry da API não valem igual para todos os endpoints de VCN:

Em qualquer endpoint, se o erro persistir, acione o suporte com o horário da chamada e o requestId.

Leitura logo após escrever

A leitura é eventualmente consistente.

• Logo depois da emissão, Atualizar, Revelar, Consultar e Cancelar podem responder 404 por alguns instantes: repita antes de concluir que a VCN não existe.
• Logo depois de uma atualização ou de um cancelamento, Consultar VCN pode devolver o estado anterior por alguns instantes.
• Atualizações da mesma VCN em sequência muito rápida podem receber 409 vcn-limit-conflict (veja Recargas em paralelo).

Corpo da requisição

Criar VCN

• Envie exatamente um identificador, o do seu type: hotelBooking, flightBooking ou reference. O de outro tipo é recusado com 400 bad-request-exception, e o field do erro aponta o identificador (ex.: body.reference num HOTEL).
• Dinheiro tem um campo por significado: amount é o custo da reserva (obrigatório em HOTEL e AERIAL, proibido no CUSTOM); limit é o teto (obrigatório no CUSTOM, proibido nos tipos de reserva).
• Valores monetários são decimais com até 2 casas. Mais casas → 400, sem arredondamento. A moeda é sempre BRL.
• Chaves desconhecidas são descartadas sem erro — inclusive partner: a plataforma vem só do header X-Partner-Id e nunca é lida do corpo.
• null não equivale a campo ausente: num campo opcional, é recusado com 400.
• reference é texto. Um objeto ({"id": …}) é recusado com 400.
• requestor é obrigatório: texto de 1 a 100 caracteres, com o e-mail de um usuário ou um identificador do seu sistema. Um objeto ({"name": …}) é recusado com 400.
• customFields aceita até 50 itens, com name até 50 e value até 100 caracteres: são os limites que a rede do cartão aceita. Acima deles, 400.

Atualizar VCN

• Envie Content-Type: application/json, o requestor (como em Criar VCN) e só o que quer mudar: pelo menos um entre limit, endDate, maxPurchaseQuantity e spendLimitPeriod. Corpo vazio ou só com o requestor → 400; campo não enviado não muda.
• O corpo é fechado. Qualquer outra chave é recusada com 400 bad-request-exception, e o field do erro aponta a chave recusada (ex.: body.expirationDate, body.limit.currency). Isso inclui os campos imutáveis type, reference, startDate, customFields, a moeda do limit e o nome antigo expirationDate.

Cancelar VCN

• Envie Content-Type: application/json e um corpo só com o requestor, como em Criar VCN. Sem corpo, sem requestor ou com outra chave → 400 bad-request-exception.

Formato dos erros

Todo erro dos endpoints de VCN tem code, message e requestId; errors[] vem só em bad-request-exception.

• Trate o erro pelo code. O texto do message pode mudar; o 500 responde sempre An unexpected error occurred on the server.
• bad-request-exception é recusa de formato, com uma entrada em errors[] por campo. invalid-vcn-request é recusa de regra da janela ou do teto: vem sem errors[], e o motivo está no message.
• errors[].field sempre começa pela parte da requisição: body., path. ou headers. (ex.: body.amount.rate, path.vcnId, headers.x-partner-id). Quando a recusa é do corpo inteiro — nenhum campo a mudar em Atualizar VCN —, o field é só body. Não procure amount.rate sem o prefixo.
• requestId identifica a chamada: informe-o ao suporte junto com o horário.
• vcnId inválido no path — mais de 255 caracteres, com /, \, ? ou #, ou igual a . ou .. — dá 400 bad-request-exception com field path.vcnId.

Ordem de avaliação

Quando mais de uma regra falha, o erro que chega é o da primeira na ordem:

• Criar VCN: 409 vcn-already-issued vem antes das regras de data. Uma chave viva responde 409 mesmo que as datas do pedido sejam inválidas.
• Atualizar VCN: vcn-not-updatable → vcn-not-active → vcn-expired → vcn-limit-conflict (por expectedValue) → 400 invalid-vcn-request (regras do endDate).
• Revelar dados do VCN: a posse vem antes do cancelamento. Uma VCN cancelada de outra empresa responde 404, não 409.