ℹ️ Conteúdo em atualização

Estamos revisando estes procedimentos. Pessoas técnicas podem encontrar ajustes em códigos de erro ou mapeamentos de payload; valide com os logs e o OpenAPI mais recente. Pessoas não técnicas podem continuar usando o passo a passo e acionar o time de suporte caso algo pareça diferente do descrito.

💳 App de Cartão

Este guia apresenta o passo a passo para integração com o serviço de cartões, permitindo listar cartões, consultar detalhes, gerenciar senhas e validar CVV.

Visão Geral

O serviço de cartão oferece funcionalidades para:

Cartões: Listagem de cartões, consulta de detalhes e informações do titular
Cobrança: Verificação de elegibilidade para negociação
Voucher: Geração de vouchers (cartão digital)
Senha: Criação, validação e recuperação de senha do cartão
CVV: Validação do código de segurança

URLs Base:

Produção: https://api.credsystem.com.br/cartao-app/api/v1
Homologação: https://apihml.credsystem.com.br/cartao-app/api/v1

Autenticação

Todos os endpoints requerem autenticação via Bearer Token (JWT).

Header obrigatório:

Authorization: Bearer <seu_token_jwt>

Importante

Tokens inválidos ou expirados retornarão erro 401 Unauthorized.

Gerenciamento de Cartões

1. Listar Cartões do Cliente

Lista todos os cartões vinculados ao cliente autenticado.

Endpoint: GET /cartao

Parâmetros Query (opcionais):

isTitular (boolean): true para retornar apenas cartões do titular, false para incluir adicionais

Exemplo: GET /cartao?isTitular=true

Resposta de Sucesso (200):

[
  {
    "idApp": 25,
    "nomeCartao": "KALLAN CARD",
    "nomeImpresso": "EDSON SATO",
    "bin": 960333,
    "finalCartao": "1243",
    "imagemCartao": "https://www.portaldocartao.com.br/static/assets/img_portalcartao/cartaoKallan.png",
    "idCartao": "50713621",
    "isTitular": true,
    "valorAPagar": 38.61,
    "situacaoCartao": "D",
    "tipoCobranca": "C",
    "limite": {
      "global": {
        "disponivel": 45577.47,
        "estipulado": 0,
        "utilizado": 4422.53,
        "total": 50000,
        "percentualUtilizado": 8.84506
      },
      "extra": {
        "valor": 95577.47,
        "parcela": 10
      }
    }
  }
]

Campos Principais:

idCartao: Identificador único do cartão (use para outras operações)
nomeCartao: Nome comercial do cartão
finalCartao: Últimos 4 dígitos do cartão
isTitular: Indica se é cartão titular ou adicional
situacaoCartao: Situação atual (ex: "D" = desbloqueado)
valorAPagar: Valor em aberto para pagamento
limite: Objeto contendo informações de limites

Objeto Limite:

global.disponivel: Valor disponível para uso
global.utilizado: Valor já utilizado
global.total: Limite total do cartão
global.percentualUtilizado: Percentual do limite utilizado (0-100)
extra.valor: Limite extra/emergencial disponível
extra.parcela: Número de parcelas do limite extra

Dica

Use o idCartao retornado para fazer chamadas subsequentes que requerem identificação do cartão específico.

2. Consultar Detalhes do Cartão

Retorna informações detalhadas de um cartão específico.

Endpoint: GET /cartao/detalhe/{idCartao}

Parâmetros:

idCartao (path, obrigatório): ID do cartão

Exemplo: GET /cartao/detalhe/50713621

Resposta de Sucesso (200):

{
  "titular": "EDSON SATO",
  "numeroCartao": "9603331234",
  "situacaoCartao": "D",
  "isHabilitadoCompra": true,
  "melhorDia": 15,
  "vencimento": 20,
  "nomeCartao": "KALLAN CARD",
  "imagemCartao": "https://www.portaldocartao.com.br/static/assets/img_portalcartao/cartaoKallan.png",
  "possuiSenha": true,
  "linkComprasOnline": "https://shop.exemplo.com",
  "diasEmAtraso": 0,
  "flagEmAtraso": false,
  "bin": 960333,
  "tipoCobranca": "C",
  "tipoCartao": "CREDITO",
  "cartaoVirtual": false,
  "idCartao": 50713621,
  "limites": {
    "global": {
      "disponivel": 45577.47,
      "utilizado": 4422.53,
      "total": 50000,
      "percentualUtilizado": 8.84506
    },
    "saque": {
      "disponivel": 1000.00,
      "utilizado": 0,
      "total": 1000.00,
      "percentualUtilizado": 0
    },
    "emergencial": {
      "disponivel": 5000.00,
      "utilizado": 0,
      "total": 5000.00,
      "percentualUtilizado": 0
    },
    "parcelado": {
      "disponivel": 30000.00,
      "estipulado": 30000,
      "valorMaximoCompraComJuros": 25000.00,
      "valorMaximoCompraSemJuros": 20000.00
    }
  }
}

Informações Adicionais:

