Você está na página 1de 21
Integração via WebService 16/10/2013 Versão Documentação 1.02 Versão WS 1.07

Integração via WebService

16/10/2013

Versão Documentação 1.02 Versão WS 1.07

APRESENTAÇÃO 4 FUNCIONAMENTO 5 1. FLUXO DE CHAMADA DE MÉTODOS 5 1.1. S ENTIDO DOS

APRESENTAÇÃO

4

FUNCIONAMENTO

5

1.

FLUXO DE CHAMADA DE MÉTODOS

5

1.1.

SENTIDO DOS FLUXOS

5

1.2.

LOGON

5

1.1.

BAIXA DE OPERADORAS E PRODUTOS

5

1.2.

RECARGA

5

1.1.

2ª VIA DE COMPROVANTE DE RECARGA

6

1.1.

CONSULTA DE RECARGAS POR TELEFONE

6

1.1.

PESQUISA DE RECARGAS POR STATUS E PERÍODO

6

 

WEBSERVICES

7

1. LOGON

7

 

1.1. ENTRADA

7

 

1.2. SAÍDA

7

2. BUSCARDADOSOPERADORASDDD

8

 

2.1. ENTRADA

8

 

2.2. SAÍDA

8

3. AUTORIZARTRANSACAOPORESTABELECIMENTO

10

 

3.1.

SAÍDA

10

4. CONFIRMARTRANSACAOPORESTABELECIMENTO

12

 

4.1. ENTRADA

12

 

4.2. SAÍDA

13

5. BUSCARDADOSCOMPROVANTE

14

 

5.1. ENTRADA

14

 

5.2. SAÍDA

14

6. CONSULTARRECARGA

16

 

6.1. ENTRADA

16

 

6.2. SAÍDA

16

7. CONSULTARRECARGAS

18

 

7.1.

ENTRADA

18

8. CANCELARRECARGA 20 8.1. E NTRADA 20 8.2. S AÍDA 20

8.

CANCELARRECARGA

20

8.1. ENTRADA

20

8.2. SAÍDA

20

Apresentação Este manual descreve a interface de venda de recargas da Redetrel entre parceiros, via

Apresentação

Este manual descreve a interface de venda de recargas da Redetrel entre parceiros, via WebServices. Os métodos disponibilizados incluem o logon, baixa de produtos, realização de recarga em 3 pernas, impressão de comprovante e consulta de recargas.

Funcionamento 1. Fluxo de chamada de métodos 1.1. Sentido dos fluxos Sentido Significado Do parceiro

Funcionamento

1. Fluxo de chamada de métodos

1.1. Sentido dos fluxos

Sentido

Significado

Do parceiro para a Redetrel

Da Redetrel para o parceiro

1.2. Logon

Método

Sentido

Logon – entrada

Logon – saída

1.1. Baixa de operadoras e produtos

Método

Sentido

BuscarDadosOperadorasDDD – entrada

BuscarDadosOperadorasDDD – saída

1.2. Recarga

Método

Sentido

Comentários

AutorizarTransacaoPorEstabelecimento - entrada AutorizarTransacaoPorEstabelecimento – saída

Tendo retorno positivo, parceiro realiza cobrança do cliente e

imprime comprovante da operação.

ConfirmarTransacaoPorEstabelecimento - entrada

Parceiro envia confirmação da operação para a Redetrel, que efetivamente realiza a operação de recarga

ConfirmarTransacaoPorEstabelecimento – saída

1.1. 2ª via de comprovante de recarga Método Sentido buscarDadosComprovante – entrada

1.1. 2ª via de comprovante de recarga

Método

Sentido

buscarDadosComprovante – entrada

buscarDadosComprovante – saída

1.1. Consulta de recargas por telefone

Método

Sentido

ConsultarRecarga – entrada

ConsultarRecarga – saída

1.1. Pesquisa de recargas por status e período

Método

Sentido

ConsultarRecargas – entrada

ConsultarRecargas – saída

WebServices Abaixo são listados os métodos que devem ser implementados pelo emissor. 1. Logon Para

WebServices

Abaixo são listados os métodos que devem ser implementados pelo emissor.

1.

Logon

