BR Consulting

BR WebService Manual de Integrao

BR WebService - Manual de Integrao

1. Objetivo
Este manual tem como objetivo apresentar as especificaes e os critrios tcnicos
necessrios para a utilizao do WebService de Integrao da BR Consulting (BR-WS).
Atravs do BR-WS poder ser realizado o envio das informaes das vendas capturadas
pelo cliente, e o recebimento das informaes processadas pelas administradoras de carto.

2. Histrico de Alteraes
Verso
1.0
1.0.1
1.0.2

Data
25/02/2014
12/03/2014
14/03/2014

Analista
Alexandre Silva
Alexandre Silva
Alexandre Silva

1.0.3

04/04/2014 Alexandre Silva

1.0.4

08/04/2014 Alexandre Silva

1.0.5

21/05/2014 Alexandre

1.0.6

22/05/2014 Alexandre

1.0.7

27/04/2015 Alexandre

1.0.8
1.0.9

07/05/2015 Alexandre
08/05/2015 Alexandre

1.0.10

20/05/2015 Alexandre

BR WebService - Manual Integrao

Descrio
Criao do Documento
Adicionar campo: numero no objeto de parcela
Mudana dos valores dos campos: bandeira e
modalidade no objeto Venda
Mudana no formato do campo data
Adio dos campos: codigoLoja e
formaCaptura no objeto de Venda
Adio dos campos: percTaxaAdministracao e
percTaxaAntecipacao no objeto de Parcela
Adio do campo: chaveVenda no objeto de
Venda
Adio do campo: chaveParcela no objeto de
Parcela
Correo do domnio do campo nsuOrigem do
objeto de parcela.
Correo do domnio dos seguintes campos do
objeto de venda:
o nrAutorizacao
o nsuOrigem
o bandeira
o modalidade
Criao dos seguintes campos no objeto de
ConsultaVenda
o dataCreditoInicial
o dataCreditoFinal
o status
o codigoEstabelecimento
Adio do status: 0 No conciliada
Criao do seguinte campo no objeto de
ConsultaVenda
o nsuAdministradora
Criao do seguinte campo no objeto de
ConsultaVenda
Pgina 1 de 12

BR Consulting
BR WebService Manual de Integrao

1.0.11
1.0.12
1.0.13

03/06/2015 Alexandre
04/06/2015 Alexandre
11/06/2015 Alexandre

1.0.14

25/06/2015 Alexandre

1.1.0

09/07/2015 Alexandre

1.1.1

15/07/2015 Alexandre

1.1.2

08/09/2015 Alexandre

1.2.0

10/09/2015 Alexandre

BR WebService - Manual Integrao

o codigoLoja
Adio da modalidade VOUCHER
Correo do formato do campo data/hora
Criao do seguinte campo no objeto de
ConsultaVenda
o nrParcela
Incluso das bandeiras
o 22 Discover
o 23 - Esplanada
o 24 - BaneseCard
Incluso das redes
o 9 - Amex
o 10 - Banesecard
o 11 Elavon
Criao do servio de excluso de venda do
cliente
Correo da lista de valores do campo
formaCaptura do objeto de Venda.
Liberao de excluso de venda de clientes,
apenas com o filtro data da venda
Adio do campo taxa de antecipao nominal no
objeto de parcela
Adio do campo vendas duplicadas no objeto de
retorno
Criao do servio de consulta de lanamento da
administradora

Pgina 2 de 12

BR Consulting
BR WebService Manual de Integrao

1. Arquitetura de Comunicao
a. Modelo Conceitual
O BR-WS disponibilizar as seguintes funcionalidades:
a)
b)
c)
d)
e)

Registro de venda do cliente

Consulta de venda do cliente
Consulta de venda da administradora
Excluso de venda do cliente
Consulta de lanamento da administradora

Existir um nico Web Service com todos os servios apresentados acima. O fluxo de
comunicao sempre iniciado pelo cliente atravs do envio de uma mensagem XML (ou
Json) ao Web Service com o pedido do servio desejado.
O pedido de servio ser atendido na mesma conexo (todos os servios sero sncronos).
O processamento do pedido do servio concludo na mesma conexo, com a devoluo
de uma mensagem XML (ou Json) contendo o retorno do processamento do servio
pedido;
O diagrama a seguir ilustra o fluxo conceitual de comunicao entre o sistema do cliente e
o BR-WS:
BR-WS

