manual de integração - brwebservice - versão 1.2.0
Post on 08-Dec-2015
236 Views
Preview:
DESCRIPTION
TRANSCRIPT
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 1 de 12
BR WebService - Manual de Integração
1. Objetivo
Este manual tem como objetivo apresentar as especificações e os critérios técnicos
necessários para a utilização do WebService de Integração da BR Consulting (BR-WS).
Através do BR-WS poderá ser realizado o envio das informações das vendas capturadas
pelo cliente, e o recebimento das informações processadas pelas administradoras de cartão.
2. Histórico de Alterações
Versão Data Analista Descrição
1.0 25/02/2014 Alexandre Silva Criação do Documento
1.0.1 12/03/2014 Alexandre Silva Adicionar campo: “numero” no objeto de parcela
1.0.2 14/03/2014 Alexandre Silva Mudança dos valores dos campos: “bandeira” e “modalidade” no objeto Venda
1.0.3 04/04/2014 Alexandre Silva Mudança no formato do campo data
Adição dos campos: “codigoLoja” e “formaCaptura” no objeto de Venda
1.0.4 08/04/2014 Alexandre Silva Adição dos campos: “percTaxaAdministracao” e “percTaxaAntecipacao” no objeto de Parcela
1.0.5 21/05/2014 Alexandre Adição do campo: “chaveVenda” no objeto de Venda
Adição do campo: “chaveParcela” no objeto de Parcela
1.0.6 22/05/2014 Alexandre Correção do domínio do campo “nsuOrigem” do objeto de parcela.
Correção do domínio dos seguintes campos do objeto de venda:
o nrAutorizacao o nsuOrigem o bandeira o modalidade
1.0.7 27/04/2015 Alexandre Criação dos seguintes campos no objeto de ConsultaVenda
o dataCreditoInicial o dataCreditoFinal o status o codigoEstabelecimento
1.0.8 07/05/2015 Alexandre Adição do status: 0 – Não conciliada
1.0.9 08/05/2015 Alexandre Criação do seguinte campo no objeto de ConsultaVenda
o nsuAdministradora
1.0.10 20/05/2015 Alexandre Criação do seguinte campo no objeto de ConsultaVenda
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 2 de 12
o codigoLoja
1.0.11 03/06/2015 Alexandre Adição da modalidade VOUCHER
1.0.12 04/06/2015 Alexandre Correção do formato do campo data/hora
1.0.13 11/06/2015 Alexandre Criação do seguinte campo no objeto de ConsultaVenda
o nrParcela
1.0.14 25/06/2015 Alexandre Inclusão das bandeiras o 22 – Discover o 23 - Esplanada o 24 - BaneseCard
Inclusão das redes o 9 - Amex o 10 - Banesecard o 11 – Elavon
1.1.0 09/07/2015 Alexandre Criação do serviço de exclusão de venda do cliente
1.1.1 15/07/2015 Alexandre Correção da lista de valores do campo formaCaptura do objeto de Venda.
1.1.2 08/09/2015 Alexandre Liberação de exclusão de venda de clientes, apenas com o filtro data da venda
Adição do campo taxa de antecipação nominal no objeto de parcela
Adição do campo vendas duplicadas no objeto de retorno
1.2.0 10/09/2015 Alexandre Criação do serviço de consulta de lançamento da administradora
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 3 de 12
1. Arquitetura de Comunicação
a. Modelo Conceitual
O BR-WS disponibilizará as seguintes funcionalidades:
a) Registro de venda do cliente
b) Consulta de venda do cliente
c) Consulta de venda da administradora
d) Exclusão de venda do cliente
e) Consulta de lançamento da administradora
Existirá um único Web Service com todos os serviços apresentados acima. O fluxo de comunicação é sempre iniciado pelo cliente através do envio de uma mensagem XML (ou Json) ao Web Service com o pedido do serviço desejado. O pedido de serviço será atendido na mesma conexão (todos os serviços serão síncronos). O processamento do pedido do serviço é concluído na mesma conexão, com a devolução de uma mensagem XML (ou Json) contendo o retorno do processamento do serviço pedido; O diagrama a seguir ilustra o fluxo conceitual de comunicação entre o sistema do cliente e o BR-WS:
Cliente
Sistema ERP ou PDV
Fluxo de
Comunicação
HTTPs
BR-WS
WebService
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 4 de 12
b. Padrão de mensagens
i. Formato de preenchimento dos campos
Formato Obervação
Data (date) Formato: AAAA-MM-DD AAAA = ano com 4 caracteres MM = mês com 2 caracteres DD = dia com 2 caracteres
Data/Hora (timestamp)
Formato: AAAA-MM-DD HH:mm:ss AAAA = ano com 4 caracteres MM = mês 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
Valores Decimais (double)
Formato: 0.00 O ponto (.) só será utilizado para separar a parte inteira da fracionária. Não 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
Valores Percentuais (double)
Formato: 0.0000 Valores em percentual devem ser apresentados em sua forma fracionária, com 5 dígitos. O ponto (.) separa a parte inteira da parte fracionária. Exemplos: 58% = 0.58 200% = 2.0 ou 2 37,65% = 0.3725
Não deve ser inserido caractere não significativo para preencher o tamanho completo do
campo, ou seja, zeros antes de número ou espaço em branco após cadeia de caracteres.
Campos não obrigatórios ou sem valor (null) não necessitam ser enviados.
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 5 de 12
2. BR WebService
a. Objetos utilizados
A seguir segue tabela com a definição 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 C: caractere; o N: número; o D: data ou data/hora; o O: objeto. Exemplo: Objeto mensagem tem um campo “cartao” do Tipo
“O”, logo “cartao” é um objeto Cartao; o L: lista de objeto. Exemplo: Cartão possui campo “listaPerguntaResposta”
do tipo “L”, logo “listaPerguntaResposta” é uma lista com 1 ou n
ocorrências do objeto PerguntaResposta;
Descrição: informações sobre o campo;
Objeto: Venda
Campo Tipo Descrição
nsuOrigem C Campo chave da venda para o cliente
nsuAdministradora N Nsu da venda na administradora
nrAutorizacao C Número da autorização da venda
redeAdquirente N Número da rede adquirente, conforme item 4.b
data D Data e hora da venda
nrCartao C Número do cartão
loja C Nome da loja
codigoEstabelecimento N Código do estabelecimento
valor N Valor da venda
nrParcelas N Número de parcelas da venda
bandeira N Número da bandeira, conforme item 4.c
modalidade N 1 – Débito, 2 – Crédito, 3 – Voucher
banco N Banco onde será creditado o valor para o cliente
agencia N Agência onde será creditado o valor para o cliente
conta N Conta onde será creditado o valor para o cliente
codigoLoja N Codigo da loja no Conciliador
formaCaptura C Veja lista de formas de captura no item 4.e
chaveVenda N Campo que identifica unicamente uma venda para o Conciliador
parcelas L Lista de parcelas da venda
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 6 de 12
Objeto: Parcela
Campo Tipo Descrição
nsuOrigem C Campo chave da parcela para o cliente
dataCredito D Data de prevista de crédito
status N Código do status da parcela, conforme item 4.d
numero N Número da parcela
dataPagamento D Data que o crédito foi realizado
valorTaxaAdministracao N Valor da taxa de administração
percTaxaAdministracao N Percentual da taxa de administração
valorTaxaAntecipacao N Valor da taxa de antecipação
percTaxaAntecipacao N Percentual da taxa de antecipação
valorAjuste N Valor de ajuste
valorPago N Valor pago
valor N Valor da parcela
chaveParcela N Campo que identifica unicamente uma parcela para o Conciliador
percTaxaAntecipacaoNominal N Percentual da taxa de antecipação nominal
Objeto: Lancamento
Campo Tipo Descrição
data N Data do lançamento
codigoLoja N Código da loja no Conciliador
nomeLoja C Nome da loja no Conciliador
redeAdquirente N Número da rede adquirente, conforme item 4.b
bandeira N Número da bandeira, conforme item 4.c
codigoHistorico N Código do histórico de lançamento no Conciliador
descricaoHistorico C Descrição do histórico de lançamento
flagDebitoCredito C D – Débito, C – Crédito
valor N Valor do lançamento
codigoConciliador N Código de identificação do lançamento no conciliador
banco N Código do banco que foi realizado o lançamento
agencia N Número da agencia que foi realizado o lançamento
conta N Número da conta que foi realizado o lançamento
Objeto: Retorno
Campo Tipo Descrição
codigoRetorno C Vide anexo III – Tabela de códigos de retorno
detalheRetorno C No caso da solicitação não ter sido atendida por algum erro, será informado neste campo maiores detalhes do problema detectado
codigoRequisicao N Número que identifica unicamente esta requisição
nrPaginaAtual N Pagina atual enviada
nrTotalPagina N Número total de paginas
vendas L Lista de vendas (só tem retorno para consulta de venda)
vendasDuplicadas L Lista de venda duplicadas (esta informação não deve ser preenchida na requisição, ela será retornada na resposta, para o caso do cliente, que valida repetição de venda, tentar registrar vendas duplicadas. Só é preenchido na resposta do serviço registrar venda)
lancamentos L Lista de vendas (só tem retorno para consulta de lançamento)
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 7 de 12
Objeto: LoteVenda
Campo Tipo Descrição
nsuLote N Campo chave do lote de venda para o cliente
codigoCliente N Código do cliente
nrVendas N Número de vendas no lote
totalVendas N Valor total de vendas deste lote
vendas L Lista de venda
Objeto: ConsultaLancamento
Campo Tipo Descrição
dataInicial D Data inicial do lançamento (obrigatório)
dataFinal D Data final do lançamento (obrigatório)
valorInicial N Valor inicial do lançamento
valorFinal N Valor final do lançamento
codigoLoja N Código da loja no Conciliador
redeAdquirente N Número da rede adquirente, conforme item 4.b
bandeira N Número da bandeira, conforme item 4.c
codigoHistorico N Código do histórico de lançamento no Conciliador
flagDebitoCredito C D – Débito, C – Crédito
codigoRequisicao N Código da requisição da consulta original (utilizado para tratar paginação)
nrPagina N Número da página requerida da consulta original(utilizado para tratar paginação)
Objeto: ConsultaVenda
Campo Tipo Descrição
codigoCliente N Código do cliente
nsuLote N Campo chave do lote de venda para o cliente
nsuVenda N Campo chave da venda para o cliente
nrAutorizacao N Número da autorização da venda
codigoRequisicao N Código da requisição da consulta original (utilizado para tratar paginação)
nrPagina N Número da página requerida da consulta original(utilizado para tratar paginação)
dataVendaInicial D Data de venda inicial
dataVendaFinal D Data de venda final
dataInclusaoInicial D Data de inclusão inicial
dataInclusaoFinal D Data de inclusão final
dataPagamentoInicial D Data de pagamento inicial
dataPagamentoFinal D Data de pagamento final
dataCancelamentoInicial D Data de cancelamento inicial
dataCancelamentoFinal D Data de cancelamento final
dataCreditoInicial D Data de crédito inicial
dataCreditoFinal D Data de crédito final
status N Situção da parcela (ver campo status do objeto parcela)
codigoEstabelecimento N Código do estabelecimento na administradora de cartão
codigoLoja N Codigo da loja no Conciliador
nsuAdministradora N Nsu da administradora
nrParcela N Número da parcela
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 8 de 12
3. Serviços
a. Registro de venda do cliente
Para o cliente registrar os dados de uma venda deverá chamar o serviço
registraVendaCliente do BR-WS passando os seguintes parâmetros:
Campo Tipo Descrição
versao N Versão do BR-WS utilizado
loteVenda O XML ou Json que representa o objeto de loteVenda. O número máximo de vendas por lote é 100.
token N Conjunto de caracteres que autentica o cliente, esta informação é fornecida pela BR Consulting
Como resposta a solicitação enviada acima será retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificação 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 serviço
consultaVendaCliente do BR-WS passando os seguintes parâmetros:
Campo Tipo Descrição
versao N Versão do BR-WS utilizado
consultaVenda O XML ou Json que representa um objeto consultaVenda
token N Conjunto de caracteres que autentica o cliente, esta informação é fornecida pela BR Consulting
Como resposta a solicitação enviada acima será retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificação dos objetos
utilizados (item 4.1).
c. Consulta de venda da administradora
Para o cliente consultar a(s) venda(s) das administradoras de cartão, deverá chamar o
serviço consultaVendaAdm do BR-WS passando os seguintes parâmetros:
Campo Tipo Descrição
versao N Versão do BR-WS utilizado
consultaVenda O XML ou Json que representa um objeto consultaVenda
token N Conjunto de caracteres que autentica o cliente, esta informação é fornecida pela BR Consulting
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 9 de 12
Como resposta a solicitação enviada acima será retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificação dos objetos
utilizados (item 4.1).
d. Exclusão de venda do cliente Para o cliente excluir uma venda enviada por ele mesmo, deverá chamar o serviço
excluiVendaCliente do BR-WS passando os seguintes parâmetros:
Campo Tipo Descrição
versao N Versão do BR-WS utilizado
venda O XML ou Json que representa um objeto venda. O campo data é obrigatório. Se for informado apenas o campo data, serão apagadas todas as vendas com a data informada. Para apagar apenas uma venda informar os seguintes campos, além do campo data:
nsuOrigem
valor
token N Conjunto de caracteres que autentica o cliente, esta informação é fornecida pela BR Consulting
Como resposta a solicitação enviada acima será retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificação dos objetos
utilizados (item 4.1).
e. Consulta de lançamento da administradora
Para o cliente consultar o(s) lançamentos(s) das administradoras de cartão, deverá chamar o
serviço consultaLancamento do BR-WS passando os seguintes parâmetros:
Campo Tipo Descrição
versao N Versão do BR-WS utilizado
consultaLancamento O XML ou Json que representa um objeto consultaLancamento
token N Conjunto de caracteres que autentica o cliente, esta informação é fornecida pela BR Consulting
Como resposta a solicitação enviada acima será retornada uma cadeia de caracteres que
representa o XML ou Json do objeto de retorno, conforme a especificação dos objetos
utilizados (item 4.1).
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 10 de 12
4. Anexo
a. Tabela de códigos de retorno das requisições
Código Tipo Descrição
MSG_001 Mensagem Resquisicao atendida com sucesso.
ERR_001 Erro Erro inesperado, no momento de registrar a requisicao no banco de dados
ERR_002 Erro Erro inesperado, Tipo de entrada invalido.
ERR_003 Erro Erro inesperado na validacao do token. {0}
ERR_004 Erro Erro inesperado na consulta de requisicao. {0}
ERR_005 Erro Erro inesperado na obtencao dos filtros originais da consulta
ERR_006 Erro Erros nos filtros da requisicao original: {0}. {1}
ERR_007 Erro Erro inesperado na contagem do numero de paginas
ERR_008 Erro Erro inesperado na consulta de venda da administradora
ERR_009 Erro Erro inesperado na consulta das parcelas da venda
ERR_999 Erro Erro inesperado. {0}
NGC_001 Negócio Versão inválida
NGC_002 Negócio Token invalido
NGC_003 Negócio Número da página é obrigatório quando se informa o código da requisição
NGC_004 Negócio Um dos períodos é obrigatório: cancelamento, inclusão, pagamento, crédito ou venda
NGC_005 Negócio Codigo de requisicao: {0} inexistente para o cliente: {1}
NGC_006 Negócio O campo nrVendas eh obrigatorio
NGC_007 Negócio O campo totalVendas eh obrigatorio
NGC_008 Negócio A lista de vendas eh obrigatorio
NGC_009 Negócio O numero de vendas informado difere do numero de registros da lista de vendas
NGC_010 Negócio O total de vendas informado difere da soma de registros da lista de vendas
NGC_011 Negócio Campo data eh obrigatorio. Venda da posicao: {0}
NGC_012 Negócio Campo valor eh obrigatorio. Venda da posicao: {0}
NGC_014 Negócio Campo nrParcelas eh obrigatorio. Venda da posicao: {0}
NGC_016 Negócio O numero de parcelas informado difere do numero de registros da lista de parcelas. Venda da posicao: {0}
NGC_017 Negócio Campo numero eh obrigatorio. Venda da posicao {0} parcela de posicao: {1}
NGC_018 Negócio Campo valor eh obrigatorio. Venda da posicao: {0} parcela de posicao: {1}
NGC_019 Negócio O valor da venda informado difere do valor da soma das parcelas. Venda da posicao: {0}
NGC_020 Negócio O campo forma de captura deve ser igual a P (POS) ou T (TEF). Venda da posicao: {0}
NGC_021 Negócio O campo Nsu de Origem é obrigatório
NGC_022 Negócio Não foi encontrada nenhuma venda com o nsuOrigem, data e valor passados
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 11 de 12
b. Lista de redes adquirentes
Código Descrição
1 Cielo
2 RedeCard
3 HiperCard
4 CrediShop
5 Losango
6 GETNET
7 LiberCrad
8 FortBrasil
9 Amex
10 BaneseCard
11 Elavon
c. Lista de bandeiras
Código Descrição
1 Visa
2 MasterCard
3 HiperCard
4 Amex
5 CrediShop
6 Sodexo
7 LiberCard
8 GoodCard
9 Aura
10 Losango
11 Elo
12 SoroCred
13 Cabal
14 Diners
15 AgiPlan
16 FortBrasil
17 CredZ
18 CredSystem
19 CUP
20 Sicredi
21 BanesCard
22 Discover
23 Esplanada
24 BaneseCard
BR Consulting BR WebService – Manual de Integração
BR WebService - Manual Integração Página 12 de 12
d. Lista de status da parcela
Código Descrição
0 Não conciliada
1 Previsto
2 Confirmado
3 Liquidado
4 Cancelado
5 Antecipado
6 Cancelado Administradora
7 Cancelado Cliente
10 Ajustado
11 Cancelado Por Reagendamento
12 Suspenso/Penhorado/Retido
13 Liquidado Por Aceleração
e. Lista de formas de captura
i. TEF
ii. POS
iii. Manual
iv. Internet
v. Leitor de Trilhas
vi. URA
vii. Arquivo
viii. Mobile
top related