💳 Cartão do Cliente

📋 Visão Geral

O cartão é um dos principais meios de pagamento em plataformas de e-commerce.

Durante o processo de compra, os dados do cartão são coletados e enviados diretamente a um gateway de pagamento. Nesse fluxo, apenas informações não sensíveis são armazenadas no banco de dados — nunca o número completo do cartão ou o código de segurança.

Os endpoints desta seção são utilizados principalmente nas telas de Minha Conta e Checkout, sendo operações totalmente controladas pelo cliente autenticado. O acesso é baseado no token de autenticação — não é necessário informar o ID do cliente na URL.

🔄 Entidades Envolvidas

As seguintes entidades participam do fluxo:

Cliente

O titular dos cartões cadastrados, identificado pelo token de autenticação. Toda consulta e operação é automaticamente filtrada pelo cliente do token.

Opção de Pagamento

Representa a instituição ou gateway ao qual o cartão foi vinculado. Cada cartão registrado carrega uma referência à opção de pagamento correspondente (paymentOptionId).

🗂️ Estrutura do Cartão

O objeto de cartão retornado pelos endpoints contém as seguintes informações:

• id — identificador único do cartão cadastrado
• paymentOptionId — ID da opção de pagamento (instituição/gateway) à qual o cartão está vinculado
• firstSix — primeiros seis dígitos do número do cartão
• lastFour — últimos quatro dígitos do número do cartão
• flag — bandeira do cartão (por exemplo: "visa", "master")
• main — indica se este é o cartão principal do cliente (true ou false)
• createdAt — data e hora de cadastro do cartão

📌 Notas e Considerações

• Nenhuma informação sensível de cartão é armazenada pela API — o número completo, o CVV e os dados de validade são transmitidos ao gateway e nunca persistidos.
• Não se deve solicitar ou tentar acessar dados completos de cartão dos clientes.
• A plataforma atua em conformidade com a Lei Geral de Proteção de Dados (LGPD), e qualquer tentativa de manipulação indevida dessas informações pode resultar em penalidades legais.
• A segurança e a privacidade dos dados financeiros são tratadas como prioridade máxima 🔐.

💳 Listagem de Cartões do Cliente

📄 Descrição

Endpoint responsável por retornar todos os cartões cadastrados do cliente atual.

O resultado é paginado e suporta filtragem por campos como id, paymentOptionId, flag, main e createdAt, além de ordenação pelos mesmos campos.

A utilização requer autenticação via CustomerAuth — o ID do cliente é identificado automaticamente pelo token de autenticação, não sendo necessário informá-lo na requisição.

📋 Parâmetros de Query

🏷️ Headers Obrigatórios

🔍 Campos de Condição Disponíveis

🔃 Campos de Ordenação Disponíveis

💡 Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/cards' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json'

💡 Exemplo com Filtros

1curl --request GET \
2  --url '{{MAIN_URL}}/customer/cards?limit=10&offset=0&condition[conditions][0][field]=flag&condition[conditions][0][value]=Visa&condition[conditions][0][operator]==&order[0][field]=createdAt&order[0][order]=desc' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 123,
7        "paymentOptionId": 123,
8        "firstSix": "123456",
9        "lastFour": "1234",
10        "flag": "Visa",
11        "main": false,
12        "createdAt": "2025-04-30 13:08:35"
13      }
14    ],
15    "pagination": {
16      "limit": 10,
17      "offset": 0,
18      "pages": 16,
19      "registers": 156
20    }
21  }
22}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.

💳 Cadastrar cartão do cliente

📋 Descrição

Endpoint responsável por cadastrar um cartão do cliente, utilizado principalmente nos fluxos de Checkout e Minha Conta 💳.

O cadastro permite que o cliente associe um cartão para uso em futuras compras, seguindo os padrões de segurança exigidos pelo gateway de pagamento.

IMPORTANTE 🔐: nenhuma informação sensível de cartão é armazenada pela API.

Não solicite e não tente acessar dados completos de cartão dos clientes.

A plataforma atua em conformidade com a Lei Geral de Proteção de Dados (LGPD), e qualquer tentativa de manipulação indevida dessas informações poderá resultar em penalidades.

🔧 Parâmetros de Query

Headers Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/customer/cards \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Juvenal Souza",
7    "document": "12345678911",
8    "number": "4111111111111111",
9    "cvv": "123",
10    "month": "09",
11    "year": "2033",
12    "main": true
13  }'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": {
4    "id": 5,
5    "paymentOptionId": 0,
6    "firstSix": "411111",
7    "lastFour": "1111",
8    "flag": "master",
9    "main": true,
10    "createdAt": "2025-05-16 20:41:08"
11  }
12}

⚠️ Possíveis Erros

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

🗑️ Exclusão do cartão do cliente

📄 Descrição

Endpoint responsável por excluir permanentemente um cartão cadastrado do cliente autenticado.

A operação remove o registro do cartão do banco de dados local. Caso o cartão excluído seja o cartão principal do cliente, o sistema promove automaticamente o cartão mais recente como novo principal, sem necessidade de ação adicional.

A utilização requer autenticação via CustomerAuth — o ID do cliente é identificado automaticamente pelo token de autenticação. O cardId informado deve pertencer ao cliente autenticado; caso contrário, o erro UAPPI_STORE_CUSTOMER_CARD_NOT_FOUND é retornado.

🔐 Permissão

• CustomerAuth — autenticação do cliente via token JWT

📝 Parâmetros

🏷️ Headers Obrigatórios

🔗 Parâmetros de URL

💡 Exemplo de Requisição

1curl --request DELETE \
2  --url '{{MAIN_URL}}/customer/cards/42' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

HTTP Status: 200 OK

1{
2  "status": true,
3  "data": true
4}

⚠️ Possíveis Erros

> Os cenários abaixo representam os principais erros que podem ocorrer neste endpoint, servindo como referência para entendimento e tratamento das falhas.