Portadores

É o primeiro passo na jornada para transformar seu cliente em um portador de cartão private label. Para isso, a API Portadores oferece os seguintes serviços para gerenciamento de portadores de cartão:

Gerenciamento das informações cadastrais da pessoa portadora do cartão.

Histórico e gerenciamento de produtos obtidos.

Bloqueios e desbloqueios.

Contas associadas à pessoa titular.

Cadastro e alteração de senhas.

Ciclos de fatura.

Gerenciamento de dependentes.

Figura 1. Diagrama geral da comunicação da API Portadores com outros serviços

Autenticação e segurança

A API Portadores utiliza OAuth 2 como protocolo de segurança junto de um Json Web Token (JWT). Para saber mais detalhes, confira a documentação de autenticação.

Endpoints

Todos os endpoints da API Portadores utilizam URL base /api/v1/portadores/.

Cadastro de contas

Endpoints para cadastro das contas de pessoas físicas e jurídicas.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/contas/pf`	Cadastra uma conta para Pessoa Física
`POST`	`/api/v1/portadores/contas/pj`	Cadastra uma conta para Pessoa Jurídica

Gestão de portadores

Endpoints para gestão dos portadores do seu cartão, incluindo informações cadastrais, ciclos de fatura, limites, bloqueio e desbloqueio e tipo de cartões.

Informações sobre portadores

Utilize este endpoint para visualizar todos os clientes que possuem seu cartão private label através dos seus identificadores, CPF ou CNPJ.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}`	Lista todos os portadores cadastrados na base de dados
`GET`	`/api/v1/portadores/{idPortador}/informacoes`	Lista as informações do portador a partir do seu identificador
`GET`	`/api/v1/portadores/contas`	Lista as contas associadas a um CPF ou a um CNPJ
`GET`	`/api/v1/portadores/rg`	Lista as contas associadas a uma Pessoa Física através do RG
`GET`	`/api/v1/portadores/completo/cpf`	Lista todas as informações de um portador através do CPF
`GET`	`/api/v1/portadores/simplificado/cpf`	Lista as principais informações do portador a partir do CPF
`GET`	`/api/v1/portadores/nomes`	Lista as contas associadas a um portador através do seu nome
`GET`	`/api/v1/portadores/cnpj`	Lista as contas associadas a um CNPJ

Alteração de dados

Utilize este endpoint para atualizar os dados do portador, seja pessoa física ou pessoa jurídica.

Tipo	Endpoint	Documentação
`PATCH`	`/api/v1/portadores/{idPortador}`	Altera os dados do portador

Informações em lote

Utilize este endpoint para visualizar informações sobre um lote específico de portadores.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/lote`	Lista informações sobre vários portadores simultaneamente

Limites de crédito do cartão

O limite de crédito do cartão é estabelecido a partir das suas regras de negócio. Utilize este endpoint para alterar os limites de um portador.

Tipo	Endpoint	Documentação
`PATCH`	`/api/v1/portadores/{idPortador}/limites`	Altera os limites de crédito de um portador

Ciclos de fatura

Utilize este endpoint para consultar as informações do ciclo de fatura de um portador.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}/ciclo`	Consulte o ciclo de fatura do portador

Produtos

O portador pode adquirir diferentes produtos, de acordo com o catálogo do seu negócio. Utilize este endpoint para alterar o vínculo entre o portador e o seu produto.

Tipo	Endpoint	Documentação
`PATCH`	`/api/v1/portadores/produto`	Altera o produto vinculado a um portador

Bloqueio e desbloqueio de um portador

De acordo com as condições de bloqueio e desbloqueio existentes no seu negócio, o portador pode ser bloqueado ou desbloqueado. Utilize o respectivo endpoint para isso.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/bloqueios`	Bloqueia um portador
`POST`	`/api/v1/portadores/desbloqueios`	Desbloqueia um portador

Vipagem

Alguns cartões private label podem se tornar bandeirados, a depender do seu negócio. Para isso, utilize este endpoint.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/{idPortador}/vipagem`	Altera a classificação do cartão

Gestão de dependentes

