Cartões - Consultar

#Visão Geral

Este endpoint permite consultar informações detalhadas sobre um cartão específico, identificado pelo seu ID único. Os dados retornados incluem informações parciais do cartão (por segurança), detalhes sobre o estado do cartão, e metadados associados.

#Precauções

• Segurança: Apenas dados parciais do cartão são retornados (primeiros e últimos dígitos), nunca o número completo.
• Autenticação: Certifique-se de que o usuário tem permissão para acessar os dados do cartão especificado.
• ID do Cartão: O ID do cartão deve ser válido e existir no sistema.

#Descrição

O endpoint Consultar Cartão permite obter todas as informações disponíveis sobre um cartão específico cadastrado no sistema, utilizando seu identificador único.

#Requisição

GET /v1/cards/{cardId}

#Parâmetros da Requisição

#Resposta - 200 OK

Se a requisição for bem-sucedida, um objeto JSON com detalhes do cartão solicitado é retornado.

#Exemplo de Resposta

{
  "id": "card_01hqzvabc",
  "holderName": "João Silva",
  "brand": "Visa",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "expirationMonth": "12",
  "expirationYear": "2030",
  "primary": true,
  "active": true,
  "valid": true,
  "verified": true,
  "associated": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc",
      "method": "GET",
      "description": "Read a card."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the card."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "GET",
      "description": "List all cards."
    }
  }
}

#Atributos da Resposta

#Respostas de Erro

Todas as respostas de erro seguem o envelope { "error": { status, statusCode, category, code, message, resource, details?, params? } }.

#400 Bad Request - Formato de ID Inválido

Retornado quando o cardId não tem o prefixo card_.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "code": "validation",
    "message": "Validation errors occurred.",
    "resource": "card",
    "params": [
      { "cardId": "must be a valid card_ id" }
    ]
  }
}

#404 Not Found - Cartão não encontrado

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "code": "cardIdNotFound",
    "message": "Card ID not found.",
    "resource": "card",
    "details": "The card ID was not found. Please check the card ID and try again."
  }
}

#409 Conflict - Cartão expirado

Retornado quando o cartão existe mas já está marcado como expirado.

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "client",
    "code": "cardExpired",
    "message": "Card expired",
    "resource": "card",
    "details": "The provided card has expired. Please use a valid card."
  }
}

#Casos de Uso

1. Exibição de Detalhes do Cartão: Mostrar informações do cartão na interface do cliente
2. Verificação de Status: Verificar se um cartão está ativo, válido ou marcado como primário
3. Confirmação Antes do Pagamento: Exibir informações mascaradas do cartão para confirmação antes de efetuar uma transação
4. Validação Antes de Operações: Verificar a validade e o estado do cartão antes de operações críticas

#Melhores Práticas

1. Caching Limitado: Implemente cache com tempo de expiração curto para reduzir chamadas repetidas ao API
2. Exibição Segura: Sempre exiba apenas informações mascaradas dos cartões na interface do usuário
3. Verificações Regulares: Verifique periodicamente a validade dos cartões armazenados para notificar clientes sobre cartões prestes a expirar
4. Tratamento de Erros: Implemente tratamento adequado para os diferentes cenários de erro
5. Verificação de Permissões: Confirme que o usuário atual tem permissão para acessar as informações do cartão solicitado

#Integração com Outros Endpoints

• Use Listar Cartões para obter todos os cartões de um cliente
• Cartões são imutáveis: para alterar dados, exclua o cartão e cadastre um novo
• Use Excluir Cartão para remover um cartão que não será mais utilizado