Integrao via WebService

16/10/2013
Verso Documentao 1.02
Verso WS 1.07

APRESENTAO ..................................................................................................... 4
FUNCIONAMENTO ................................................................................................. 5
1.

FLUXO DE CHAMADA DE MTODOS ............................................................................................ 5

1.1.
1.2.
1.1.
1.2.
1.1.
1.1.
1.1.

SENTIDO DOS FLUXOS ........................................................................................................................ 5

LOGON ........................................................................................................................................... 5
BAIXA DE OPERADORAS E PRODUTOS ................................................................................................... 5
RECARGA ........................................................................................................................................ 5
2 VIA DE COMPROVANTE DE RECARGA ................................................................................................ 6
CONSULTA DE RECARGAS POR TELEFONE............................................................................................... 6
PESQUISA DE RECARGAS POR STATUS E PERODO .................................................................................... 6

WEBSERVICES ........................................................................................................ 7
1.

LOGON ...................................................................................................................................... 7
1.1.
1.2.

2.

BUSCARDADOSOPERADORASDDD .............................................................................................. 8
2.1.
2.2.

3.

ENTRADA ...................................................................................................................................... 14
SADA ........................................................................................................................................... 14

CONSULTARRECARGA .............................................................................................................. 16
6.1.
6.2.

7.

ENTRADA ...................................................................................................................................... 12
SADA ........................................................................................................................................... 13

BUSCARDADOSCOMPROVANTE................................................................................................ 14
5.1.
5.2.

6.

SADA ........................................................................................................................................... 10

CONFIRMARTRANSACAOPORESTABELECIMENTO...................................................................... 12
4.1.
4.2.

5.

ENTRADA ........................................................................................................................................ 8
SADA ............................................................................................................................................. 8

AUTORIZARTRANSACAOPORESTABELECIMENTO ....................................................................... 10
3.1.

4.

ENTRADA ........................................................................................................................................ 7
SADA ............................................................................................................................................. 7

ENTRADA ...................................................................................................................................... 16
SADA ........................................................................................................................................... 16

CONSULTARRECARGAS............................................................................................................. 18
7.1.
7.2.

ENTRADA ...................................................................................................................................... 18
SADA ........................................................................................................................................... 18

8.

CANCELARRECARGA ................................................................................................................. 20
8.1.
8.2.

ENTRADA ...................................................................................................................................... 20
SADA ........................................................................................................................................... 20

Apresentao
Este manual descreve a interface de venda de recargas da Redetrel entre parceiros, via WebServices. Os
mtodos disponibilizados incluem o logon, baixa de produtos, realizao de recarga em 3 pernas,
impresso de comprovante e consulta de recargas.

Funcionamento
1. Fluxo de chamada de mtodos
1.1. Sentido dos fluxos
Sentido

Significado
Do parceiro para a Redetrel

Da Redetrel para o parceiro

1.2. Logon
Mtodo

Sentido

Logon entrada
Logon sada

1.1. Baixa de operadoras e produtos

Mtodo

Sentido

BuscarDadosOperadorasDDD entrada
BuscarDadosOperadorasDDD sada

1.2. Recarga
Mtodo

AutorizarTransacaoPorEstabelecimento - entrada
AutorizarTransacaoPorEstabelecimento sada

Sentido

ConfirmarTransacaoPorEstabelecimento - entrada
ConfirmarTransacaoPorEstabelecimento sada

Comentrios
Tendo retorno positivo, parceiro
realiza cobrana do cliente e
imprime comprovante da
operao.
Parceiro envia confirmao da
operao para a Redetrel, que
efetivamente realiza a operao
de recarga

1.1. 2 via de comprovante de recarga

Mtodo

Sentido

buscarDadosComprovante entrada
buscarDadosComprovante sada

1.1. Consulta de recargas por telefone

Mtodo

Sentido

ConsultarRecarga entrada
ConsultarRecarga sada

1.1. Pesquisa de recargas por status e perodo

Mtodo

Sentido

ConsultarRecargas entrada
ConsultarRecargas sada

WebServices
Abaixo so listados os mtodos que devem ser implementados pelo emissor.

1. Logon
Para ser possvel o uso dos WebServices, a Redetrel deve previamente cadastrar e configurar o parceiro,
definindo o terminal, cdigo 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 vlidos o logon retorna um token, o qual deve ser
utilizado em todas os demais mtodos. O token expira ao final do dia.
1.1. Entrada
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo do cliente, definido pela Redetrel.

String

Sim

senha

Senha do cliente, definida pela Redetrel.

String

Sim

codigoTerminal

Cdigo do terminal, definido pela Redetrel.

String

Sim

String

Sim

Endereo fsico da placa de rede do servidor que envia a

