Buscar Cartão - Autorizou

Este endpoint permite recuperar as informações de um cartão específico usando seu UUID. Retorna apenas dados seguros (sem informações sensíveis).

Casos de Uso

🔍 Validar cartão antes de processar pagamento
📊 Exibir detalhes do cartão na interface
🕐 Confirmar validade do cartão

Parâmetros de URL

uuid

string

required

UUID único do cartão a ser consultado

Exemplo de Requisição

curl -X GET https://zeus-sandbox.autorizou.dev/api/v1/cards/card_def456ghi789jkl012 \
  -H "Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc"

Resposta de Sucesso

{
  "id": "card_def456ghi789jkl012",
  "customer_id": "345f8bdc-397f-4f25-a564-48bb771b8123",
  "holder": "JOAO SILVA",
  "brand": "visa",
  "first_6": "411111",
  "last_4": "1111",
  "exp_month": "12",
  "exp_year": "30",
  "created_at": "15/01/2024 10:35:00",
  "updated_at": "20/01/2024 14:30:00"
}

Dados Sensíveis: Por motivos de segurança, o endpoint nunca retorna o número completo do cartão ou o CVV. Os dados sensíveis são armazenados de forma tokenizada no VGS (Very Good Security).

Detalhes da Resposta

Campo	Tipo	Descrição
`id`	string	UUID único do cartão
`customer_id`	string	UUID do cliente proprietário
`holder`	string	Nome do portador do cartão
`brand`	string	Bandeira do cartão (visa, mastercard, elo, etc)
`first_6`	string	Primeiros 6 dígitos do cartão (BIN)
`last_4`	string	Últimos 4 dígitos do cartão
`exp_month`	string	Mês de expiração (MM)
`exp_year`	string	Ano de expiração (YY) - apenas 2 dígitos
`created_at`	string	Data de criação no formato DD/MM/YYYY HH:mm:ss
`updated_at`	string	Data da última atualização

BIN (Bank Identification Number): Os primeiros 6 dígitos (first_6) identificam o banco emissor e o tipo de cartão. São úteis para validações e análise de fraude.

Códigos de Erro

404 - Not Found

Cartão não encontrado

{
  "error": {
    "code": "card_not_found",
    "message": "Cartão não encontrado"
  }
}

Possíveis causas:

UUID não existe
Cartão pertence a outro merchant
UUID malformado

400 - Bad Request

UUID inválido

{
  "error": {
    "code": "invalid_uuid",
    "message": "UUID do cartão é inválido"
  }
}

403 - Forbidden

Acesso negado ao cartão

{
  "error": {
    "code": "access_denied",
    "message": "Acesso negado a este cartão"
  }
}

Interpretando os Dados

Verificação de Validade

function isCardExpired(card) {
  const now = new Date();
  const expiry = new Date(
    2000 + parseInt(card.exp_year), 
    parseInt(card.exp_month) - 1,
    1
  );
  
  return expiry < now;
}

// Uso
const card = await buscarCartao('card_...');
if (isCardExpired(card)) {
  console.log('Cartão expirado');
}

Verificação de Bandeira

function getBrandInfo(card) {
  const brandNames = {
    visa: 'Visa',
    mastercard: 'Mastercard',
    elo: 'Elo',
    hipercard: 'Hipercard',
    diners: 'Diners Club',
    discover: 'Discover',
    jcb: 'JCB',
    amex: 'American Express'
  };

  return {
    brand: card.brand,
    displayName: brandNames[card.brand] || card.brand.toUpperCase(),
    supportsNetworkToken: ['visa', 'mastercard'].includes(card.brand)
  };
}

Casos de Uso Práticos

Validação Pré-Pagamento

async function validarCartaoParaPagamento(cardId) {
  try {
    const response = await fetch(`https://zeus-sandbox.autorizou.dev/api/v1/cards/${cardId}`, {
      headers: { 'Authorization': 'Bearer ...' }
    });

    if (!response.ok) {
      throw new Error('Cartão não encontrado');
    }

    const card = await response.json();

    // Verificar se está expirado
    if (isCardExpired(card)) {
      throw new Error('Cartão expirado');
    }

    return {
      valid: true,
      card: card
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message
    };
  }
}

Interface de Gerenciamento

function formatCardForDisplay(card) {
  const brandIcons = {
    visa: '💳',
    mastercard: '💳',
    elo: '💳',
    hipercard: '💳'
  };

  return {
    id: card.id,
    display: `${brandIcons[card.brand] || '💳'} **** ${card.last_4}`,
    brand: card.brand.toUpperCase(),
    holder: card.holder,
    expires: `${card.exp_month}/${card.exp_year}`,
    isExpired: isCardExpired(card)
  };
}

Considerações de Performance

Cache sugerido: Dados de cartão mudam raramente. Considere cache com TTL de 1 hora.

Batch requests: Se precisar consultar múltiplos cartões, considere usar o endpoint de listagem de cartões do cliente.

Segurança

Dados sensíveis: Este endpoint NUNCA retorna dados sensíveis como número completo do cartão ou CVV.

Auditoria: Consultas a cartões são logadas para fins de auditoria e segurança.

Próximos Passos

Após consultar um cartão:

​Casos de Uso

​Parâmetros de URL

​Exemplo de Requisição

​Resposta de Sucesso

​Detalhes da Resposta

​Códigos de Erro

​Interpretando os Dados

​Verificação de Validade

​Verificação de Bandeira

​Casos de Uso Práticos

​Validação Pré-Pagamento

​Interface de Gerenciamento

​Considerações de Performance

​Segurança

​Próximos Passos

Casos de Uso

Parâmetros de URL

Exemplo de Requisição

Resposta de Sucesso

Detalhes da Resposta

Códigos de Erro

Interpretando os Dados

Verificação de Validade

Verificação de Bandeira

Casos de Uso Práticos

Validação Pré-Pagamento

Interface de Gerenciamento

Considerações de Performance

Segurança

Próximos Passos