Pular para o conteúdo principal
ℹ️ 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.

⭐ 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>
Atenção

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ço
  • contratado: 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'
Uso Prático

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ço
  • status (obrigatório): Status do opt-in (0=Inativo, 1=Ativo)
  • cliente (obrigatório): Código do cliente
  • bin (obrigatório): BIN do cartão
  • estabelecimento (obrigatório): Código do estabelecimento
  • idSistema (obrigatório): ID do sistema
  • ddd (opcional): DDD do telefone
  • telefone (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
}'
Contratado!

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ço
  • status (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
}'
Cancelamento

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 anuidade
  • valorAnuidadeBonificada: 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'
Transparência

Mostre ambos os valores ao cliente para destacar benefícios de programas de fidelidade.

Biometria

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ão
  • token: Token específico da biometria
  • url: 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"
}'
Uso Prático
  1. Gere o link
  2. Redirecione o cliente para a URL
  3. Aguarde a validação
  4. 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 dias
  • abertosAtuais: Carnês com vencimento no período atual

Campos de cada Carnê:

  • numeroContrato: Número do contrato
  • numeroCarne: Número do carnê
  • parcelasTotal: Total de parcelas
  • parcelaAtual: Parcela vigente
  • parcelaValor: Valor da parcela
  • valorComEncargos: Valor com juros/multas (se houver)
  • numeroLoja: Identificação da loja
  • isVencido: Se está vencido
  • emitirBoleto: Se permite emitir boleto
  • valorPago: Valor já pago do carnê
  • localPagamento: Onde pode ser pago
  • permitePagamento: 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 contrato
  • parcela: 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 compra
  • loja: Dados completos da loja
  • ramo: 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'
Detalhamento

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 emissor
  • tipo: 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'
Chaves Comuns
  • TERMO_CARTAO: Termos de uso do cartão
  • PRIVACIDADE: Política de privacidade
  • SEGURO: Termos do seguro
  • CASHBACK: Regulamento de cashback

Códigos de Resposta

CódigoStatusDescrição
200✅ SucessoOperação realizada com sucesso
204∅ Sem conteúdoSem dados para retornar
400⚠️ Bad RequestParâmetros inválidos ou dados incorretos
401⛔ UnauthorizedToken inválido ou expirado
500💥 Internal ErrorErro 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

TermoSignificado
Opt-inAdesão/contratação voluntária de um serviço
AnuidadeTaxa anual cobrada pela manutenção do cartão
CarnêModalidade de parcelamento com parcelas fixas
BINBank Identification Number (primeiros dígitos do cartão)
BiometriaValidação de identidade por características físicas
Limite EmergencialCré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.