Cliente

Sistema ERP ou PDV

HTTPs

WebService

Fluxo de
Comunicao

BR WebService - Manual Integrao

Pgina 3 de 12

BR Consulting
BR WebService Manual de Integrao

b. Padro de mensagens
i. Formato de preenchimento dos campos
Formato
Data (date)

Data/Hora
(timestamp)

Valores Decimais
(double)

Valores Percentuais
(double)

Obervao
Formato: AAAA-MM-DD
AAAA = ano com 4 caracteres
MM = ms com 2 caracteres
DD = dia com 2 caracteres
Formato: AAAA-MM-DD HH:mm:ss
AAAA = ano com 4 caracteres
MM = ms com 2 caracteres
DD = dia com 2 caracteres
HH = hora com 2 caracteres (formato 24 horas)
mm = minuto com 2 caracteres
ss = segundo com 2 caracteres
Formato: 0.00
O ponto (.) s ser utilizado para separar a parte inteira da
fracionria. No se deve utilizar separador de milhar. Exemplos:
32.786,43 = 32786.43
2,00 = 2.00 ou 2
0,30 = 0.30 ou 0.3
Formato: 0.0000
Valores em percentual devem ser apresentados em sua forma
fracionria, com 5 dgitos. O ponto (.) separa a parte inteira da parte
fracionria. Exemplos:
58% = 0.58
200% = 2.0 ou 2
37,65% = 0.3725

No deve ser inserido caractere no significativo para preencher o tamanho completo do

campo, ou seja, zeros antes de nmero ou espao em branco aps cadeia de caracteres.
Campos no obrigatrios ou sem valor (null) no necessitam ser enviados.

BR WebService - Manual Integrao

Pgina 4 de 12

BR Consulting
BR WebService Manual de Integrao

2. BR WebService
a. Objetos utilizados
A seguir segue tabela com a definio dos objetos utilizados como dados. A tabela est
dividida em 4 colunas, a saber:

Objeto: tipo composto;

Campo: tipo simples;
Tipo: tipo de dados:

o
o
o
o

C: caractere;
N: nmero;

L: lista de objeto. Exemplo: Carto possui campo listaPerguntaResposta

do tipo L, logo listaPerguntaResposta uma lista com 1 ou n
ocorrncias do objeto PerguntaResposta;

D: data ou data/hora;
O: objeto. Exemplo: Objeto mensagem tem um campo cartao do Tipo
O, logo cartao um objeto Cartao;

Descrio: informaes sobre o campo;

Objeto: Venda
Campo
nsuOrigem
nsuAdministradora
nrAutorizacao
redeAdquirente
data
nrCartao
loja
codigoEstabelecimento
valor
nrParcelas
bandeira
modalidade
banco
agencia
conta
codigoLoja
formaCaptura
chaveVenda
parcelas

Tipo
C
N
C
N
D
C
C
N
N
N
N
N
N
N
N
N
C
N
L

BR WebService - Manual Integrao

Descrio
Campo chave da venda para o cliente
Nsu da venda na administradora
Nmero da autorizao da venda
Nmero da rede adquirente, conforme item 4.b
Data e hora da venda
Nmero do carto
Nome da loja
Cdigo do estabelecimento
Valor da venda
Nmero de parcelas da venda
Nmero da bandeira, conforme item 4.c
1 Dbito, 2 Crdito, 3 Voucher
Banco onde ser creditado o valor para o cliente
Agncia onde ser creditado o valor para o cliente
Conta onde ser creditado o valor para o cliente
Codigo da loja no Conciliador
Veja lista de formas de captura no item 4.e
Campo que identifica unicamente uma venda para o Conciliador
Lista de parcelas da venda

Pgina 5 de 12

BR Consulting
BR WebService Manual de Integrao
Objeto: Parcela
Campo
nsuOrigem
dataCredito
status
numero
dataPagamento
valorTaxaAdministracao
percTaxaAdministracao
valorTaxaAntecipacao
percTaxaAntecipacao
valorAjuste
valorPago
valor
chaveParcela

