API

Integração com Parceiros

Portal do Consumidor Positivo
Versão 1.0 – 07/2019
Sumário

Definições iniciais ............................................................................................................................ 3

Endereço de Acesso ........................................................................................................................ 4
Cadastro do Consumidor ................................................................................................................. 5
Validação de Identidade - Perguntas (KBA) .................................................................................... 7
Validação de Identidade - Respostas (KBA) .................................................................................. 10
Consulta do Relatório do Consumidor ........................................................................................... 12
Redirecionamento do Consumidor para o Portal Boa Vista ........................................................... 17
Tabelas de Erros e Status.............................................................................................................. 18
4xx .............................................................................................................................................. 18
5xx .............................................................................................................................................. 20
KBA ErrorCode ........................................................................................................................... 21
Status HTTP ............................................................................................................................... 22

2
Definições iniciais
Todos os serviços disponibilizados, recebem e retornam os conteúdos e troca de informações
em formato JSON.

Para todas as chamadas, devem ser enviados obrigatoriamente os parâmetros abaixo no

cabeçalho (header) de todas as requisições HTTP:

1. Authorization
2. PartnerID
3. X-Forwarded-For

As credenciais de autorização e acesso são diferentes para os ambientes de

desenvolvimento (sandbox) e produção, e devem ser solicitadas para a área
responsável de acessos da Boa Vista. Todas as solicitações realizadas em ambiente
de produção serão tarifadas conforme o plano disponibilizado.

Exemplo de chamada utilizando a biblioteca CURL:

curl " https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/"

-H "Authorization: Bearer <TOKEN_AUTORIZACAO>"
-H "PartnerID: <TOKEN_PARCEIRO>"
-H "X-Forwarded-For: <IP_ORIGEM_CONSUMIDOR>"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST
-d '{
"..."
}'

3
Serviços disponíveis
O fluxo e sequencia das chamadas dos serviços disponíveis para esta modalidade de
integração, deverão ser realizados conforme as necessidades e definições de planos contratados
e regras de envio e recebimento de informações do parceiro com a Boa Vista.

Os serviços abaixo estão disponíveis para todos os parceiros:

1. Cadastro do Consumidor
2. Validação de Identidade - Perguntas (KBA)
3. Validação de Identidade - Respostas (KBA)
4. Consulta do Relatório do Consumidor
5. Redirecionamento do Consumidor para o Portal Boa Vista

Endereço de Acesso
https://apiw.bvsnet.com.br:8243/parceiros/consumidor

As credenciais de acesso (Authorization e PartnerID) definem o apontamento para

os respectivos ambientes de desenvolvimento (sandbox) e produção, e devem ser solicitadas
para a área responsável de acessos da Boa Vista. Todas as solicitações realizadas em
ambiente de produção serão tarifadas conforme o plano disponibilizado.

4
Cadastro do Consumidor
Serviço para inclusão e envio de informações de consumidores relacionados com o
parceiro. As informações obrigatórias que devem ser enviadas na chamada do serviço, podem
variar de acordo com o plano acordado.

| POST |

https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/

REQUEST

curl "https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/"
-H "Authorization: Bearer af0f2ads571bxc5d261c2957a31b0db3"
-H "PartnerID: 5913299F-36A8-AEF5-9BE5-A32B7FC3EF08"
-H "X-Forwarded-For: XXX.XXX.XXX.XXX"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST
-d {
"documento": "12345678901",
"termo_aceite_boavista": "1",
"email": "[email protected]",
"data_nascimento": "01/01/1990",
"celular": "11987654321",
"nome": "NOME COMPLETO DO CONSUMIDOR",
"..."
}

Parâmetro Tipo Descrição

documento String  CPF do consumidor sem caracteres especiais.