Endpoints para cadastro e visualização das pessoas dependentes de uma pessoa titular.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/{idPortador}/dependentes`	Cadastra dependentes à um portador titular
`GET`	`/api/v1/portadores/{idPortador}/dependentes`	Lista as pessoas dependentes através do identificador do titular
`GET`	`/api/v1/portadores/dependentes/cpf`	Lista as pessoas adicionais através do CPF do titular

Gestão de senhas

Endpoints para alteração de senha e confirmação de SMS via número de telefone.

Alteração de senha

Utilize este endpoint para alterar a senha de um portador de cartão a partir da senha antiga. Por ser uma informação sensível, observe sempre a segurança do procedimento.

Tipo	Endpoint	Documentação
`PATCH`	`/api/v1/portadores/{idPortador}/senha`	Altera a senha do portador usando a senha anterior

Envio de senha por SMS

O portador do cartão pode solicitar, via SAC, a alteração da sua senha. Utilize este endpoint para enviar a nova senha para o portador através de SMS. Por ser uma informação sensível, observe sempre a segurança do procedimento.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/{idPortador}/senhas/sms`	Envia a senha do portador via SMS

Visualização de histórico

Endpoints para visualização de histórico do portador, de seus limites e de suas inadimplências.

Histórico do portador

Utilize este endpoint para visualizar o histórico de eventos de um portador num determinado período de tempo.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}/historico`	Lista o histórico do portador

Limites

Utilize este endpoint para visualizar o histórico de alterações de limite do cartão de um portador num determinado período de tempo.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}/limites/historico`	Lista o histórico de limites do portador

Inadimplências

Utilize este endpoint para visualizar o histórico de inadimplências do portador num determinado período de tempo.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}/inadimplencias`	Lista o histórico de inadimplências do portador

Ocorrências

Utilize este endpoint para visualizar o histórico de ocorrências (atraso de faturas, bloqueios e desbloqueios, atraso de pagamentos, etc) na conta de um portador num determinado período de tempo.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/{idPortador}/ocorrencias`	Lista as ocorrências da conta de um portador num determinado período

Gestão de telefones

Gestão de telefones de portadores

Cadastre, remova e visualize os números de telefone de um portador.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/{idPortador}/telefones`	Cadastra telefones para um portador
`GET`	`/api/v1/portadores/{idPortador}/telefones`	Lista os telefones cadastrados para um portador
`DELETE`	`/api/v1/portadores/{idPortador}/telefones/{idTelefone}`	Deleta telefones associados a um portador

Habilitação de SMS

Utilize este endpoint para habilitar o envio de informações ao portador via SMS.

Tipo	Endpoint	Documentação
`POST`	`/api/v1/portadores/{idPortador}/telefones/recebe-sms`	Confirma o telefone para recebimento de SMS

Informações da base de dados

Endpoints para visualização os tipos de informações cadastrais presentes na sua base de dados.

Bloqueios

Utilize este endpoint para visualizar todos os tipos de bloqueios cadastrados na sua base de dados.

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/bloqueios/tipos`	Lista os tipos de bloqueio aplicados pelo emissor

Escolaridade

