Manual de Integração - BRWebService - Versão 1.2.0

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




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


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



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



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.



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



Objeto: Parcela


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


data N Data do lançamento

codigoLoja N Código da loja no Conciliador

nomeLoja C Nome da loja no Conciliador



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


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)



Objeto: LoteVenda


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


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



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


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



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:


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:



consultaVenda O XML ou Json que representa um objeto consultaVenda





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:



consultaVenda O XML ou Json que representa um objeto consultaVenda







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:



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





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:



consultaLancamento O XML ou Json que representa um objeto consultaLancamento







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



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



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

Manual de Integração - BRWebService - Versão 1.2.0

Documents

Transcript of Manual de Integração - BRWebService - Versão 1.2.0