termo_aceite_boavista String  “S” = Sim ou “N” = Não
Utilizado para identificar que o parceiro apresentou (e que o
consumidor validou e está de acordo) com termos de uso para
utilização dos serviços da Boa Vista.
email String  E-mail válido do consumidor.
celular Numeric  Número de celular (DDD + número) somente números.
data_nascimento Date Data de nascimento no formato dd/mm/aaaa.
nome String Nome completo do consumidor.
campos_adicionais String Dependendo do plano de envio e recebimento contratado,
poderão ser solicitados parâmetros adicionais na chamada e
serão encaminhados em documentação específica para o
parceiro.

() Campos obrigatórios

5
RESPONSE SUCESS (2XX CODE):

HTTP/1.1 201 Ok
{
"documento": "12345678901",
"mensagem": "Consumidor inserido com sucesso",
}

RESPONSE ERROR (4XX CODE):

HTTP/1.1 400 Bad Request

{
"erro": "prtInputError",
"mensagem": "Data de nascimento inválida ou não informada"
}

6
Validação de Identidade - Perguntas (KBA)
Faz a solicitação das perguntas do questionário para validação de identidade do
consumidor.

| GET |

https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/kba

REQUEST

curl "https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/kba"
-H "Authorization: Bearer af0f2ads571bxc5d261c2957a31b0db3"
-H "PartnerID: 5913299F-36A8-AEF5-9BE5-A32B7FC3EF08"
-H "X-Forwarded-For: XXX.XXX.XXX.XXX"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X GET

Parâmetro Tipo Descrição

documento String Número do documento (CPF) enviado.

questoes Object Bloco com as questões
DocInfo Object Informações do documento.
TicketId String Ticket de identificação utilizado para a validação das respostas.
ResultCode String Código do resultado.
ResultMessage String Mensagem gerada.
Questions Object Bloco [array] com perguntas e alternativas de respostas.
Question String Pergunta
Answers Object Bloco [array] com as respostas possíveis.

7
RESPONSE SUCESS (2XX CODE):

HTTP/1.1 200 Ok
{
"documento": "12345678901",
"questoes": {
"DocInfo": [],
"TicketId": "5a5bye25z93b9e0a9c8726bl",
"ResultCode": "0",
"ResultMessage": "Generated",
"Questions": [
{
"Question": "Qual é o nome da sua mãe?",
"Answers": [
"CLAIR DOS SANTOS",
"ROSANA EMANNUELE DIAS",
"JANE GOMES DA SILVA",
"JAMILE SOUZA TEIXEIRA" ]
},
{
"Question": "Qual o seu grau de parentesco com ETELVINA TEIXEIRA DA SILVA?",
"Answers": [
"NETO(A)",
"IRMAO(A)",
"AVO",
"MARIDO\\ESPOSA"
]
},
{
"Question": "Em qual das opções abaixo está localizada sua residência?",
"Answers": [
"VIA",
"RUA",
"AVENIDA",
"GALERIA"
]
}
]
}
}

8
RESPONSE ERROR (4XX CODE):

HTTP/1.1 400 Bad Request

{
"erro": -1,
"mensagem": "Questionnaire answers NOT validated."
}

9
Validação de Identidade - Respostas (KBA)
Envia as respostas de um questionário previamente gerado para validação.

| POST |

https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/kba

REQUEST

curl " https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/kba"

-H "Authorization: Bearer af0f2ads571bxc5d261c2957a31b0db3"
-H "PartnerID: 5913299F-36A8-AEF5-9BE5-A32B7FC3EF08"
-H "X-Forwarded-For: XXX.XXX.XXX.XXX"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X POST
-d {
"ticketId": "5a5c0abb293b9e0a9c8727b5",
"answers": [
"CLAIR DOS SANTOS",
"IRMAO(A)",
"AVENIDA"
]
}

Parâmetro Tipo Descrição

ticketId String O ticket gerado na resposta da requisição anterior (perguntas).

answers Object Array com respostas, formato [“RESP1”,”RESP2”,”RESP3”].

10
RESPONSE SUCESS (2XX CODE):

HTTP/1.1 200 OK

RESPONSE ERROR (4XX CODE):

HTTP/1.1 400 Bad Request

{
"erro": -207,
"mensagem": "Not Enought Answers."
}