Tipo
C
D
N
N
D
N
N
N
N
N
N
N
N

percTaxaAntecipacaoNominal
Objeto: Lancamento
Campo
data
codigoLoja
nomeLoja
redeAdquirente
bandeira
codigoHistorico
descricaoHistorico
flagDebitoCredito
valor
codigoConciliador
banco
agencia
conta

Tipo
N
N
C
N
N
N
C
C
N
N
N
N
N

Objeto: Retorno
Campo
codigoRetorno
detalheRetorno

Tipo
C
C

codigoRequisicao
nrPaginaAtual
nrTotalPagina
vendas
vendasDuplicadas

N
N
N
L
L

lancamentos

BR WebService - Manual Integrao

Descrio
Campo chave da parcela para o cliente
Data de prevista de crdito
Cdigo do status da parcela, conforme item 4.d
Nmero da parcela
Data que o crdito foi realizado
Valor da taxa de administrao
Percentual da taxa de administrao
Valor da taxa de antecipao
Percentual da taxa de antecipao
Valor de ajuste
Valor pago
Valor da parcela
Campo que identifica unicamente uma parcela para o
Conciliador
Percentual da taxa de antecipao nominal

Descrio
Data do lanamento
Cdigo da loja no Conciliador
Nome da loja no Conciliador
Nmero da rede adquirente, conforme item 4.b
Nmero da bandeira, conforme item 4.c
Cdigo do histrico de lanamento no Conciliador
Descrio do histrico de lanamento
D Dbito, C Crdito
Valor do lanamento
Cdigo de identificao do lanamento no conciliador
Cdigo do banco que foi realizado o lanamento
Nmero da agencia que foi realizado o lanamento
Nmero da conta que foi realizado o lanamento

Descrio
Vide anexo III Tabela de cdigos de retorno
No caso da solicitao no ter sido atendida por algum erro, ser
informado neste campo maiores detalhes do problema
detectado
Nmero que identifica unicamente esta requisio
Pagina atual enviada
Nmero total de paginas
Lista de vendas (s tem retorno para consulta de venda)
Lista de venda duplicadas (esta informao no deve ser
preenchida na requisio, ela ser retornada na resposta, para o
caso do cliente, que valida repetio de venda, tentar registrar
vendas duplicadas. S preenchido na resposta do servio
registrar venda)
Lista de vendas (s tem retorno para consulta de lanamento)

Pgina 6 de 12

BR Consulting
BR WebService Manual de Integrao

Objeto: LoteVenda
Campo
nsuLote
codigoCliente
nrVendas
totalVendas
vendas

Tipo
N
N
N
N
L

Objeto: ConsultaLancamento
Campo
Tipo
dataInicial
D
dataFinal
D
valorInicial
N
valorFinal
N
codigoLoja
N
redeAdquirente
N
bandeira
N
codigoHistorico
N
flagDebitoCredito
C
codigoRequisicao
N
nrPagina

Objeto: ConsultaVenda
Campo
codigoCliente
nsuLote
nsuVenda
nrAutorizacao
codigoRequisicao

Tipo
N
N
N
N
N

nrPagina

dataVendaInicial
dataVendaFinal
dataInclusaoInicial
dataInclusaoFinal
dataPagamentoInicial
dataPagamentoFinal
dataCancelamentoInicial
dataCancelamentoFinal
dataCreditoInicial
dataCreditoFinal
status
codigoEstabelecimento
codigoLoja
nsuAdministradora
nrParcela

D
D
D
D
D
D
D
D
D
D
N
N
N
N
N

BR WebService - Manual Integrao

Descrio
Campo chave do lote de venda para o cliente
Cdigo do cliente
Nmero de vendas no lote
Valor total de vendas deste lote
Lista de venda

Descrio
Data inicial do lanamento (obrigatrio)
Data final do lanamento (obrigatrio)
Valor inicial do lanamento
Valor final do lanamento
Cdigo da loja no Conciliador
Nmero da rede adquirente, conforme item 4.b
Nmero da bandeira, conforme item 4.c
Cdigo do histrico de lanamento no Conciliador
D Dbito, C Crdito
Cdigo da requisio da consulta original (utilizado para tratar
paginao)
Nmero da pgina requerida da consulta original(utilizado para
tratar paginao)