Para ser possível o uso dos WebServices, a Redetrel deve previamente cadastrar e configurar o parceiro, definindo o terminal, código do cliente e do ponto e cadastrando o mac address do servidor que irá conectar na sua plataforma. A Redetrel definirá uma senha que deve ser utilizada no logon.

Diariamente, o parceiro deve autenticar na plataforma informando credenciais previamente fornecidas pela Redetrel. Sendo as credenciais e mac address válidos o logon retorna um token, o qual deve ser utilizado em todas os demais métodos. O token expira ao final do dia.

1.1.

Entrada

 

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

 

Código do cliente, definido pela Redetrel.

String

 

Sim

senha

Senha do cliente, definida pela Redetrel.

String

 

Sim

codigoTerminal

 

Código do terminal, definido pela Redetrel.

String

 

Sim

codigoEstabelecimento

Código do ponto do cliente

String

 

Sim

macAdress

Endereço físico da placa de rede do servidor que envia a solicitação. Deve ser enviado sem hífens, apenas os caracteres alfanuméricos. Ex.: C1A4E3B098092B

String

 

Sim

1.2.

Saída

 

Nome

Descrição

Tipo

tokenVO

Objeto que contém o token diário e sua datahora de validade

 

Objeto

Atributos de tokenVO

 

Nome

Descrição

Tipo

token

Código diário de validação de acesso que deve ser enviado em cada método. Sem o envio do código correto os métodos retornam erro. Se a operação de LOGON for malsucedida, este atributo é retornado vazio.

 

String

dataValidade

Data de validade do token.

 

Date

mensagem

Se a operação de LOGON for bem sucedida, este atributo vem vazio. Caso contrário, traz a descrição do erro.

String

2. buscarDadosOperadorasDDD Este método deve ser chamado diariamente após o Logon. Ele retorna todas as

2.

buscarDadosOperadorasDDD

Este método deve ser chamado diariamente após o Logon. Ele retorna todas as operadoras e seus produtos disponíveis, agrupados por DDD.

2.1.

Entrada

 

Nome

Descrição

 

Tipo

Obrigatório

codigoOrigem

Código de origem

 

String

 

Sim

senha

Senha

 

String

 

Sim

token

Código diário de validação de acesso

String

 

Sim

codigoTerminal

Código do terminal, definido pela Redetrel.

String

 

Não

2.2.

Saída

 

Nome

Descrição

Tipo

RetornoDadosOperadorasDDD

Objeto que contém relação de operadoras disponíveis

 

Objeto

Atributos de RetornoOPeradorasDDD

 

Nome

Descrição

 

Tipo

codigoRetorno

 

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0)

 

String

descricaoRetorno

Descrição do código de retorno.

 

String

operadoras

Vetor com todas as operadoras. Vetor com objetos do tipo OperadoraVO

Array

boletoDisponivel

 

Sempre enviado como False.

 

Boolean

Atributos de OperadoraVO

 

Nome

Descrição

Tipo

descricaoOperadora

Nome da operadora

 

String

regionais

Vetor com todas as regionais da operadora. Vetor de objetos do tipo RegionalVO

Array

Atributos de RegionalVO Nome Descrição Tipo descricaoRegional Nome da regional String codigoRegional

Atributos de RegionalVO

Nome

Descrição

Tipo

descricaoRegional

Nome da regional

String

codigoRegional

Código da Regional

String

valores

Vetor com os produtos da Regional. Vetor com objetos do tipo Valor

Array

 

Vetor com os DDDs atendidos pela regional.

Array

dddArray

String

Atributos de Valor

Nome

Descrição

Tipo

valorFace

Valor de recarga, sem separador decimal. Ex.: R$20,00 = 2000.

Long

valorBonus

Valor do bônus.

Long

produto

Devolvido fixo como “Recarga de Voz”.

String

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Operadoras não configuradas

2

Token Inválido/Usuário não autenticado.

3

Concessionárias não cadastradas.

5

Falha geral.

3. autorizarTransacaoPorEstabelecimento A transação de recarga de celular é realiza em 3 etapas. A chamada

3.

autorizarTransacaoPorEstabelecimento

A transação de recarga de celular é realiza em 3 etapas. A chamada deste método é a primeira delas. Ao receber chamada deste método, a Redetrel verifica com a operadora se a recarga pode ser realizada para os parâmetros informados (regional, celular, valor). Caso positivo, este método devolve dados para serem impressos no comprovante (2ª etapa).

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