11
Consulta do Relatório do Consumidor
Faz a solicitação da consulta completa do consumidor. Retornará como padrão os blocos
de Débitos, Cheques, Alertas de Documentos e o Score.

| GET |

https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/relatorio

REQUEST

curl "https://apiw.bvsnet.com.br:8243/ parceiros/consumidores/v1/{documento}/relatorio"

-H "Authorization: Bearer af0f2ads571bxc5d261c2957a31b0db3"
-H "PartnerID: 5913299F-36A8-AEF5-9BE5-A32B7FC3EF08"
-H "X-Forwarded-For: XXX.XXX.XXX.XXX"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X GET

Parâmetro Tipo Descrição

consulta_numero String Número do protocolo (identificador) da consulta na base de dados

consulta_data Date Data e hora da consulta.

Caso a consulta seja recuperada do histórico de consultas do

parceiro (conforme plano e regras de armazenamento contratadas)
será retornada a data e hora do consulta realizada originalmente.

consulta Object Bloco com informações retornadas do relatório do consumidor.

quantidade_alertas String Quantidade de alertas retornados na consulta.
quantidade_cheques String Quantidade de cheques retornados na consulta.
quantidade_debitos String Quantidade de débitos retornados na consulta.
alertas Object Bloco com a lista de alertas.
Tipo_Documento_Alerta String Código com o tipo do alerta retornado.
Descricao_Tipo_Alerta String Descrição do alerta retornado.
cheques Object Bloco com a lista de cheques.
Condicao String Código com a condição do cheque.
Tipo_Documento String Tipo do documento retornado.
debitos Object Bloco com a lista de débitos.
empresa String Empresa credora.
logradouro String Endereço da empresa credora.
data_debito String Data do débito.
data_disponibilizada String Data de disponibilização do débito para o mercado.
valor String Valor do débito.
origem String SCPC de origem.
score Object Bloco com Score.
retorno String Valor do Score.

12
RESPONSE SUCESS (2XX CODE):