melhorDia: Melhor dia para compra (para aproveitar prazo maior)
vencimento: Dia do vencimento da fatura
possuiSenha: Indica se o cartão já tem senha cadastrada
isHabilitadoCompra: Se o cartão está habilitado para compras
flagEmAtraso: Indica se há pagamentos em atraso
diasEmAtraso: Quantidade de dias em atraso

Tipos de Limite:

global: Limite total do cartão
saque: Limite disponível para saques
emergencial: Limite emergencial/extra
parcelado: Informações sobre compras parceladas

3. Consultar Cartão Titular

Retorna apenas o cartão titular do cliente (atalho para o cartão principal).

Endpoint: GET /cartao/titular

Exemplo: GET /cartao/titular

Resposta: Retorna o mesmo formato do endpoint de detalhes, mas apenas do cartão titular.

Cobrança e Negociação

Consultar Elegibilidade para Negociação

Verifica se o cliente está elegível para negociação de dívidas e retorna URL de redirecionamento quando aplicável.

Endpoint: GET /cartao/cobranca

Exemplo: GET /cartao/cobranca

Resposta de Sucesso (200):

{
  "elegivelNegociacao": false,
  "elegivelAcordoAndamento": true,
  "url": "https://www.portaldocartao.com.br/negociar-externo?token=3242342d-dsafdsa-saasdfa"
}

Campos da Resposta:

elegivelNegociacao: Cliente pode iniciar uma nova negociação
elegivelAcordoAndamento: Já existe um acordo em andamento
url: Link para portal de negociação (quando disponível)

Casos de Uso

Se elegivelNegociacao for true, exiba botão "Negociar Dívida"
Se elegivelAcordoAndamento for true, exiba "Acompanhar Acordo"
Use a url para redirecionar o cliente ao portal de negociação

Cartão Digital (Voucher)

Gerar Voucher (Cartão Digital)

Gera um voucher para uso do cartão digital/virtual.

Endpoint: POST /voucher

Body:

{
  "idCartao": "50713621"
}

Resposta de Sucesso (200):

{
  "voucher": "ABC123XYZ789",
  "dataExpiracao": "2024-12-31T23:59:59",
  "numeroCartaoVirtual": "5200****1234"
}

Voucher

O voucher é usado para habilitar o cartão digital temporariamente para compras online seguras.

Gerenciamento de Senha

1. Criar ou Alterar Senha

Cria uma nova senha ou altera a senha existente do cartão.

Endpoint: PUT /senha

Body:

{
  "idCartao": 50713621,
  "senha": "1234",
  "origem": "APP_MOBILE"
}

Resposta de Sucesso (200):

{
  "mensagem": "Senha criada com sucesso"
}

Campos do Request:

idCartao: ID do cartão
senha: Nova senha (geralmente 4 dígitos)
origem: Origem da requisição (ex: "APP_MOBILE", "APP_WEB")

Segurança

A senha deve ser numérica com 4 dígitos
Nunca armazene a senha em texto plano
Sempre use conexão segura (HTTPS)

2. Validar Senha

Valida se a senha fornecida está correta.

Endpoint: POST /senha/validar

Body:

{
  "idCartao": 50713621,
  "senha": "1234",
  "origem": "APP_MOBILE"
}

Resposta de Sucesso (200):

{
  "valida": true,
  "mensagem": "Senha válida"
}

Casos de Uso:

Validar senha antes de operações sensíveis
Confirmar identidade do usuário
Desbloquear funcionalidades do app

3. Recuperar Senha (Clarear)

Permite que o cliente recupere/visualize a senha cadastrada.

Endpoint: GET /senha/clarear

Headers:

Authorization: Bearer token
codigoCartao: Código do cartão

Exemplo:

GET /senha/clarear HTTP/1.1
Authorization: Bearer <token>
codigoCartao: 50713621

Resposta de Sucesso (200):

{
  "senha": "1234"
}

Segurança

Este endpoint deve ser usado com extremo cuidado e apenas após validação adicional de identidade (como SMS, biometria, etc.).

Validação de CVV

Validar Código de Segurança (CVV)

Valida o CVV (código de segurança) do cartão.

Endpoint: POST /cvv/valida

Body:

{
  "cvv": "123",
  "idCartao": "50713621"
}

Resposta de Sucesso (200):

{
  "valido": true,
  "mensagem": "CVV válido"
}

Casos de Uso:

Validar CVV antes de compras online
Confirmar posse física do cartão
Segurança adicional em transações

Fluxo Completo: Primeiro Uso do Cartão

Aqui está um exemplo de fluxo para o primeiro uso de um cartão:

Passo 1: Listar Cartões Disponíveis

GET /cartao?isTitular=true

Passo 2: Consultar Detalhes do Cartão

GET /cartao/detalhe/50713621

Passo 3: Criar Senha (se não houver)

PUT /senha
{
  "idCartao": 50713621,
  "senha": "1234",
  "origem": "APP_MOBILE"
}

Passo 4: Gerar Cartão Virtual (Voucher)

POST /voucher
{
  "idCartao": "50713621"
}

Passo 5: Cliente Pode Usar o Cartão! 🎉