solicitao. Deve ser enviado sem hfens, apenas os String
caracteres alfanumricos. Ex.: C1A4E3B098092B

Sim

codigoEstabelecimento Cdigo do ponto do cliente

macAdress

1.2. Sada
Nome

Descrio

Tipo

tokenVO

Objeto que contm o token dirio e sua datahora de validade

Objeto

Atributos de tokenVO
Nome
token
dataValidade
mensagem

Descrio

Tipo

Cdigo dirio de validao de acesso que deve ser enviado em cada

mtodo. Sem o envio do cdigo correto os mtodos retornam erro. Se a
String
operao de LOGON for malsucedida, este atributo retornado vazio.
Data de validade do token.
Date
Se a operao de LOGON for bem sucedida, este atributo vem vazio. Caso
String
contrrio, traz a descrio do erro.

2. buscarDadosOperadorasDDD
Este mtodo deve ser chamado diariamente aps o Logon. Ele retorna todas as operadoras e seus produtos
disponveis, agrupados por DDD.
2.1. Entrada
Nome
codigoOrigem
senha

Descrio
Cdigo de origem
Senha

Tipo
String
String

Obrigatrio
Sim
Sim

token

Cdigo dirio de validao de acesso

String

Sim

String

No

codigoTerminal Cdigo do terminal, definido pela Redetrel.

2.2. Sada
Nome

Descrio

RetornoDadosOperadorasDDD Objeto que contm relao de operadoras disponveis

Tipo
Objeto

Atributos de RetornoOPeradorasDDD
Nome

Descrio
Identifica se a operao foi bem sucedida (retornando 0) ou se houve
codigoRetorno
algum erro (retornando valor <> 0)
descricaoRetorno Descrio do cdigo de retorno.
Vetor com todas as operadoras. Vetor com objetos do tipo OperadoraVO
operadoras
boletoDisponivel Sempre enviado como False.

Tipo
String
String
Array
Boolean

Atributos de OperadoraVO
Nome

Descrio

descricaoOperadora Nome da operadora

regionais

Tipo
String

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

Array
RegionalVO

Atributos de RegionalVO
Nome

Descrio

descricaoRegional Nome da regional

codigoRegional

Cdigo da Regional

Tipo
String
String

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

Array

Vetor com os DDDs atendidos pela regional.

Array
String

Nome

Descrio

Tipo

valorFace

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

Long

valorBonus

Valor do bnus.

Long

produto

Devolvido fixo como Recarga de Voz.

String

valores
dddArray

Atributos de Valor

Cdigos de retorno
Retorno
0
1
2
3
5

Mensagem
Sucesso
Operadoras no configuradas
Token Invlido/Usurio no autenticado.
Concessionrias no cadastradas.
Falha geral.

3. autorizarTransacaoPorEstabelecimento
A transao de recarga de celular realiza em 3 etapas. A chamada deste mtodo a primeira delas. Ao
receber chamada deste mtodo, a Redetrel verifica com a operadora se a recarga pode ser realizada para
os parmetros informados (regional, celular, valor). Caso positivo, este mtodo devolve dados para serem
impressos no comprovante (2 etapa).
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo de origem

String

Sim

Senha

Senha

String

Sim

codigoRegional

Cdigo da regional

String

Sim

numeroTelefone

Nmero de celular do cliente, no formado

DDSNNNNNNNN, onde DD o DDD com 2 dgitos, S
opcional, sendo 9 quando DD = 11; NNNNNNNN so String
os oito dgitos finais do telefone. Exemplo:
2192737261; 11988273726

Sim

Valor

Valor da recarga. O formato do valor ser o mesmo

do
ValorFace
enviado
pelo
mtodo String
buscarDadosOperadorasDDD. Ex: R$ 20,00 = 2000

Sim

codigoEstabelecimento Cdigo do estabelecimento

String

Sim

token

Cdigo dirio de validao de acesso

String

Sim

codigoTerminal

Cdigo do terminal, definido pela Redetrel.

String

No

3.1. Sada
Nome

Descrio

Tipo

autorizacaoVO

Objeto com os dados do processamento da recarga.

Objeto

Atributos de autorizacaoVO
Nome
Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se

houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrio do retorno.

String

statusRecarga

Indica situao da transao no autorizador UNO. (Possveis

retornos descritos abaixo)

String

nsuHost

Nmero sequencial nico da Redetrel

Long

numeroTelefone

Nmero do telefone

String

codigoRegional

Cdigo da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorizao 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

ATENO: Para verificar o sucesso da transao, deve-se utilizar o codigoRetorno. O campo statusRecarga
representa meramente uma informao adicional.
Cdigos de retorno
Retorno
0
1
2
3

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha na integradora
Falha Geral Banco Dados

Limite de Crdito Excedido

Produtos no Configurados

DDD no Permitido

