> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autorizou.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Buscar Cartão

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

<ParamField path="uuid" type="string" required>
  UUID único do cartão a ser consultado
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://pay.autorizou.dev/api/v1/cards/card_def456ghi789jkl012 \
    -H "Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://pay.autorizou.dev/api/v1/cards/card_def456ghi789jkl012', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer 4eC39HqLyjWDarjtT1zdp7dc'
    }
  });

  const card = await response.json();
  console.log('Detalhes do cartão:', card);
  ```

  ```php PHP theme={null}
  <?php

  $cardId = 'card_def456ghi789jkl012';

  $curl = curl_init();
  curl_setopt_array($curl, [
      CURLOPT_URL => "https://pay.autorizou.dev/api/v1/cards/{$cardId}",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc'
      ]
  ]);

  $response = curl_exec($curl);
  $card = json_decode($response, true);
  curl_close($curl);

  echo "Cartão: " . json_encode($card, JSON_PRETTY_PRINT);
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

```json theme={null}
{
  "id": "3f7d2a91-8c4e-4b6f-9a2d-5e8c1f4b7a30",
  "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"
}
```

<Note>
  **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).
</Note>

## 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                      |

<Info>
  **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.
</Info>

## Códigos de Erro

<AccordionGroup>
  <Accordion title="404 - Not Found" icon="circle-xmark">
    Cartão não encontrado

    ```json theme={null}
    {
      "message": "Cartão não encontrado"
    }
    ```

    **Possíveis causas:**

    * UUID não existe
    * Cartão pertence a outro merchant
    * UUID malformado
  </Accordion>

  <Accordion title="400 - Bad Request" icon="circle-xmark">
    UUID inválido

    ```json theme={null}
    {
      "error": {
        "code": "invalid_uuid",
        "message": "UUID do cartão é inválido"
      }
    }
    ```
  </Accordion>

  <Accordion title="403 - Forbidden" icon="circle-xmark">
    Acesso negado ao cartão

    ```json theme={null}
    {
      "error": {
        "code": "access_denied",
        "message": "Acesso negado a este cartão"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Interpretando os Dados

### Verificação de Validade

```javascript theme={null}
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

```javascript theme={null}
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

```javascript theme={null}
async function validarCartaoParaPagamento(cardId) {
  try {
    const response = await fetch(`https://pay.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

```javascript theme={null}
function formatCardForDisplay(card) {
  const brandLabels = {
    visa: 'Visa',
    mastercard: 'Mastercard',
    elo: 'Elo',
    hipercard: 'Hipercard'
  };

  return {
    id: card.id,
    display: `${brandLabels[card.brand] || 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

<Tip>
  **Cache sugerido:** Dados de cartão mudam raramente. Considere cache com TTL de 1 hora.
</Tip>

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

## Segurança

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

<Note>
  **Auditoria:** Consultas a cartões são logadas para fins de auditoria e segurança.
</Note>

## Próximos Passos

Após consultar um cartão:

1. [Processar pagamento com o cartão](/api-reference/charges/orders/create-order)
2. [Criar novo cartão](/api-reference/cards/create-card)
3. [Solicitar Network Token (Visa/Mastercard)](/api-reference/cards/enroll-network-token)