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.
⭐ Private Label - Serviços Adicionais
Guia completo para serviços adicionais do Private Label: opt-in de serviços, anuidades, biometria, carnês e muito mais.
Introdução
Este serviço oferece funcionalidades específicas para aplicações Private Label, incluindo:
- 📝 Gestão de opt-in de serviços
- 💳 Consulta de anuidades
- 🔐 Autenticação biométrica
- 📋 Gerenciamento de carnês
- 🆘 Limite emergencial
- 📄 Termos e contratos
URLs Base:
- Produção:
https://api.credsystem.com.br/private-label-app/api/v1 - Homologação:
https://apihml.credsystem.com.br/private-label-app/api/v1
Autenticação
Todas as requisições precisam incluir o token de autenticação no header:
Authorization: Bearer <seu_token_jwt>
Tokens inválidos ou expirados retornarão erro 401 Unauthorized.
Opt-in de Serviços
1. Verificar Elegibilidade para Serviço
Antes de oferecer um serviço ao cliente, verifique se ele é elegível e se já possui o serviço contratado.
Endpoint: GET /optin-servico
Parâmetros Query:
serviceType(obrigatório): ID do tipo de serviço
Exemplo:
GET /private-label-app/api/v1/optin-servico?serviceType=1 HTTP/1.1
Host: bff-app-privatelabel-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json
Resposta de Sucesso (200):
{
"elegivel": true,
"contratado": false
}
Campos da Resposta:
elegivel: Se o cliente pode contratar o serviçocontratado: Se o cliente já possui o serviço ativo
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/optin-servico?serviceType=1' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
Use elegivel: true e contratado: false para exibir oferta do serviço ao cliente.
2. Contratar Serviço (Opt-in)
Realize a adesão do cliente a um serviço disponível.
Endpoint: POST /optin-servico
Body:
{
"tipoServico": 1,
"status": 1,
"cliente": 12345,
"bin": 123456,
"estabelecimento": 1,
"idSistema": 1,
"ddd": 11,
"telefone": 999999999
}
Campos do Request:
tipoServico(obrigatório): ID do tipo de serviçostatus(obrigatório): Status do opt-in (0=Inativo, 1=Ativo)cliente(obrigatório): Código do clientebin(obrigatório): BIN do cartãoestabelecimento(obrigatório): Código do estabelecimentoidSistema(obrigatório): ID do sistemaddd(opcional): DDD do telefonetelefone(opcional): Número do telefone
Resposta de Sucesso (200):
{
"statusCode": 200,
"reasonPhrase": "OK",
"httpVersion": "1.1",
"content": "Serviço contratado com sucesso"
}
Exemplo de cURL:
curl -X 'POST' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/optin-servico' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT' \
-H 'Content-Type: application/json' \
-d '{
"tipoServico": 1,
"status": 1,
"cliente": 12345,
"bin": 123456,
"estabelecimento": 1,
"idSistema": 1,
"ddd": 11,
"telefone": 999999999
}'
Após sucesso, o serviço estará ativo para o cliente.
3. Alterar Status do Serviço
Ative ou desative um serviço já contratado.
Endpoint: PUT /optin-servico
Body:
{
"tipoServico": 1,
"status": 0,
"idCashBackCampanha": 0
}
Campos do Request:
tipoServico(obrigatório): ID do serviçostatus(obrigatório): Novo status (0=Inativo, 1=Ativo)idCashBackCampanha(opcional): ID da campanha de cashback
Resposta de Sucesso (200):
{
"statusCode": 200,
"reasonPhrase": "OK",
"httpVersion": "1.1",
"content": "Status do serviço alterado com sucesso"
}
Exemplo de cURL:
curl -X 'PUT' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/optin-servico' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT' \
-H 'Content-Type: application/json' \
-d '{
"tipoServico": 1,
"status": 0
}'
Use status: 0 para desativar um serviço sem excluir o histórico.
Anuidade
4. Consultar Valores de Anuidade
Obtenha as taxas e valores de anuidade do cartão.
Endpoint: GET /anuidade/valores
Exemplo:
GET /private-label-app/api/v1/anuidade/valores HTTP/1.1
Host: bff-app-privatelabel-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json
Resposta de Sucesso (200):
{
"valorAnuidade": 5.50,
"valorAnuidadeBonificada": 1.50
}
Campos da Resposta:
valorAnuidade: Valor normal da anuidadevalorAnuidadeBonificada: Valor com desconto/bonificação
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/anuidade/valores' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
Mostre ambos os valores ao cliente para destacar benefícios de programas de fidelidade.
Biometria
5. Gerar Link de Autenticação Biométrica
Crie uma sessão única para validação de identidade por biometria.
Endpoint: POST /biometria/link
Body:
{
"consumidor": "cliente@example.com"
}
Campos do Request:
consumidor(obrigatório): E-mail ou identificador do cliente
Resposta de Sucesso (200):
{
"authorization": "exemploAuthorization",
"token": "exemploToken",
"url": "https://exemplo-url.com/biometria/sessao/abc123"
}
Campos da Resposta:
authorization: Token de autorização para a sessãotoken: Token específico da biometriaurl: Link único para realizar a captura biométrica
Exemplo de cURL:
curl -X 'POST' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/biometria/link' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT' \
-H 'Content-Type: application/json' \
-d '{
"consumidor": "cliente@example.com"
}'
- Gere o link
- Redirecione o cliente para a URL
- Aguarde a validação
- Confirme a identidade
Limite Emergencial
6. Consultar Taxa de Limite Emergencial
Veja o valor da tarifa para contratar limite emergencial.
Endpoint: GET /limite-emergencial/taxas
Exemplo:
GET /private-label-app/api/v1/limite-emergencial/taxas HTTP/1.1
Host: bff-app-privatelabel-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json
Resposta de Sucesso (200):
{
"valorTarifa": 9.90
}
Campos da Resposta:
valorTarifa: Valor cobrado pela ativação do limite emergencial
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/limite-emergencial/taxas' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
Carnês
7. Listar Carnês Abertos
Consulte carnês com vencimento próximo e atual.
Endpoint: GET /carne/abertos
Resposta de Sucesso (200):
{
"abertosProximos": [
{
"numeroContrato": "CONT001",
"numeroCarne": "CARNE001",
"parcelasTotal": 12,
"parcelaAtual": 3,
"parcelaValor": 150.50,
"valorComEncargos": 155.00,
"numeroLoja": "LOJA123",
"isVencido": false,
"emitirBoleto": true,
"valorPago": 450.00,
"localPagamento": "Loja Física",
"permitePagamento": true
}
],
"abertosAtuais": [
{
"numeroContrato": "CONT002",
"numeroCarne": "CARNE002",
"parcelasTotal": 6,
"parcelaAtual": 2,
"parcelaValor": 200.00,
"valorComEncargos": 205.00,
"numeroLoja": "LOJA456",
"isVencido": false,
"emitirBoleto": true,
"valorPago": 400.00,
"localPagamento": "Online",
"permitePagamento": true
}
]
}
Campos:
abertosProximos: Carnês com vencimento nos próximos diasabertosAtuais: Carnês com vencimento no período atual
Campos de cada Carnê:
numeroContrato: Número do contratonumeroCarne: Número do carnêparcelasTotal: Total de parcelasparcelaAtual: Parcela vigenteparcelaValor: Valor da parcelavalorComEncargos: Valor com juros/multas (se houver)numeroLoja: Identificação da lojaisVencido: Se está vencidoemitirBoleto: Se permite emitir boletovalorPago: Valor já pago do carnêlocalPagamento: Onde pode ser pagopermitePagamento: Se está disponível para pagamento
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/carne/abertos' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
8. Consultar Histórico de Carnês
Veja carnês já pagos/finalizados.
Endpoint: GET /carne/historico
Resposta de Sucesso (200):
{
"historicos": [
{
"numeroContrato": "CONT001",
"numeroCarne": "CARNE001",
"parcelasTotal": 12,
"parcelaAtual": 12,
"parcelaValor": 150.50,
"valorComEncargos": 155.00,
"numeroLoja": "LOJA123",
"isVencido": false,
"dataPagamento": {
"year": 2025,
"month": 10,
"day": 15
},
"valorPago": 1860.00
}
]
}
Campos Adicionais:
dataPagamento: Data de quitação (objeto com year, month, day)valorPago: Valor total pago
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/carne/historico' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
9. Detalhes de um Carnê Específico
Obtenha informações completas sobre um carnê incluindo dados da loja.
Endpoint: GET /carne/detalhes/{contrato}/{parcela}
Parâmetros Path:
contrato: Número do contratoparcela: Número da parcela
Exemplo:
GET /private-label-app/api/v1/carne/detalhes/123456/3 HTTP/1.1
Host: bff-app-privatelabel-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json
Resposta de Sucesso (200):
{
"compraData": "2025-01-15",
"compraHora": "14:30:00",
"compraValorTotal": 1800.00,
"isVencido": false,
"numeroCarne": "123456",
"numeroContrato": "123456",
"parcelaAtual": 3,
"parcelaValor": 150.50,
"parcelasTotal": 12,
"loja": {
"bairro": "Jardins",
"cidade": "São Paulo",
"endereco": "Rua das Flores, 123",
"id": "LOJA123",
"nome": "Loja Exemplo",
"uf": "SP"
},
"ramo": {
"id": 1,
"nome": "Departamentos"
}
}
Campos da Resposta:
compraData: Data da compra (YYYY-MM-DD)compraHora: Hora da compra (HH:mm:ss)compraValorTotal: Valor total da compraloja: Dados completos da lojaramo: Ramo de atividade da loja
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/carne/detalhes/123456/3' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
Use este endpoint para exibir informações completas quando o cliente clicar em um carnê.
Termos e Contratos
10. Consultar Termo ou Contrato
Recupere o conteúdo de termos de uso e contratos por chave.
Endpoint: GET /termos-contratos/{chave}
Parâmetros Path:
chave: Identificador único do termo/contrato
Exemplo:
GET /private-label-app/api/v1/termos-contratos/TERMO_CARTAO_001 HTTP/1.1
Host: bff-app-privatelabel-hml.credsystem.com.br
Authorization: Bearer <token>
Accept: application/json
Resposta de Sucesso (200):
{
"exclusivo": true,
"tipo": "TERMO_CARTAO",
"conteudo": "Termos e condições gerais de uso do cartão...",
"chave": "TERMO_CARTAO_001"
}
Campos da Resposta:
exclusivo: Se o termo é exclusivo para este emissortipo: Tipo do termo (TERMO_CARTAO, PRIVACIDADE, etc.)conteudo: Texto completo do termo (pode conter HTML)chave: Chave única para referência
Exemplo de cURL:
curl -X 'GET' \
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/termos-contratos/TERMO_CARTAO_001' \
-H 'accept: application/json' \
-H 'Authorization: Bearer SEU_TOKEN_JWT'
TERMO_CARTAO: Termos de uso do cartãoPRIVACIDADE: Política de privacidadeSEGURO: Termos do seguroCASHBACK: Regulamento de cashback
Códigos de Resposta
| Código | Status | Descrição |
|---|---|---|
| 200 | ✅ Sucesso | Operação realizada com sucesso |
| 204 | ∅ Sem conteúdo | Sem dados para retornar |
| 400 | ⚠️ Bad Request | Parâmetros inválidos ou dados incorretos |
| 401 | ⛔ Unauthorized | Token inválido ou expirado |
| 500 | 💥 Internal Error | Erro interno do servidor |
Tratamento de Erros
{
"error": {
"message": "Descrição do erro",
"code": 400
}
}
Fluxos de Uso
Fluxo: Contratar Serviço Adicional
1. Cliente visualiza ofertas de serviços
↓
2. Verificar Elegibilidade (GET /optin-servico?serviceType=X)
↓
3. SE elegivel=true AND contratado=false:
├─ Exibir oferta do serviço
├─ Cliente aceita contratar
├─ Contratar Serviço (POST /optin-servico)
└─ Serviço Ativo! ✅
↓
4. SE contratado=true:
└─ Mostrar "Você já possui este serviço"
Fluxo: Autenticação Biométrica
1. Necessidade de validação extra de identidade
↓
2. Gerar Link Biométrico (POST /biometria/link)
↓
3. Guardar authorization e token
↓
4. Redirecionar cliente para URL
↓
5. Cliente realiza captura biométrica
↓
6. Sistema valida e retorna para o app
↓
7. Identidade confirmada ✅
Fluxo: Gestão de Carnês
1. Cliente acessa "Meus Carnês"
↓
2. Listar Carnês Abertos (GET /carne/abertos)
↓
3. Exibir listas separadas:
├─ Vencimento Atual
└─ Vencimento Próximo
↓
4. Cliente clica em um carnê
↓
5. Buscar Detalhes (GET /carne/detalhes/{contrato}/{parcela})
↓
6. Exibir informações completas:
├─ Dados da compra
├─ Informações da loja
├─ Opções de pagamento
└─ Botão "Emitir Boleto" (se permitido)
Exemplos de Implementação
Exemplo 1: Verificar e Contratar Serviço
// Verificar elegibilidade
async function verificarElegibilidadeServico(tipoServico) {
try {
const response = await fetch(
`https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/optin-servico?serviceType=${tipoServico}`,
{
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error('Erro ao verificar elegibilidade');
}
const { elegivel, contratado } = await response.json();
if (contratado) {
alert('Você já possui este serviço!');
return false;
}
if (!elegivel) {
alert('Você não é elegível para este serviço no momento');
return false;
}
return true;
} catch (error) {
console.error('Erro:', error);
return false;
}
}
// Contratar serviço
async function contratarServico(dadosServico) {
try {
const response = await fetch(
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/optin-servico',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify(dadosServico)
}
);
if (!response.ok) {
throw new Error('Erro ao contratar serviço');
}
const resultado = await response.json();
alert(resultado.content);
return true;
} catch (error) {
console.error('Erro:', error);
alert('Não foi possível contratar o serviço');
return false;
}
}
// Fluxo completo
async function processoContratacaoServico() {
const tipoServico = 1; // ID do serviço
// Verificar elegibilidade
const podeContratar = await verificarElegibilidadeServico(tipoServico);
if (!podeContratar) {
return;
}
// Confirmar com cliente
const confirmacao = confirm('Deseja contratar este serviço?');
if (!confirmacao) {
return;
}
// Contratar
const dadosServico = {
tipoServico: tipoServico,
status: 1,
cliente: clienteId,
bin: clienteBin,
estabelecimento: 1,
idSistema: 1,
ddd: clienteDDD,
telefone: clienteTelefone
};
await contratarServico(dadosServico);
}
Exemplo 2: Exibir Carnês
// Listar carnês abertos
async function listarCarnesAbertos() {
try {
const response = await fetch(
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/carne/abertos',
{
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error('Erro ao listar carnês');
}
const { abertosProximos, abertosAtuais } = await response.json();
// Renderizar carnês atuais
renderizarCarnes('carnes-atuais', abertosAtuais, 'Vencimento Atual');
// Renderizar carnês próximos
renderizarCarnes('carnes-proximos', abertosProximos, 'Próximo Vencimento');
} catch (error) {
console.error('Erro:', error);
alert('Não foi possível carregar os carnês');
}
}
// Renderizar lista de carnês
function renderizarCarnes(containerId, carnes, titulo) {
const container = document.getElementById(containerId);
container.innerHTML = `<h3>${titulo}</h3>`;
if (carnes.length === 0) {
container.innerHTML += '<p>Nenhum carnê nesta categoria</p>';
return;
}
carnes.forEach(carne => {
const card = document.createElement('div');
card.className = 'carne-card';
card.innerHTML = `
<div class="carne-header">
<strong>Carnê ${carne.numeroCarne}</strong>
${carne.isVencido ? '<span class="badge-vencido">Vencido</span>' : ''}
</div>
<div class="carne-info">
<p>Parcela: ${carne.parcelaAtual}/${carne.parcelasTotal}</p>
<p>Valor: R$ ${carne.parcelaValor.toFixed(2)}</p>
${carne.valorComEncargos > carne.parcelaValor ?
`<p class="encargos">Com encargos: R$ ${carne.valorComEncargos.toFixed(2)}</p>` :
''}
<p>Loja: ${carne.numeroLoja}</p>
</div>
<div class="carne-actions">
<button onclick="verDetalhesCarne('${carne.numeroContrato}', ${carne.parcelaAtual})">
Ver Detalhes
</button>
${carne.emitirBoleto && carne.permitePagamento ?
'<button class="btn-boleto">Emitir Boleto</button>' :
''}
</div>
`;
container.appendChild(card);
});
}
// Ver detalhes de um carnê
async function verDetalhesCarne(contrato, parcela) {
try {
const response = await fetch(
`https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/carne/detalhes/${contrato}/${parcela}`,
{
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json'
}
}
);
if (!response.ok) {
throw new Error('Erro ao carregar detalhes');
}
const detalhes = await response.json();
// Exibir modal com detalhes
exibirModalDetalhes(detalhes);
} catch (error) {
console.error('Erro:', error);
alert('Não foi possível carregar os detalhes');
}
}
// Exibir modal de detalhes
function exibirModalDetalhes(detalhes) {
const modal = document.getElementById('modal-detalhes');
modal.innerHTML = `
<div class="modal-content">
<h2>Detalhes do Carnê</h2>
<div class="info-section">
<h3>Informações da Compra</h3>
<p><strong>Data:</strong> ${formatarData(detalhes.compraData)}</p>
<p><strong>Hora:</strong> ${detalhes.compraHora}</p>
<p><strong>Valor Total:</strong> R$ ${detalhes.compraValorTotal.toFixed(2)}</p>
</div>
<div class="info-section">
<h3>Parcelas</h3>
<p>Parcela ${detalhes.parcelaAtual} de ${detalhes.parcelasTotal}</p>
<p><strong>Valor:</strong> R$ ${detalhes.parcelaValor.toFixed(2)}</p>
</div>
<div class="info-section">
<h3>Loja</h3>
<p><strong>${detalhes.loja.nome}</strong></p>
<p>${detalhes.loja.endereco}</p>
<p>${detalhes.loja.bairro} - ${detalhes.loja.cidade}/${detalhes.loja.uf}</p>
<p><em>Ramo: ${detalhes.ramo.nome}</em></p>
</div>
<button onclick="fecharModal()">Fechar</button>
</div>
`;
modal.style.display = 'block';
}
Exemplo 3: Autenticação Biométrica
// Iniciar processo de biometria
async function iniciarBiometria(consumidor) {
try {
const response = await fetch(
'https://bff-app-privatelabel-hml.credsystem.com.br/private-label-app/api/v1/biometria/link',
{
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Accept': 'application/json',
'Content-Type': 'application/json'
},
body: JSON.stringify({ consumidor })
}
);
if (!response.ok) {
throw new Error('Erro ao gerar link de biometria');
}
const { authorization, token: bioToken, url } = await response.json();
// Guardar tokens
sessionStorage.setItem('bioAuth', authorization);
sessionStorage.setItem('bioToken', bioToken);
// Redirecionar para captura biométrica
window.location.href = url;
} catch (error) {
console.error('Erro:', error);
alert('Não foi possível iniciar a autenticação biométrica');
}
}
Glossário
| Termo | Significado |
|---|---|
| Opt-in | Adesão/contratação voluntária de um serviço |
| Anuidade | Taxa anual cobrada pela manutenção do cartão |
| Carnê | Modalidade de parcelamento com parcelas fixas |
| BIN | Bank Identification Number (primeiros dígitos do cartão) |
| Biometria | Validação de identidade por características físicas |
| Limite Emergencial | Crédito adicional temporário para emergências |
Suporte
Para dúvidas ou problemas com a integração, entre em contato com a equipe de suporte técnico.