Falha de Configurao

Falha Geral

Possveis retornos para o Status da Transao

Retorno
1
7

Mensagem
Recarga Autorizada Pendente de Confirmao. (No Efetivada)
Negada pelo Distribuidor

Cancelada pelo Cliente

Negada por limite de crdito

10

Falha no Distribuidor Cancelada automaticamente pelo WS quando no resposta do

distribuidor.

4. confirmarTransacaoPorEstabelecimento
Aps o parceiro receber o retorno do mtodo autorizarTransacaoPorEstabelecimento, imprimir o
comprovante e receber o pagamento do cliente, ele deve enviar para a Redetrel a confirmao da
transao. Ao receber esta confirmao, a Redetrle confirma frente a Operadora, que credita o valor da
recarga e bnus do telefone do cliente.
4.1. Entrada
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo de Origem

String

Sim

senha

Senha

String

Sim

autorizacao

O objeto autorizacao deve ser enviado

exatamente da forma que foi retornado pelo
mtodo autorizarTransacaoPorEstabelecimento, AutorizacaoVO
com exceo do atributo codigoRetorno, o qual
deve ser 0 para confirmao com sucesso.

Sim

codigoEstabelecimento Cdigo do estabelecimento

String

Sim

token

Cdigo dirio de validao de acesso

String

Sim

codigoTerminal

Cdigo do terminal, definido pela Redetrel.

String

No

4.2. Sada
Nome

Descrio

confirmacaoVO Objeto com dados da confirmao da recarga

Tipo
Objeto

Atributos de confirmacaoVO
Nome

Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se

houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrio do retorno.

String

statusRecarga

Indica situao da transao no autorizador UNO. (Possveis

String
retornos descritos abaixo)

nsuOperadora

Nmero sequencial nico na operadora (ou integradora)

Long

nsuHost

Nmero sequencial nico da Redetrel

Long

numeroTelefone

Nmero do telefone

String

codigoRegional

Cdigo da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorizao de recarga.

DateTime

mensagemOperadora
boletoDisponivel

Mensagem que a operadora envia ao solicitar a recarga. Deve ser

String
impressa no comprovante de recarga.
Sempre enviado como False.
Boolean

ATENO: Para verificar o sucesso da transao, deve-se utilizar o codigoRetorno. O campo statusRecarga
representa meramente uma informao adicional.

Cdigos de retorno
Retorno
0
1
8

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha Geral

4.2.1. Possveis retornos para o Status da Transao

Retorno
1
2

Mensagem
Recarga Autorizada Pendente de Confirmao. (No Efetivada)
Recarga Confirmada, efetivada pela Operadora.

5. buscarDadosComprovante
Este mtodo permite a impresso da 2 via do comprovante, tendo a finalidade de devolver os mesmos
dados que so retornados pela confirmao bem sucedida de uma recarga.
5.1. Entrada
Nome
codigoOrigem
senha

Descrio
Cdigo de origem
Senha

Tipo
String
String

Obrigatrio
Sim
Sim

nsuHost

Nmero sequencial nico da Redetrel, utilizado para identificar

String
a recarga.

Sim

codigoRegional
token

Cdigo da regional
Cdigo dirio de validao de acesso.

String
Long

Sim
Sim

produto

Devolvido fixo como RV.

String

Sim

codigoTerminal Cdigo do terminal, definido pela Redetrel.

String

No

5.2. Sada
Nome

Descrio

Tipo

RetornoDadosRecarga

Objeto que contm os dados para a impresso da 2 via do

comprovante.

Objeto

Atributos de RetornoDadosRecarga
Nome

Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se houve

String
algum erro (retornando valor <> 0).

descricaoRetorno

Descrio do retorno.

String

recarga

Objeto com os dados da recarga.

Objeto

boletoDisponivel

Sempre enviado como False.

Boolean

Atributos de Recarga
Nome
statusRecarga

Descrio
Indica se a recarga foi ou no autorizada.

nsuOperadora

Nmero sequencial nico na operadora (ou integradora)

nsuHost

Nmero sequencial nico da Redetrel

Long

numeroTelefone

Nmero do telefone

String

codigoRegional

Cdigo da regional

Integer

valorFace

Valor da recarga

Long

dataAutorizacao

Data que foi solicitada a autorizao de recarga.

DateTime

mensagemOperadora
boletoDisponivel

String

Mensagem que a operadora envia ao solicitar a recarga. Deve ser

String
impressa no comprovante de recarga.
Sempre enviado como False.
Boolean

Cdigos de retorno
Retorno
0
1
8

Tipo

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha Geral

6. consultarRecarga
Este mtodo permite a consulta de todas as recargas realizadas para o telefone informado.
6.1. Entrada
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo de Origem.

String

Sim

senha