HTTP/1.1 200 Ok
{
"consulta_numero": "03b2o91c85cd5fb8",
"consulta_data": "2018-01-01 01:30:49",
"consulta": {
"quantidade_alertas": "1",
"quantidade_cheques": "3",
"quantidade_debitos": "2",
"alertas": [
{
"Codigo_Base_Operadora": "SP",
"Codigo_Entidade": "00000000",
"Cidade_Entidade": "SAO PAULO",
"UF_Entidade": "SP",
"Controle": "2018012100102",
"Tipo_Documento_Alerta": "11",
"Descricao_Tipo_Alerta": "TALAO DE CHEQUES",
"Numero_Banco": "370",
"Descricao_Banco": "BANCO WESTLB BRASIL SA",
"Motivo_Alerta": "01",
"Descricao_Motivo": "ROUBO / FURTO",
"Data_Ocorrencia": "12012018",
"Boletim_Ocorrencia": "123",
"Cidade_Alerta": "SAO PAULO",
"UF_Alerta": "SP",
"Condicao_Alerta": "A",
"Data_Inclusao": "12012018",
"Hora_Inclusao": "100102",
"Response_time": "1515987035"
}
],
"cheques": [
{
"Condicao": "I",
"Tipo_Documento": "1",
"Numero_Documento": "12345678901",
"Nome": "NOME DO CONSUMIDOR",
"Banco": "389",
"Descricao_Banco": "BANCO MERCANTIL DO BRASIL SA",

13
 "Agencia": "0032",
"Motivo12": "011",
"Descricao_Alinea12": "DEV 2A APRESENTACAO",
"Data_Ultima_Ocorrencia12": "13062014",
"Motivo13": "000",
"Descricao_Alinea13": "",
"Data_Ultima_Ocorrencia13": "00000000",
"Motivo14": "000",
"Descricao_Alinea14": "",
"Data_Ultima_Ocorrencia14": "00000000",
"Motivo99": "000",
"Descricao_Alinea99": "",
"Data_Ultima_Ocorrencia99": "00000000"
},
{
"Condicao": "I",
"Tipo_Documento": "1",
"Numero_Documento": "12345678901",
"Nome": "NOME DO CONSUMIDOR",
"Banco": "756",
"Descricao_Banco": "BANCO COOPERATIVO DO BRASIL",
"Agencia": "4031",
"Motivo12": "004",
"Descricao_Alinea12": "DEV 2A APRESENTACAO",
"Data_Ultima_Ocorrencia12": "18092013",
"Motivo13": "000",
"Descricao_Alinea13": "",
"Data_Ultima_Ocorrencia13": "00000000",
"Motivo14": "000",
"Descricao_Alinea14": "",
"Data_Ultima_Ocorrencia14": "00000000",
"Motivo99": "000",
"Descricao_Alinea99": "",
"Data_Ultima_Ocorrencia99": "00000000"
},
{
"Condicao": "I",
"Tipo_Documento": "1",
"Numero_Documento": "12345678901",
"Nome": "NOME DO CONSUMIDOR",
"Banco": "237",

14
 "Descricao_Banco": "BANCO BRADESCO S.A.",
"Agencia": "1685",
"Motivo12": "002",
"Descricao_Alinea12": "DEV 2A APRESENTACAO",
"Data_Ultima_Ocorrencia12": "22072014",
"Motivo13": "000",
"Descricao_Alinea13": "",
"Data_Ultima_Ocorrencia13": "00000000",
"Motivo14": "000",
"Descricao_Alinea14": "",
"Data_Ultima_Ocorrencia14": "00000000",
"Motivo99": "000",
"Descricao_Alinea99": "",
"Data_Ultima_Ocorrencia99": "00000000"
}
],
"debitos": [
{
"empresa": "ITAU UNIBANCO S/A",
"logradouro": "PCA ALFREDO E S ARANHA, 100 - TORRE EUDORO VILLELA",
"bairro": "JABAQUARA",
"cidade": "SAO PAULO",
"uf": "SP",
"cep": "04344902",
"telefone": "11 4004-1144",
"data_debito": "20/11/2013",
"data_disponibilizada": "15/08/2021",
"valor": "000000800.00",
"origem": ""
},
{
"empresa": "RANA FORMATURAS E EVENTOS LTDA EPP",
"logradouro": "AV. RAIMUNDO P MAGALHAES, 3320",
"bairro": "PIRITUBA",
"cidade": "SAO PAULO",
"uf": "SP",
"cep": "05145200",
"telefone": "38341026",
"data_debito": "01/01/2016",
"data_disponibilizada": "15/01/2016",
"valor": "000000000.01",

15
 "origem": ""
}
],
"score": [
{
"retorno": "523"
}
]
}
}

RESPONSE ERROR (4XX CODE):

HTTP/1.1 400 Bad Request

{
"erro": "OptinKBAError",
"mensagem": "O consumidor ainda não realizou a validação de identidade"
}

16
Redirecionamento do Consumidor para o Portal Boa Vista
Este serviço tem o objetivo de informar o endereço (URL) em que os consumidores
cadastrados no parceiro deverão ser direcionados, no caso de ser necessária a ativação de conta
ou conclusão do cadastro no Portal do Consumidor Positivo.

| GET |
https://apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/portal

REQUEST

curl " apiw.bvsnet.com.br:8243/parceiros/consumidores/v1/{documento}/portal"

-H "Authorization: Bearer af0f2ads571bxc5d261c2957a31b0db3"
-H "PartnerID: 5913299F-36A8-AEF5-9BE5-A32B7FC3EF08"
-H "X-Forwarded-For: XXX.XXX.XXX.XXX"
-H "Content-Type: application/json"
-H "Accept: application/json"
-X GET

RESPONSE SUCESS (2XX CODE):

HTTP/1.1 201 OK
{
"redirect_to": "[url_redirecionamento_consumidor]",
}

RESPONSE ERROR (4XX CODE):

HTTP/1.1 400 Bad Request