Descrio
Cdigo do cliente
Campo chave do lote de venda para o cliente
Campo chave da venda para o cliente
Nmero da autorizao da venda
Cdigo da requisio da consulta original (utilizado para tratar
paginao)
Nmero da pgina requerida da consulta original(utilizado para
tratar paginao)
Data de venda inicial
Data de venda final
Data de incluso inicial
Data de incluso final
Data de pagamento inicial
Data de pagamento final
Data de cancelamento inicial
Data de cancelamento final
Data de crdito inicial
Data de crdito final
Situo da parcela (ver campo status do objeto parcela)
Cdigo do estabelecimento na administradora de carto
Codigo da loja no Conciliador
Nsu da administradora
Nmero da parcela

Pgina 7 de 12

BR Consulting
BR WebService Manual de Integrao

3. Servios
a. Registro de venda do cliente
Para o cliente registrar os dados de uma venda dever chamar o servio
registraVendaCliente do BR-WS passando os seguintes parmetros:
Campo
versao
loteVenda
token

Tipo
Descrio
N
Verso do BR-WS utilizado
O
XML ou Json que representa o objeto de loteVenda.
O nmero mximo de vendas por lote 100.
N
Conjunto de caracteres que autentica o cliente, esta informao
fornecida pela BR Consulting

Como resposta a solicitao enviada acima ser retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificao dos objetos
utilizados (item 4.1).

b. Consulta de venda do cliente

Para o cliente consultar a vendas j registras por ele, dever chamar o servio
consultaVendaCliente do BR-WS passando os seguintes parmetros:
Campo
versao
consultaVenda
token

Tipo
Descrio
N
Verso do BR-WS utilizado
O
XML ou Json que representa um objeto consultaVenda
N
Conjunto de caracteres que autentica o cliente, esta informao
fornecida pela BR Consulting

Como resposta a solicitao enviada acima ser retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificao dos objetos
utilizados (item 4.1).

c. Consulta de venda da administradora

Para o cliente consultar a(s) venda(s) das administradoras de carto, dever chamar o
servio consultaVendaAdm do BR-WS passando os seguintes parmetros:
Campo
versao
consultaVenda
token

Tipo
Descrio
N
Verso do BR-WS utilizado
O
XML ou Json que representa um objeto consultaVenda
N
Conjunto de caracteres que autentica o cliente, esta informao
fornecida pela BR Consulting

BR WebService - Manual Integrao

Pgina 8 de 12

BR Consulting
BR WebService Manual de Integrao
Como resposta a solicitao enviada acima ser retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificao dos objetos
utilizados (item 4.1).

d. Excluso de venda do cliente

Para o cliente excluir uma venda enviada por ele mesmo, dever chamar o servio
excluiVendaCliente do BR-WS passando os seguintes parmetros:
Campo
versao
venda

token

Tipo
Descrio
N
Verso do BR-WS utilizado
O
XML ou Json que representa um objeto venda.
O campo data obrigatrio.
Se for informado apenas o campo data, sero apagadas todas as
vendas com a data informada.
Para apagar apenas uma venda informar os seguintes campos,
alm do campo data:
nsuOrigem
valor
N
Conjunto de caracteres que autentica o cliente, esta informao
fornecida pela BR Consulting

Como resposta a solicitao enviada acima ser retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificao dos objetos
utilizados (item 4.1).

e. Consulta de lanamento da administradora

Para o cliente consultar o(s) lanamentos(s) das administradoras de carto, dever chamar o
servio consultaLancamento do BR-WS passando os seguintes parmetros:
Campo
versao
consultaLancamento
token

Tipo
Descrio
N
Verso do BR-WS utilizado
O
XML ou Json que representa um objeto consultaLancamento
N
Conjunto de caracteres que autentica o cliente, esta informao
fornecida pela BR Consulting

Como resposta a solicitao enviada acima ser retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificao dos objetos
utilizados (item 4.1).

BR WebService - Manual Integrao

Pgina 9 de 12

BR Consulting
BR WebService Manual de Integrao

4. Anexo
a. Tabela de cdigos de retorno das requisies
Cdigo
MSG_001

Tipo
Mensagem

