👤 API de Clientes Lojista

Este guia apresenta o passo a passo para integração com o serviço de consulta de informações de clientes em estabelecimentos lojistas, incluindo dados cadastrais, cartões e portadores adicionais.

🎯 Visão Geral

A API de Clientes Lojista permite que você:

• 📋 Consulte dados cadastrais completos de clientes
• 💳 Obtenha informações de cartões (limites, situação, vencimentos)
• 📱 Acesse dados de contato (telefones e e-mails)
• 🏠 Visualize endereços cadastrados
• 👥 Identifique portadores adicionais vinculados ao cartão

URLs Base:

• Homologação: https://apihml.credsystem.com.br/servicos-lojista/api/v1
• Produção: https://api.credsystem.com.br/servicos-lojista/api/v1

📚 Recursos Adicionais

• 🔧 Guia de Troubleshooting - Solução de problemas e erros comuns
• 📖 Especificação OpenAPI — Referência técnica completa (schemas, tipos, exemplos)

---

🔐 Autenticação

Esta API utiliza Oracle IDCS com o fluxo Client Credentials (servidor para servidor).

Todos os endpoints requerem autenticação via Bearer Token (JWT) no header:

Authorization: Bearer <seu_token_jwt>

Propriedade	Valor
Sistema	Oracle IDCS
Fluxo OAuth2	Client Credentials
Tipo	Servidor para Servidor (sem usuário)
Token	Access Token (JWT)

Atenção

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

🔑 Como obter o token?

Veja o Passo 2 — Entender os Sistemas e o Passo 3 — Exemplos em 7 linguagens para gerar seu Bearer Token.

---

📚 Endpoint Disponível

1️⃣ Consultar Dados Cadastrais do Cliente

Retorna todas as informações cadastrais de um cliente, incluindo dados pessoais, contatos, endereços, informações do cartão e portadores adicionais.

Endpoint: GET /clientes

Parâmetros de header:

• Authorization (string, obrigatório) – Token de autorização válido
• cpf (string, opcional) – CPF do cliente (11 dígitos numéricos)
• cartao (string, opcional) – Número completo do cartão (16 dígitos numéricos)

Importante

Pelo menos um dos parâmetros deve ser informado: cpf OU cartao OU ambos.

Boas práticas

• Valide o CPF e/ou número do cartão antes de enviar a requisição
• Armazene o traceId retornado para rastreamento de problemas
• Quando informar CPF e cartão juntos, certifique-se que o cartão pertence ao CPF fornecido
• Para maior precisão, envie ambos os parâmetros quando disponíveis

Exemplos de requisição:

cURL

# Consulta com CPF e Cartão
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "accept: */*" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpf: 25296540000" \
  -H "cartao: 9604201327474511"

# Consulta apenas com CPF
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "accept: */*" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cpf: 25296540000"

# Consulta apenas com Cartão
curl -X GET "https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes" \
  -H "accept: */*" \
  -H "Authorization: Bearer SEU_TOKEN_JWT" \
  -H "cartao: 9604201327474511"

JavaScript

const API_BASE = 'https://apihml.credsystem.com.br/servicos-lojista/api/v1';
const TOKEN = 'SEU_TOKEN_JWT';

async function consultarCliente(cpf = null, cartao = null) {
  if (!cpf && !cartao) {
    throw new Error('Informe pelo menos CPF ou Cartão');
  }

  const headers = {
    'accept': '*/*',
    'Authorization': `Bearer ${TOKEN}`
  };

  if (cpf) headers['cpf'] = cpf;
  if (cartao) headers['cartao'] = cartao;

  const response = await fetch(`${API_BASE}/clientes`, {
    method: 'GET',
    headers: headers
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`Erro ${response.status}: ${error.detalhe}`);
  }

  const data = await response.json();
  console.log('✅ Consulta realizada:', data.mensagem);
  return data;
}

// Exemplos de uso:
// Com CPF e Cartão
consultarCliente('25296540000', '9604201327474511')
  .then(result => console.log('Cliente:', result.dados.nome))
  .catch(err => console.error('❌ Erro:', err.message));

// Apenas com CPF
consultarCliente('25296540000')
  .then(result => console.log('Cliente:', result.dados.nome))
  .catch(err => console.error('❌ Erro:', err.message));

// Apenas com Cartão
consultarCliente(null, '9604201327474511')
  .then(result => console.log('Cliente:', result.dados.nome))
  .catch(err => console.error('❌ Erro:', err.message));

Python

import requests

API_BASE = 'https://apihml.credsystem.com.br/servicos-lojista/api/v1'
TOKEN = 'SEU_TOKEN_JWT'