Utilize este endpoint para visualizar todas os níveis de escolaridade cadastrados na sua base de dados:

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/escolaridade`	Lista as escolaridades cadastradas na base do emissor

Ocupações

Utilize este endpoint para visualizar todas as ocupações cadastradas na sua base de dados:

Tipo	Endpoint	Documentação
`GET`	`/api/v1/portadores/ocupacoes`	Lista as ocupações cadastradas na base do emissor

Casos de uso

Transformando um cliente em portador de cartão

Utilize o endpoint de cadastro de pessoa física para transformar um cliente pessoa física em um portador do seu cartão:

Exemplo de request body com as informações para cadastro:

{
  "nome": "José da Silva",
  "cpf": "45678920300",
  "dataNascimento": "1980-05-17",
  "rg": "999999999",
  "orgaoEmissor": "SSPPB",
  "renda": 2100,
  "sexo": "MASCULINO",
  "nomeMae": "Maria da Silva",
  "idProfissao": 2,
  "enderecoResidencial": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB"
  },
  "enderecoComercial": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "empresa": "Empresa 2",
    "departamento": "Pesquisa e Inovação",
    "cnpj": "99999999000199"
  },
  "enderecoAlternativo": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "tipo": "R"
  }
  },
  "adicionais": [
    {
      "nome": "Maria Souza",
      "cpf": "98765432101",
      "rg": "987654321",
      "dataNascimento": "1980-02-16",
      "sexo": "FEMININO",
      "grauParentesco": "OUTROS",
      "nomePersonalizado": "Mari Souza"
    }
  ],
  "referencias": [
    {
      "nome": "Maria Aparecida dos Santos",
      "grauParentesco": "FILHO",
      "telefone": {
        "tipo": "RESIDENCIAL",
        "ramal": "4020",
        "area": "83",
        "telefone": "999999999",
        "receberSMS": false,
        "faturaDigital": false
      }
    }
  ],
  "idLoja": 15,
  "limiteRotativo": 2000,
  "ocupacao": "OUTROS",
  "nacionalidade": "Brasileiro",
  "telefones": [
    {
      "tipo": "RESIDENCIAL",
      "ramal": "4020",
      "area": "83",
      "telefone": "999999999",
      "receberSMS": false,
      "faturaDigital": false
    }
  ],
  "idProduto": 0
}

O response body do endpoint apontando o sucesso da operação de cadastro:

201 Created 
{
   "contaCartao": 111111,
   "cartaoMascarado": "0000XXXXXXXX0000",
   "numeroManual": "CA-123456789=",
   "nomeCartao": "NOME PORTADOR FICTICIO",
   "diaVencimento": 16,
   "dataValidade": "2024-10-01"
}

Obtendo informações sobre o portador de cartão pelo seu identificador

Uma vez que o cliente já foi cadastrado na sua base de dados, é possível visualizar as informações pelo endpoint de listagem de informação do portador GET /api/v1/portadores/{idPortador} usando o idPortador.

Exemplo de response body:

{
 "id": 2001,
 "nome": "CONTA NUMERO 13053",
 "rg": "7687287",
 "cpf": "63450321072",
 "cartao": "string",
 "email": "[email protected]",
 "numeroCartaoTruncado": "string",
 "clienteDataNascimento": "1970-01-01",
 "rendas": [
   {
     "id": 44,
     "valor": 788,
     "comprovada": "S",
     "idPessoa": 13053,
     "principal": "string",
     "origem": "string"
   }
 ],
 "statusCliente": "string",
 "descricaoStatusCliente": "string",
 "statusAnalise": "string",
 "contratoImpresso": "string",
 "estanoCobranca": "string",
 "ultimoMotivoBloqueioCliente": "string",
 "extratoClienteResponse": {
   "limite": 0,
   "saldoDisponivel": 0,
   "saldoReservado": 0,
   "saldoParceladoDisp": 0,
   "limiteParcelado": 0,
   "devedorTotal": 0,
   "utilizaLimiteExtra": true,
   "valorLimiteExtra": 0,
   "limiteExtraTotal": 0,
   "saldoDisponivelExtra": 0,
   "valorFaturaFechada": 0,
   "clienteEmBloqueioJuridico": true
 },
 "valorLancamentosFuturos": 0,
 "pontuacaoFidelidadeResponse": {
   "idCliente": 0,
   "valorPontuacao": 0,
   "dataReferencia": "2023-04-24",
   "descricaoPrograma": "string"
 },
 "statusFaturaDigital": "string",
 "boletos": [
   {
     "id": 0,
     "quantidadesRegistros": 0,
     "ordemRegistro": 0,
     "codigoBoleto": 0,
     "valorTotal": 0,
     "valorJuros": 0,
     "valorPagamentosEfetuados": 0
   }
 ],
 "faturaFechada": {
   "id": 0,
   "dataVencimento": "2023-04-24",
   "valorTotal": 0,
   "somaPagamentos": 0,
   "valorMinimoRenegociacao": 0,
   "valorMinimoRotativo": 0,
   "valorPagamentoMinimo": 0,
   "valorPrestacoesParceladas": 0,
   "possuiPagamentoMinimo": true,
   "hashFatura": "string"
 },
 "faturaFutura": {
   "dataVencimento": "2023-04-24",
   "valorTotal": 0
 },
 "statusCartao": "string",
 "melhorDiaCompra": 0,
 "senhaExpirada": true,
 "ciclo": {
   "id": 0,
   "diaCorte": 0,
   "diaVencimento": 0,
   "descricao": "string",
   "ativo": "string",
   "corteUltimoDiaMes": "string",
   "diasCarencia": 0,
   "descricaoContaBancariaCicloAtual": "string",
   "descricaoContaBancariaProximoCiclo": "string"
 },
 "dependentes": [
   {
     "id": 0,
     "nome": "string",
     "cpf": "string",
     "sexo": "string",
     "nascimento": "2023-04-24",
     "grauParentesco": 0,
     "statusCartao": "string"
   }
 ],
 "dataFechamentoProxFatura": "2023-04-24",
 "produto": {
   "id": 0,
   "descricao": "string",
   "isProdutoDigital": "string",
   "isProdutoBandeirado": "string",
   "encargos": {
     "cobrarMulta": true,
     "multa": 0,
     "regraCalculoMulta": "string",
     "ignorarMultaAnterior": true,
     "ignorarSaldoRolado": true,
     "mora": 0,
     "regraCalculoMora": "string",
     "jurosRotativo": 0,
     "realizarEstornoJurosPagamento": true
   },
   "limiteExtra": {
     "percentualPadrao": 0,
     "valorPadrao": 0,
     "habilitarClientesNovos": true
   },
   "overlimit": {
     "percentualSobreUso": 0,
     "permitePercentualSobreUso": true,
     "taxaSobreUso": 0,
     "permiteTaxaSobreUso": true,
     "permiteRepetirMesmoCiclo": true
   }
 },
 "dataCadastro": "2023-04-24",
 "taxas": [
   {
     "descricao": "string",
     "valorContratado": 0,
     "desconto": 0,
     "dataFimDesconto": "2023-04-24",
     "dataFimDoCarencia": "2023-04-24",
     "numeroCobrancas": 0,
     "natureza": "string"
   }
 ],
 "estaEmPerda": true,
 "numeroCartaoCriptografado": "string",
 "idCartao": 0,
 "permiteAcessoApp": true,
 "dataEmissaoRG": "2023-04-24",
 "estaEmAtraso": true,
 "orgaoEmissorRG": "string",
 "unidadeFederativaRG": "string",
 "totalTentativasValidacaoCartao": 0,
 "enderecoResidencial": {
   "logradouro": "string",
   "complemento": "string",
   "numero": "string",
   "bairro": "string",
   "cep": "string",
   "uf": "string",
   "cidade": "string"
 },
 "inibirEnvioFaturaGrafica": true,
 "enderecoComercial": {
   "logradouro": "string",
   "complemento": "string",
   "numero": "string",
   "bairro": "string",
   "cep": "string",
   "uf": "string",
   "cidade": "string",
   "empresa": "string",
   "departamento": "string",
   "cnpj": "string"
 },
 "enderecoAlternativo": {
   "logradouro": "string",
   "complemento": "string",
   "numero": "string",
   "bairro": "string",
   "cep": "string",
   "uf": "string",
   "cidade": "string",
   "tipo": "string"
 },
 "transicaoBandeira": "string",
 "utilizaOverLimitPersonalizado": true,
 "diasAtrasoTotal": 0,
 "diasProvisionamento": 0,
 "produtoTransicaoBandeira": {
   "id": "string",
   "descricao": "string",
   "isProdutoDigital": "string",
   "isProdutoBandeirado": "string",
   "encargos": {
     "cobrarMulta": true,
     "multa": 0,
     "regraCalculoMulta": "string",
     "ignorarMultaAnterior": true,
     "ignorarSaldoRolado": true,
     "mora": 0,
     "regraCalculoMora": "string",
     "jurosRotativo": 0,
     "realizarEstornoJurosPagamento": true
   },
   "limiteExtra": {
     "percentualPadrao": 0,
     "valorPadrao": 0,
     "habilitarClientesNovos": true
   },
   "overlimit": {
     "percentualSobreUso": 0,
     "permitePercentualSobreUso": true,
     "taxaSobreUso": 0,
     "permiteTaxaSobreUso": true,
     "permiteRepetirMesmoCiclo": true
   }
 }
}

Atualizando dados do portador

Quando houver a necessidade de alterar alguma informação do portador de cartão, o endpoint para alteração de dados do portador PATCH /api/v1/portadores/{idPortador}, através do idPortador, faz essa requisição através do request body:

Exemplo de request body incluindo os dados a serem alterados:

{
  "nome": "João da Silva",
  "nomeSocial": "João Gomes",
  "email": "[email protected]",
  "nacionalidade": "BRASILEIRA",
  "cidadeNatal": "SÃO PAULO",
  "estadoNatal": "SP",
  "enderecoResidencial": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "tempoMoradiaAnos": 3,
    "tempoMoradiaMeses": 11
  },
  "enderecoComercial": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "empresa": "Empresa 2",
    "departamento": "Pesquisa e Inovação",
    "cnpj": "22130511000160"
  },
  "enderecoAlternativo": {
    "numero": "4020",
    "cep": "58070000",
    "complemento": "Ap 301",
    "logradouro": "Av. Presidente Epitácio Pessoa",
    "bairro": "Lapa",
    "localidade": "João Pessoa",
    "uf": "PB",
    "tipo": "R"
  },
  "sexo": "MASCULINO",
  "nomePai": "José da Silva",
  "nomeMae": "Maria da Silva",
  "idMoradia": 1,
  "idEscolaridade": 1,
  "idOcupacao": 1,
  "renda": {
    "id": 52256,
    "valor": 150.5,
    "comprovada": true
  },
  "estadoCivil": "SOLTEIRO",
  "rg": {
    "rg": "3040312",
    "dataEmissao": "2002-05-16",
    "orgaoEmissor": "SSP",
    "unidadeFederativa": "PB"
  },
  "conjuge": {
    "nome": "Maria Aparecida dos Santos",
    "sexo": "FEMININO",
    "dataNascimento": "1992-10-25",
    "nomeEmpresa": "Empresa 1",
    "idProfissao": 5,
    "telefone": {
      "tipo": "RESIDENCIAL",
      "ramal": "4020",
      "area": "83",
      "telefone": "999999999",
      "receberSMS": false,
      "faturaDigital": false
    },
    "cpf": "81227381417",
    "escolaridade": "MEDIO_COMPLETO",
    "rg": {
      "rg": "3040312",
      "dataEmissao": "2002-05-16",
      "orgaoEmissor": "SSP",
      "unidadeFederativa": "PB"
    },
    "salario": 2000
  },f
  "pep": {
    "cpf": "41827755970",
    "nome": "string",
    "justificativa": "String"
  },
  "estrangeiro": {
    "paisOrigem": "Canadá",
    "documentoPaisOrigem": "SSN - Social Security Number"
  },
  "idProfissao": 1,
  "dataAdmissaoProfissao": "1974-12-01",
  "quantidadeAnosProfissao": 18,
  "portadorNecessidadesVisuais": false,
  "inibirEnvioFaturaGrafica": false,
  "dataNascimento": "1992-10-25"
}

Exemplo de response body onde a alteração dos dados do portador funcionou:


{
200 OK
}

Obtendo informações sobre pessoas dependentes

Através do idPortador no endpoint de listagem de informação de pessoas dependentesGET /api/v1/portadores/{idPortador}/dependentesé possível visualizar as informações das pessoas dependentes associadas à uma pessoa portadora de cartão:

Exemplo de response body:


{
[
 {
   "id": 9999,
   "idClienteTitularAssociado": 99,
   "nome": "DEPENDENTE TESTE",
   "nomeSocial": "DEPENDENTE SOCIAL",
   "cpf": "99999999999",
   "dataNascimento": "1994-03-02",
   "sexo": "M",
   "idGrauParentesco": 3,
   "nomeMae": "MAE TESTE",
   "telefone": "83999999999",
   "areaTelefone": "83",
   "numeroTelefone": "999999999",
   "persisted": true,
   "status": "A"
 }
]
}

Os endpoints irão retornar os dados que podem ser acessados de acordo com suas credenciais de autenticação. Para mais informações, visite a página de autenticação.

Após o cliente se tornar um portador de cartão, a API Cartões será responsável pela emissão e gestão do cartão. Leia mais sobre a API Cartões aqui.

Serviços relacionados

API Cartões

API Gestão de contas

Materiais relacionados

Como testar endpoints através do Tote

Interpretando os códigos de resposta

Diretrizes básicas do Horizon

Autenticação e segurança#

Endpoints#

Informações sobre portadores#

Alteração de dados#

Informações em lote#

Limites de crédito do cartão#

Ciclos de fatura#

Produtos#

Bloqueio e desbloqueio de um portador#

Vipagem#

Alteração de senha#

Envio de senha por SMS#

Histórico do portador#

Limites#

Inadimplências#

Ocorrências#

Gestão de telefones de portadores#

Habilitação de SMS#

Bloqueios#

Escolaridade#

Ocupações#

Casos de uso#

Serviços relacionados#

Materiais relacionados#