Código de origem

String

Sim

Senha

Senha

String

Sim

codigoRegional

Código da regional

String

Sim

numeroTelefone

Número de celular do cliente, no formado DDSNNNNNNNN, onde DD é o DDD com 2 dígitos, S é opcional, sendo 9 quando DD = 11; NNNNNNNN são os oito dígitos finais do telefone. Exemplo:

String

Sim

2192737261; 11988273726

Valor

Valor da recarga. O formato do valor será o mesmo do ValorFace enviado pelo método buscarDadosOperadorasDDD. Ex: R$ 20,00 = 2000

String

Sim

codigoEstabelecimento

Código do estabelecimento

String

Sim

token

Código diário de validação de acesso

String

Sim

codigoTerminal

Código do terminal, definido pela Redetrel.

String

Não

3.1.

Saída

Nome

Descrição

Tipo

autorizacaoVO

Objeto com os dados do processamento da recarga.

Objeto

Atributos de autorizacaoVO Nome Descrição Tipo codigoRetorno Identifica se a operação foi bem sucedida

Atributos de autorizacaoVO

Nome

Descrição

Tipo

codigoRetorno

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrição do retorno.

String

statusRecarga

Indica situação da transação no autorizador UNO. (Possíveis retornos descritos abaixo)

String

nsuHost

Número sequencial único da Redetrel

Long

numeroTelefone

Número do telefone

String

codigoRegional

Código da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorização de recarga.

DateTime

mensagemOperadora

Mensagem que a operadora envia ao solicitar a recarga. Deve ser impressa no comprovante de recarga.

String

boletoDisponivel

Sempre enviado como False.

Boolean

ATENÇÃO: Para verificar o sucesso da transação, deve-se utilizar o codigoRetorno. O campo statusRecarga representa meramente uma informação adicional.

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

2

Falha na integradora

3

Falha Geral – Banco Dados

4

Limite de Crédito Excedido

5

Produtos não Configurados

6

DDD não Permitido

7

Falha de Configuração

8

Falha Geral

Possíveis retornos para o Status da Transação Retorno Mensagem 1 Recarga Autorizada Pendente de

Possíveis retornos para o Status da Transação

Retorno

Mensagem

1

Recarga Autorizada Pendente de Confirmação. (Não Efetivada)

7

Negada pelo Distribuidor

8

Cancelada pelo Cliente

9

Negada por limite de crédito

10

Falha no Distribuidor – Cancelada automaticamente pelo WS quando não resposta do distribuidor.

4.

confirmarTransacaoPorEstabelecimento

Após o parceiro receber o retorno do método autorizarTransacaoPorEstabelecimento, imprimir o comprovante e receber o pagamento do cliente, ele deve enviar para a Redetrel a confirmação da transação. Ao receber esta confirmação, a Redetrle confirma frente a Operadora, que credita o valor da recarga e bônus do telefone do cliente.

4.1.

Entrada

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

Código de Origem

String

Sim

senha

Senha

String

Sim

autorizacao

O objeto autorizacao deve ser enviado exatamente da forma que foi retornado pelo método autorizarTransacaoPorEstabelecimento, com exceção do atributo codigoRetorno, o qual deve ser “0” para confirmação com sucesso.

AutorizacaoVO

Sim

codigoEstabelecimento

Código do estabelecimento

String

Sim

token

Código diário de validação de acesso

String

Sim

codigoTerminal

Código do terminal, definido pela Redetrel.

String

Não

4.2. Saída Nome   Descrição Tipo confirmacaoVO Objeto com dados da confirmação da recarga  

4.2.

Saída

Nome

 

Descrição

Tipo

confirmacaoVO

Objeto com dados da confirmação da recarga

 

Objeto

Atributos de confirmacaoVO

 

Nome

Descrição

Tipo

codigoRetorno

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrição do retorno.

String

statusRecarga

Indica situação da transação no autorizador UNO. (Possíveis retornos descritos abaixo)

String

nsuOperadora

Número sequencial único na operadora (ou integradora)

Long

nsuHost

Número sequencial único da Redetrel

Long

numeroTelefone

Número do telefone

String

codigoRegional

Código da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorização de recarga.