Códigos de Resposta HTTP

Código	Status	Descrição
200	✅ Sucesso	Requisição processada com sucesso
204	∅ Sem conteúdo	Requisição bem-sucedida, mas sem dados para retornar
400	⚠️ Bad Request	Parâmetros inválidos na requisição
401	⛔ Unauthorized	Token inválido ou expirado
500	💥 Internal Error	Erro interno do servidor

Tratamento de Erros

As respostas de erro seguem o seguinte formato:

{
  "error": {
    "message": "Descrição do erro",
    "code": 400
  }
}

Exemplos de Integração

Exemplo com cURL (Listar Cartões)

curl -X 'GET' \
  'https://bff-app-cartao-hml.credsystem.com.br/cartao-app/api/v1/cartao?isTitular=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT'

Exemplo com cURL (Criar Senha)

curl -X 'PUT' \
  'https://bff-app-cartao-hml.credsystem.com.br/cartao-app/api/v1/senha' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "idCartao": 50713621,
    "senha": "1234",
    "origem": "APP_MOBILE"
  }'

Exemplo com cURL (Validar CVV)

curl -X 'POST' \
  'https://bff-app-cartao-hml.credsystem.com.br/cartao-app/api/v1/cvv/valida' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer SEU_TOKEN_JWT' \
  -H 'Content-Type: application/json' \
  -d '{
    "cvv": "123",
    "idCartao": "50713621"
  }'

Boas Práticas

Cache Inteligente: Faça cache das informações do cartão, mas revalide periodicamente
Segurança de Senha:
- Nunca armazene senhas em texto plano
- Use HTTPS em todas as requisições
- Implemente timeout de sessão
Validação Local: Valide formatos antes de enviar para a API
Feedback ao Usuário: Sempre mostre mensagens claras sobre o status das operações
Tratamento de Erros: Implemente retry com backoff exponencial para erros temporários
Logging: Registre operações importantes (sem dados sensíveis)
UX de Limites: Mostre os limites de forma visual (gráficos, barras de progresso)

Situações de Cartão

Códigos comuns para situacaoCartao:

Código	Descrição
D	Desbloqueado (ativo)
B	Bloqueado
C	Cancelado
P	Pendente

informação

Sempre consulte a situação do cartão antes de permitir operações sensíveis.

Tipos de Cobrança

Códigos para tipoCobranca:

Código	Descrição
C	Carnê
F	Fatura
R	Rotativo

Ambiente de Produção

Atenção

Certifique-se de usar a URL de produção quando o aplicativo estiver em ambiente produtivo: https://api.credsystem.com.br/cartao-app/api/v1

Suporte

Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.

Visão Geral​

Autenticação​

Gerenciamento de Cartões​

1. Listar Cartões do Cliente​

2. Consultar Detalhes do Cartão​

3. Consultar Cartão Titular​

Cobrança e Negociação​

Consultar Elegibilidade para Negociação​

Cartão Digital (Voucher)​

Gerar Voucher (Cartão Digital)​

Gerenciamento de Senha​

1. Criar ou Alterar Senha​

2. Validar Senha​

3. Recuperar Senha (Clarear)​

Validação de CVV​

Validar Código de Segurança (CVV)​

Fluxo Completo: Primeiro Uso do Cartão​

Passo 1: Listar Cartões Disponíveis​

Passo 2: Consultar Detalhes do Cartão​

Passo 3: Criar Senha (se não houver)​

Passo 4: Gerar Cartão Virtual (Voucher)​

Passo 5: Cliente Pode Usar o Cartão! 🎉​

Códigos de Resposta HTTP​

Tratamento de Erros​

Exemplos de Integração​

Exemplo com cURL (Listar Cartões)​

Exemplo com cURL (Criar Senha)​

Exemplo com cURL (Validar CVV)​

Boas Práticas​

Situações de Cartão​

Tipos de Cobrança​

Ambiente de Produção​

Suporte​

Visão Geral

Autenticação

Gerenciamento de Cartões

1. Listar Cartões do Cliente

2. Consultar Detalhes do Cartão

3. Consultar Cartão Titular

Cobrança e Negociação

Consultar Elegibilidade para Negociação

Cartão Digital (Voucher)

Gerar Voucher (Cartão Digital)

Gerenciamento de Senha

1. Criar ou Alterar Senha

2. Validar Senha

3. Recuperar Senha (Clarear)

Validação de CVV

Validar Código de Segurança (CVV)

Fluxo Completo: Primeiro Uso do Cartão

Passo 1: Listar Cartões Disponíveis

Passo 2: Consultar Detalhes do Cartão

Passo 3: Criar Senha (se não houver)

Passo 4: Gerar Cartão Virtual (Voucher)

Passo 5: Cliente Pode Usar o Cartão! 🎉

Códigos de Resposta HTTP

Tratamento de Erros

Exemplos de Integração

Exemplo com cURL (Listar Cartões)

Exemplo com cURL (Criar Senha)

Exemplo com cURL (Validar CVV)

Boas Práticas

Situações de Cartão

Tipos de Cobrança

Ambiente de Produção

Suporte