{
"erro": "prtIdentidadeError",
"mensagem": "Consumidor não cadastrado anteriormente pelo parceiro"
}

17
Tabelas de Erros e Status
4xx
Code Message

IdParceiroRequerido O envio das informações de identificação do parceiro são obrigatórias (PartnerId)

DocumentoRequerido O preenchimento do campo [documento] é obrigatório.

MethodNotAllowed Requisição com method METHOD_ENVIADO não permitida. Deve ser via POST.

EmailRequerido O preenchimento do campo [email] é obrigatório.

CelularRequerido O preenchimento do campo [celular] é obrigatório.

DocumentoError Documento (CPF) inválido.

EmailError Email inválido.

DataNascimentoError Data de nascimento inválida.

CepError CEP em formato inválido - deve conter somente 8 números.

CepRequerido O preenchimento do campo [cep] é obrigatório.

EnderecoRequerido O preenchimento do campo [endereco] é obrigatório.

BairroRequerido O preenchimento do campo [bairro] é obrigatório.

CidadeRequerida O preenchimento do campo [cidade] é obrigatório.

UfRequerida O preenchimento do campo [uf] é obrigatório.

UfError UF inválida.

NumeroRgRequerido O preenchimento do campo [numero_rg] é obrigatório.

OrgaoExpedidorRequerido O preenchimento do campo [orgao_expedidor] é obrigatório.

18
Code Message

UfExpedidorRequerido O preenchimento do campo [uf_expedidor] é obrigatório.

UfExpedidorError UF do expedidor inválida.

DataExpedicaoRequerida O preenchimento do campo [data_expedicao] é obrigatório.

DataExpedicaoError Data de nascimento inválida.

TicketIdRequerido O preenchimento do campo [ticketId] é obrigatório.

AnswersRequeridas O preenchimento do campo [answers] é obrigatório.

NoAnswersError Documento (CPF) ainda não passou pelo processo de questionário.

SaldoInsuficienteError Saldo insuficiente para realizar a consulta.

NomeError Nome inválido.

NomeMaeError Nome da mãe inválido.

CelularError Número de celular inválido.

19
5xx
Code Message

InsertConsumidorError Erro ao inserir Consumidor.

QuestoesError O serviço não retornou questões.

UpdateQuestionarioError Erro ao atualizar a operação questionário no registro do consumidor.

RespostasError O serviço não confirmou o recebimento das respostas.

KbaLimitError CPF bloqueado. O CPF informado ultrapassou o limite de erros no questionário e foi
bloqueado.

AuthorizationRequestError Falha na comunicação com serviço de autorização. [MENSAGEM].

ConsultaError Consulta Indisponível no momento.

ConsultaResponseError Consulta indisponível no momento.

ConsultaAlertasError Consulta alertas indisponível no momento.

ConsultaErrorsError Erro(s) retornados na consulta.

QuestionError Erros na tabela de Questionário abaixo.

ExceptionError Erros genéricos.

20
KBA ErrorCode
Code Message

0 Questionnaire generated

1 Questionnaire answers validated

4 Second chance questionnaire answers validated

-1 Questionnaire answers NOT validated

-2 Answers not validated, but a Second Chance Questionnaire was generated.

-4 Second chance questionnaire answers NOT validated

-5 Frontend user response timeout

-100 An error occurred while building the questions

-101 Not enough information

-102 Build questionnaire timeout

-111 Access denied

-112 Insufficient input parameters

-120 Error loading domain/group configurations

-200 An error occurred while checking answers

-202 Invalid ticketIdId

-204 Questionnaire expired

-303 Input name doesn't match with official name

-308 Blocked by velocity validation

21
Code Message

-311 Blocked by TrackMe velocity

-405 [SecondChance] Not enough information

Status HTTP
Code Message

200 OK

201 Created

301 Moved Permanently

302 Found

303 See Other

304 Not Modified

307 Temporary Redirect

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

405 Method Not Allowed

406 Not Acceptable

412 Precondition Failed

22
Code Message

415 Unsupported Media Type

500 Internal Server Error

501 Not Implemented

23