DateTime

mensagemOperadora

Mensagem que a operadora envia ao solicitar a recarga. Deve ser impressa no comprovante de recarga.

String

boletoDisponivel

Sempre enviado como False.

Boolean

ATENÇÃO: Para verificar o sucesso da transação, deve-se utilizar o codigoRetorno. O campo statusRecarga representa meramente uma informação adicional.

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

8

Falha Geral

4.2.1. Possíveis retornos para o Status da Transação Retorno Mensagem 1 Recarga Autorizada Pendente de

4.2.1. Possíveis retornos para o Status da Transação

Retorno

Mensagem

1

Recarga Autorizada Pendente de Confirmação. (Não Efetivada)

2

Recarga Confirmada, efetivada pela Operadora.

5.

buscarDadosComprovante

Este método permite a impresso da 2ª via do comprovante, tendo a finalidade de devolver os mesmos dados que são retornados pela confirmação bem sucedida de uma recarga.

5.1. Entrada

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

Código de origem

String

 

Sim

senha

Senha

String

 

Sim

nsuHost

Número sequencial único da Redetrel, utilizado para identificar a recarga.

String

 

Sim

codigoRegional

Código da regional

String

 

Sim

token

Código diário de validação de acesso.

Long

 

Sim

produto

Devolvido fixo como “RV”.

String

 

Sim

codigoTerminal

Código do terminal, definido pela Redetrel.

String

 

Não

5.2.

Saída

 

Nome

Descrição

Tipo

RetornoDadosRecarga

Objeto que contém os dados para a impressão da 2ª via do comprovante.

Objeto

Atributos de RetornoDadosRecarga

 

Nome

Descrição

Tipo

codigoRetorno

 

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

String

descricaoRetorno

 

Descrição do retorno.

String

recarga

Objeto com os dados da recarga.

Objeto

boletoDisponivel

 

Sempre enviado como False.

Boolean

Atributos de Recarga Nome Descrição Tipo statusRecarga Indica se a recarga foi ou não autorizada.

Atributos de Recarga

Nome

Descrição

Tipo

statusRecarga

Indica se a recarga foi ou não autorizada.

String

nsuOperadora

Número sequencial único na operadora (ou integradora)

 

nsuHost

Número sequencial único da Redetrel

Long

numeroTelefone

Número do telefone

String

codigoRegional

Código da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorização de recarga.

DateTime

mensagemOperadora

Mensagem que a operadora envia ao solicitar a recarga. Deve ser impressa no comprovante de recarga.

String

boletoDisponivel

Sempre enviado como False.

Boolean

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

8

Falha Geral

6. consultarRecarga Este método permite a consulta de todas as recargas realizadas para o telefone

6.

consultarRecarga

Este método permite a consulta de todas as recargas realizadas para o telefone informado.

6.1. Entrada

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

Código de Origem.

String

 

Sim

senha

Senha

String

 

Sim

numeroTelefone

Número do telefone.

String

 

Sim

Token

Código diário de validação de acesso.

String

 

Sim

Produto

Devolvido fixo como “RV”.

String

 

Sim

codigoTerminal

Código do terminal, definido pela Redetrel.

String

 

Não

6.2.

Saída

Nome

Descrição

Tipo

RetornoConsulta

Objeto com dados da consulta.

Objeto

Atributos de RetornoConsulta

 

Nome

Descrição

Tipo

codigoRetorno

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

 

String

descricaoRetorno

Descrição do retorno.

String

recargas

Vetor com as recargas encontradas. Vetor com objetos do tipo Recarga

 

Array

boletoDisponivel

Sempre enviado como False.

Boolean

Atributos de Recarga Nome Descrição Tipo Status Status da recarga: Efetivada, Cancelada ou Pendente;

Atributos de Recarga

Nome

Descrição

Tipo

Status

Status da recarga: Efetivada, Cancelada ou Pendente;

String

nsuOperadora

Número sequencial único da operadora.

Long

nsuHost

Número sequencial único da Redetrel

Long

nsuCentralizador

NSU secundário de verificação da Redetrel.

Long

numeroTelefone

Número do telefone.

String

codigoRegional

Código da regional.

String

valorFace

Valor da recarga

Long

dataAutorizacao