ERR_001
ERR_002
ERR_003
ERR_004
ERR_005
ERR_006
ERR_007
ERR_008
ERR_009
ERR_999
NGC_001
NGC_002

Erro
Erro
Erro
Erro
Erro
Erro
Erro
Erro
Erro
Erro
Negcio
Negcio

NGC_003

Negcio

NGC_004
NGC_005
NGC_006
NGC_007
NGC_008

Negcio
Negcio
Negcio
Negcio
Negcio

NGC_009

Negcio

NGC_010
NGC_011
NGC_012
NGC_014

Negcio
Negcio
Negcio
Negcio

NGC_016

Negcio

NGC_017

Negcio

NGC_018

Negcio

NGC_019

Negcio

NGC_020
NGC_021

Negcio
Negcio

NGC_022

Negcio

Descrio
Resquisicao atendida com sucesso.
Erro inesperado, no momento de registrar a requisicao no
banco de dados
Erro inesperado, Tipo de entrada invalido.
Erro inesperado na validacao do token. {0}
Erro inesperado na consulta de requisicao. {0}
Erro inesperado na obtencao dos filtros originais da consulta
Erros nos filtros da requisicao original: {0}. {1}
Erro inesperado na contagem do numero de paginas
Erro inesperado na consulta de venda da administradora
Erro inesperado na consulta das parcelas da venda
Erro inesperado. {0}
Verso invlida
Token invalido
Nmero da pgina obrigatrio quando se informa o cdigo da
requisio
Um dos perodos obrigatrio: cancelamento, incluso,
pagamento, crdito ou venda
Codigo de requisicao: {0} inexistente para o cliente: {1}
O campo nrVendas eh obrigatorio
O campo totalVendas eh obrigatorio
A lista de vendas eh obrigatorio
O numero de vendas informado difere do numero de registros
da lista de vendas
O total de vendas informado difere da soma de registros da lista
de vendas
Campo data eh obrigatorio. Venda da posicao: {0}
Campo valor eh obrigatorio. Venda da posicao: {0}
Campo nrParcelas eh obrigatorio. Venda da posicao: {0}
O numero de parcelas informado difere do numero de registros
da lista de parcelas. Venda da posicao: {0}
Campo numero eh obrigatorio. Venda da posicao {0} parcela de
posicao: {1}
Campo valor eh obrigatorio. Venda da posicao: {0} parcela de
posicao: {1}
O valor da venda informado difere do valor da soma das
parcelas. Venda da posicao: {0}
O campo forma de captura deve ser igual a P (POS) ou T (TEF).
Venda da posicao: {0}
O campo Nsu de Origem obrigatrio
No foi encontrada nenhuma venda com o nsuOrigem, data e
valor passados

BR WebService - Manual Integrao

Pgina 10 de 12

BR Consulting
BR WebService Manual de Integrao

b. Lista de redes adquirentes

Cdigo
1
2
3
4
5
6
7
8
9
10
11

Descrio
Cielo
RedeCard
HiperCard
CrediShop
Losango
GETNET
LiberCrad
FortBrasil
Amex
BaneseCard
Elavon

c. Lista de bandeiras
Cdigo
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Descrio
Visa
MasterCard
HiperCard
Amex
CrediShop
Sodexo
LiberCard
GoodCard
Aura
Losango
Elo
SoroCred
Cabal
Diners
AgiPlan
FortBrasil
CredZ
CredSystem
CUP
Sicredi
BanesCard
Discover
Esplanada
BaneseCard

BR WebService - Manual Integrao

Pgina 11 de 12

BR Consulting
BR WebService Manual de Integrao

d. Lista de status da parcela

Cdigo
0
1
2
3
4
5
6
7
10
11
12
13

Descrio
No conciliada
Previsto
Confirmado
Liquidado
Cancelado
Antecipado
Cancelado Administradora
Cancelado Cliente
Ajustado
Cancelado Por Reagendamento
Suspenso/Penhorado/Retido
Liquidado Por Acelerao

e. Lista de formas de captura

i.
ii.
iii.
iv.
v.
vi.
vii.

TEF
POS
Manual
Internet
Leitor de Trilhas
URA
Arquivo
viii. Mobile

BR WebService - Manual Integrao

Pgina 12 de 12