def consultar_cliente(cpf=None, cartao=None):
    """Consulta dados cadastrais do cliente
    
    Args:
        cpf: CPF do cliente (opcional)
        cartao: Número do cartão (opcional)
        
    Nota: Pelo menos um dos parâmetros deve ser informado
    """
    if not cpf and not cartao:
        raise ValueError('Informe pelo menos CPF ou Cartão')
    
    headers = {
        'accept': '*/*',
        'Authorization': f'Bearer {TOKEN}'
    }
    
    if cpf:
        headers['cpf'] = cpf
    if cartao:
        headers['cartao'] = cartao
    
    response = requests.get(
        f'{API_BASE}/clientes',
        headers=headers,
        timeout=15
    )
    
    response.raise_for_status()
    dados = response.json()
    print(f'✅ Consulta realizada: {dados.get("mensagem")}')
    return dados

# Exemplos de uso:
try:
    # Com CPF e Cartão
    resultado = consultar_cliente(cpf='25296540000', cartao='9604201327474511')
    print(f'Cliente: {resultado["dados"]["nome"]}')
    print(f'Limite disponível: R$ {resultado["dados"]["cartao"]["limiteDisponivel"]:.2f}')
    
    # Apenas com CPF
    resultado = consultar_cliente(cpf='25296540000')
    print(f'Cliente: {resultado["dados"]["nome"]}')
    
    # Apenas com Cartão
    resultado = consultar_cliente(cartao='9604201327474511')
    print(f'Cliente: {resultado["dados"]["nome"]}')
    
except requests.HTTPError as e:
    print(f'❌ Erro HTTP {e.response.status_code}: {e.response.json().get("detalhe")}')
except ValueError as e:
    print(f'❌ Erro: {e}')

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class ConsultaCliente {
    private static final String API_BASE = 
        "https://apihml.credsystem.com.br/servicos-lojista/api/v1";
    private static final String TOKEN = "SEU_TOKEN_JWT";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        // Exemplo 1: Com CPF e Cartão
        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
            .uri(URI.create(API_BASE + "/clientes"))
            .header("accept", "*/*")
            .header("Authorization", "Bearer " + TOKEN)
            .header("cpf", "25296540000")
            .header("cartao", "9604201327474511")
            .GET();
        
        // Exemplo 2: Apenas com CPF (comente a linha do cartão)
        // .header("cpf", "25296540000")
        
        // Exemplo 3: Apenas com Cartão (comente a linha do CPF)
        // .header("cartao", "9604201327474511")
        
        HttpRequest request = requestBuilder.build();

        HttpResponse<String> response = client.send(
            request,
            HttpResponse.BodyHandlers.ofString()
        );

        if (response.statusCode() == 200) {
            System.out.println("✅ Consulta realizada com sucesso");
            System.out.println(response.body());
        } else {
            System.err.println("❌ Erro: " + response.statusCode());
            System.err.println(response.body());
        }
    }
}

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;

public class ConsultaCliente
{
    private const string API_BASE = 
        "https://apihml.credsystem.com.br/servicos-lojista/api/v1";
    private const string TOKEN = "SEU_TOKEN_JWT";

    public static async Task Main()
    {
        using var client = new HttpClient();
        
        var request = new HttpRequestMessage(HttpMethod.Get, $"{API_BASE}/clientes");
        request.Headers.Add("accept", "*/*");
        request.Headers.Add("Authorization", $"Bearer {TOKEN}");
        
        // Envie pelo menos um dos parâmetros abaixo:
        request.Headers.Add("cpf", "25296540000");           // Opcional
        request.Headers.Add("cartao", "9604201327474511");   // Opcional
        
        // Exemplos de uso:
        // Apenas CPF: comente a linha do cartão
        // Apenas Cartão: comente a linha do CPF
        // Ambos: mantenha as duas linhas

        var response = await client.SendAsync(request);

        if (response.IsSuccessStatusCode)
        {
            Console.WriteLine("✅ Consulta realizada com sucesso");
            Console.WriteLine(await response.Content.ReadAsStringAsync());
        }
        else
        {
            Console.WriteLine($"❌ Erro HTTP {(int)response.StatusCode}");
            Console.WriteLine(await response.Content.ReadAsStringAsync());
        }
    }
}

PHP

<?php

// Exemplo com CPF e Cartão
$headers = [
    'accept: */*',
    'Authorization: Bearer SEU_TOKEN_JWT',
    'cpf: 25296540000',           // Opcional
    'cartao: 9604201327474511'     // Opcional
];

// Envie pelo menos um: cpf OU cartao OU ambos
// Exemplo apenas com CPF:
// $headers = ['accept: */*', 'Authorization: Bearer SEU_TOKEN_JWT', 'cpf: 25296540000'];

// Exemplo apenas com Cartão:
// $headers = ['accept: */*', 'Authorization: Bearer SEU_TOKEN_JWT', 'cartao: 9604201327474511'];

$ch = curl_init('https://apihml.credsystem.com.br/servicos-lojista/api/v1/clientes');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    echo "✅ Consulta realizada com sucesso:\n";
    $dados = json_decode($response, true);
    echo "Cliente: " . $dados['dados']['nome'] . "\n";
    if (isset($dados['dados']['cartao']['limiteDisponivel'])) {
        echo "Limite disponível: R$ " . number_format($dados['dados']['cartao']['limiteDisponivel'], 2, ',', '.') . "\n";
    }
} else {
    echo "❌ Erro HTTP {$httpCode}:\n";
    echo $response . "\n";
}