Data e hora da autorização da recarga pela Redtrel no formato yyyy-mm- dd hh:mm:ss. Ex: 2008-01-25 11:22:55;

String

mensagem

Mensagem da operadora que deve ser impressa no comprovante.

String

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

8

Falha Geral

7. consultarRecargas Este método permite a consulta de recargas de acordo com período e status

7.

consultarRecargas

Este método permite a consulta de recargas de acordo com período e status.

7.1. Entrada

Nome

 

Descrição

Tipo

Obrigatório

codigoOrigem

 

Código de origem.

String

 

Sim

senha

 

Senha.

String

 

Sim

   

Data

e hora iniciais da pesquisa no formato yyyy-mm-dd

   

dataInicial

 

hh:mm:ss.

String

 

Sim

   

Data

e hora iniciais da pesquisa no formato yyyy-mm-dd

   

dataFinal

 

hh:mm:ss.

String

 

Sim

status

 

Status das recargas que serão pesquisadas, podendo ser “E” de Efetivadas ou “C” de Canceladas.

String

 

Sim

token

 

Código diário de validação de acesso.

String

 

Sim

produto

 

Código que identifica o tipo do produto. Para efetuar uma recarga de voz utiliza-se o seguinte código “RV”.

String

 

Sim

codigoTerminal

 

Código do terminal, definido pela Redetrel.

String

 

Não

7.2.

Saída

 

Nome

   

Descrição

Tipo

RetornoConsulta

 

Objeto com o resultado da pesquisa.

 

Objeto

Atributos de RetornoConsulta

 

Nome

Descrição

 

Tipo

codigoRetorno

 

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

 

String

descricaoRetorno

Descrição do retorno.

 

String

recargas

Vetor com as recargas retornadas pela consulta. Vetor de objetos do tipo Recarga

Array

boletoDisponivel

 

Sempre enviado como False.

 

Boolean

Atributos de Recarga Nome Descrição Tipo status Status da recarga: Efetivada, Cancelada ou Pendente;

Atributos de Recarga

Nome

Descrição

Tipo

status

Status da recarga: Efetivada, Cancelada ou Pendente;

String

nsuOperadora

Número sequencial único da operadora.

Long

nsuHost

Número sequencial único da Redetrel

Long

nsuCentralizador

NSU secundário de verificação da Redetrel.

Long

numeroTelefone

Número do telefone.

String

codigoRegional

Código da regional.

String

valorFace

Valor da recarga

Long

dataAutorizacao

Data e hora da autorização da recarga pela Redtrel no formato yyyy-mm- dd hh:mm:ss. Ex: 2008-01-25 11:22:55;

String

mensagem

Mensagem da operadora que deve ser impressa no comprovante.

String

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

8

Falha Geral

8. cancelarRecarga Este método permite o cancelamento de recargas ainda com status PENDENTE. 8.1. Entrada

8.

cancelarRecarga

Este método permite o cancelamento de recargas ainda com status PENDENTE.

8.1. Entrada

Nome

Descrição

Tipo

Obrigatório

codigoOrigem

 

Código de Origem

String

 

Sim

Senha

Senha

String

 

Sim

Token

Código diário de validação de acesso

String

 

Sim

Data

Data da transação no formato yyyy-mm-dd hh.

String

 

Sim

nsuHost

Número sequencial único da Redetrel

Long

 

Sim

codigoTerminal

 

Código do terminal, definido pela Redetrel.

String

 

Não

8.2.

Saída

Nome

Descrição

Tipo

cancelamentoVO

Objeto com dados do cancelamento da recarga

 

Objeto

Atributos de cancelamentoVO Nome Descrição Tipo codigoRetorno Identifica se a operação foi bem sucedida

Atributos de cancelamentoVO

Nome

Descrição

Tipo

codigoRetorno

Identifica se a operação foi bem sucedida (retornando 0) ou se houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrição do retorno.

String

statusRecarga

Indica se a recarga foi ou não autorizada.

String

nsuHost

Número sequencial único da Redetrel

Long

numeroTelefone

Número do telefone

String

codigoRegional

Código da regional

Integer

valorFace

Valor da recarga

Long

Códigos de retorno

Retorno

Mensagem

0

Sucesso

1

Token Inválido/Usuário não Autenticado

8

Falha Geral