Senha

String

Sim

numeroTelefone Nmero do telefone.

String

Sim

Token

Cdigo dirio de validao de acesso.

String

Sim

Produto

Devolvido fixo como RV.

String

Sim

codigoTerminal

Cdigo do terminal, definido pela Redetrel.

String

No

6.2. Sada
Nome

Descrio

RetornoConsulta Objeto com dados da consulta.

Tipo
Objeto

Atributos de RetornoConsulta
Nome

Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se houve

algum erro (retornando valor <> 0).

String

descricaoRetorno Descrio do retorno.

String

recargas

Array

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

boletoDisponivel Sempre enviado como False.

Boolean

Atributos de Recarga
Nome
Status

Descrio
Status da recarga: Efetivada, Cancelada ou Pendente;

Tipo
String

nsuOperadora

Nmero sequencial nico da operadora.

Long

nsuHost

Nmero sequencial nico da Redetrel

Long

nsuCentralizador NSU secundrio de verificao da Redetrel.

Long

numeroTelefone Nmero do telefone.

String

codigoRegional

Cdigo da regional.
Valor da recarga

valorFace

String
Long

Data e hora da autorizao da recarga pela Redtrel no formato yyyy-mmdataAutorizacao dd hh:mm:ss. Ex: 2008-01-25 11:22:55;
String

mensagem

Mensagem da operadora que deve ser impressa no comprovante.

Cdigos de retorno
Retorno
0
1
8

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha Geral

String

7. consultarRecargas
Este mtodo permite a consulta de recargas de acordo com perodo e status.
7.1. Entrada
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo de origem.

String

Sim

senha

Senha.

String

Sim

dataInicial

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

String
hh:mm:ss.

Sim

dataFinal

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

String
hh:mm:ss.

Sim

status

Status das recargas que sero pesquisadas, podendo ser E de

String
Efetivadas ou C de Canceladas.

Sim

token

Cdigo dirio de validao de acesso.

String

Sim

produto

Cdigo que identifica o tipo do produto. Para efetuar uma

String
recarga de voz utiliza-se o seguinte cdigo RV.

Sim

codigoTerminal Cdigo do terminal, definido pela Redetrel.

String

No

7.2. Sada
Nome

Descrio

RetornoConsulta Objeto com o resultado da pesquisa.

Tipo
Objeto

Atributos de RetornoConsulta
Nome

Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se houve

algum erro (retornando valor <> 0).

String

descricaoRetorno Descrio do retorno.

recargas

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

Recarga

boletoDisponivel Sempre enviado como False.

String
Array
Boolean

Atributos de Recarga
Nome
status

Descrio
Status da recarga: Efetivada, Cancelada ou Pendente;

Tipo
String

nsuOperadora

Nmero sequencial nico da operadora.

Long

nsuHost

Nmero sequencial nico da Redetrel

Long

nsuCentralizador NSU secundrio de verificao da Redetrel.

Long

numeroTelefone Nmero do telefone.

String

codigoRegional

Cdigo da regional.

String

valorFace

Valor da recarga

Long

Data e hora da autorizao da recarga pela Redtrel no formato yyyy-mmdataAutorizacao dd hh:mm:ss. Ex: 2008-01-25 11:22:55;
String

mensagem

Mensagem da operadora que deve ser impressa no comprovante.

Cdigos de retorno
Retorno
0
1
8

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha Geral

String

8. cancelarRecarga
Este mtodo permite o cancelamento de recargas ainda com status PENDENTE.
8.1. Entrada
Nome

Descrio

Tipo

Obrigatrio

codigoOrigem

Cdigo de Origem

String

Sim

Senha

Senha

String

Sim

Token

Cdigo dirio de validao de acesso

String

Sim

Data

Data da transao no formato yyyy-mm-dd hh.

String

Sim

nsuHost

Nmero sequencial nico da Redetrel

Long

Sim

codigoTerminal

Cdigo do terminal, definido pela Redetrel.

String

No

8.2. Sada
Nome

Descrio

cancelamentoVO Objeto com dados do cancelamento da recarga

Tipo
Objeto

Atributos de cancelamentoVO
Nome

Descrio

Tipo

codigoRetorno

Identifica se a operao foi bem sucedida (retornando 0) ou se

houve algum erro (retornando valor <> 0).

Integer

descricaoRetorno

Descrio do retorno.

String

statusRecarga

Indica se a recarga foi ou no autorizada.

String

nsuHost

Nmero sequencial nico da Redetrel

Long

numeroTelefone

Nmero do telefone

String

codigoRegional

Cdigo da regional

Integer

valorFace

Valor da recarga

Long

Cdigos de retorno
Retorno
0
1
8

Mensagem
Sucesso
Token Invlido/Usurio no Autenticado
Falha Geral