Go

package main

import (
    "fmt"
    "io"
    "net/http"
)

const (
    API_BASE = "https://apihml.credsystem.com.br/servicos-lojista/api/v1"
    TOKEN    = "SEU_TOKEN_JWT"
)

func main() {
    req, _ := http.NewRequest("GET", API_BASE+"/clientes", nil)
    req.Header.Set("accept", "*/*")
    req.Header.Set("Authorization", "Bearer "+TOKEN)
    
    // Envie pelo menos um dos parâmetros abaixo (cpf OU cartao OU ambos):
    req.Header.Set("cpf", "25296540000")           // Opcional
    req.Header.Set("cartao", "9604201327474511")   // Opcional
    
    // Exemplos:
    // Apenas CPF: comente a linha do cartão
    // Apenas Cartão: comente a linha do CPF
    // Ambos: mantenha as duas linhas

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("❌ Erro na requisição:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    
    if resp.StatusCode == 200 {
        fmt.Println("✅ Consulta realizada com sucesso")
        fmt.Println(string(body))
    } else {
        fmt.Printf("❌ Erro HTTP %d\n", resp.StatusCode)
        fmt.Println(string(body))
    }
}

Exemplo de resposta (200 OK):

{
  "status": 200,
  "mensagem": "Consulta realizada com sucesso.",
  "dados": {
    "codigoCliente": 234032511,
    "nome": "JOÃO DA SILVA SANTOS",
    "cpf": "25296540000",
    "rg": "1032374942",
    "sexo": "M",
    "estadoCivil": "1",
    "nascimento": "1942-01-31T00:00:00.000Z",
    "email": "joao.silva@email.com",
    "faturaEmail": false,
    "telefones": [
      {
        "codigoPais": 55,
        "ddd": "51",
        "numero": "917445886",
        "tipoTelefone": "CELULAR"
      }
    ],
    "enderecos": [
      {
        "endereco": "RUA DAS FLORES",
        "numero": "123",
        "complemento": "CASA",
        "bairro": "GUAJUVIRAS",
        "cidade": "CANOAS",
        "estado": "RS",
        "cep": "92440546"
      }
    ],
    "cartao": {
      "bin": "960420",
      "finalCartao": 4511,
      "situacao": "DESBLOQUEADO POR EMISSAO",
      "cartaoAdicional": "false",
      "diaVencimento": 10,
      "melhorDiaCompra": 28,
      "limiteCartao": 900.00,
      "limiteDisponivel": 900.00,
      "valorOverLimit": 900.00,
      "parcelasOverLimit": 12
    },
    "adicionais": [
      {
        "nome": "ANA SILVA SANTOS",
        "situacao": "DESBLOQUEADO POR EMISSAO"
      }
    ],
    "emissor": {
      "codigoEmissor": 1,
      "nomeEmissor": "CREDSYSTEM"
    }
  }
}

Precisa de mais detalhes?

Consulte o 🔧 Guia de Troubleshooting para informações detalhadas sobre cada erro, exemplos práticos e soluções.

---

💡 Dicas e Boas Práticas

✅ Recomendações

1. Envie pelo menos um parâmetro - Informe CPF, cartão ou ambos para identificar o cliente
2. Prefira enviar ambos quando disponíveis - CPF + cartão resulta em consulta mais precisa
3. Valide os dados antes de enviar - Verifique CPF e número do cartão localmente antes de fazer a requisição
4. Armazene o traceId - Use para rastrear problemas com o suporte técnico
5. Implemente retry com backoff - Em caso de erro 503, tente novamente após alguns segundos
6. Cache de tokens - Evite gerar novos tokens a cada requisição
7. Valide formato do CPF - Aceite apenas 11 dígitos numéricos (quando informado)
8. Trate o código 204 - Sem conteúdo não significa erro

❌ Evite

1. ❌ Não exponha o token de autenticação no frontend
2. ❌ Não ignore os códigos de status HTTP
3. ❌ Não envie CPF ou cartão com formatação (pontos, traços)
4. ❌ Não faça requisições sem pelo menos um parâmetro de identificação (CPF ou cartão)
5. ❌ Não faça requisições excessivas desnecessárias
6. ❌ Não armazene dados sensíveis sem criptografia

---

🆘 Suporte

Contato Técnico

• Email: suporte.tecnico@credsystem.com.br
• Horário: Segunda a Sexta, 8h às 18h (BRT)

Em Caso de Erro

1. Anote o traceId retornado no erro
2. Capture a requisição completa (sem dados sensíveis)
3. Descreva o comportamento esperado vs. obtido
4. Envie para o email de suporte com assunto: [API Clientes v1] - Descrição do Problema