Introdução Este documento tem como finalidade demonstrar a implementação da integração entre e-commerces e o meio de pagamento iVarejo via chamada ao ambiente iVarejo através do uso de web-services.
Padrão da integração A integração é realizada por troca de informações via HTTP(S)/SOAP utilizando documentos XML que definem as mensagens de requisição e resposta trocadas entre a plataforma iVarejo e os e-commerces.
Este modelo de integração é suportado especificamente pelo
modelo Síncrono e tem como premissa o controle do fluxo de pagamento pelo software e-Commerce.
Plataforma Tecnológica Todos os serviços fornecidos pala iVarejo seguem arquitetura SOA implementados sobre plataforma Microsoft .NET utilizando WCF (Windows Communication Foundation).
Lista de Métodos do ServiçoA captura via web-services é realizada através de uma lista de métodos que devem ser executados. Abaixo segue a lista de métodos atualmente fornecidos:
- ServiçoCapturaMA.svc
- ObterBoletosCompra
- ObterPlanosPagamentoCompra
Lembre-se que os serviços só funcionarão com os devidos códigos fornecidos pela iVarejo (apenas para clientes em processo de adesão).
Diagrama de Sequência Abaixo temos o diagrama de sequência que demonstra a ordem de execução dos métodos fornecidos com as suas respectivas mensagens, trocadas entre o e-Commerce e a plataforma iVarejo.
1 - ServicoCapturaMA.svc Métodos Fornecidos 1.1 - EnviarDadosCompraEnvia os dados da compra, iniciando o processo de captura.
- Mensagem de requisição: DadosCompra
- Mensagem de resposta: RetornoEnvioDadosCompra
- Erro na execução do serviço: ErroServico
a) Diagrama:
b) Dicionário: DadosCompra
Atributo
|
Descrição |
Tipo |
Obrigatório |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
Sim |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID | Sim |
Pedido
|
Dados do pedido do Consumidor
|
Pedido |
Sim |
Pedido
Atributo
|
Descrição |
Tipo |
Obrigatório |
NumeroPedido
|
Número do pedido |
string |
Sim |
ValorPedido
|
Valor total do pedido |
decimal |
Sim |
ValorPrestação
|
Valor de cada prestação
|
decimal |
Não |
NumeroPrestacoes
|
Numero de prestações escolhida pelo consumidor |
int |
Sim |
EnderecoEntrega
|
Dados do endereço de entraga do pedido |
Endereco |
Não |
EnderecoResidencial
|
Dados do endereço residêncial do consumidor |
Endereco |
Sim |
EnderecoCobranca
|
Dados do endereço cobrança do consumidor |
Endereco |
Sim |
ItensPedido
|
Lista de itens(produtos) que compõe o pedido |
ItemPedido |
Sim |
DadosConsumidor
Atributo
|
Descrição |
Tipo |
Obrigatório |
Nome
|
Nome do Consumidor |
string |
Sim |
NomeMae
|
Nome da Mãe do Consumidor |
string |
Não |
NomePai
|
Nome do Pai do Consumidor |
string |
Não |
TipoPessoa
|
Tipo da Pessoa - (F:Pessoa Física / J:Pessoa Jurídica) |
string |
Sim |
DataNascimento
|
Data de Nascimento do Consumidor
|
Data (yyyy-mm-ddThh:mm:ss) |
Sim |
CpfCnpj
|
CPF do consumidor (sem formatação) |
string |
Sim |
Email
|
Email do consumidor |
string |
Sim |
Sexo
|
Sexo do consumidor - (M:Masculino / F:Feminido) |
string |
Sim |
Telefones
|
Lista de Telefones do consumidor |
Telefone |
Sim |
Telefone
Atributo
|
Descrição |
Tipo |
Obrigatório |
Tipo
|
Tipo de Telefone(R:Residêncial / C:Comercial / M:Celular) |
string |
Sim |
DDI
|
DDI do Telefone |
string |
Não |
DDD
|
DDD do Telefone |
string |
Sim |
Ramal
|
Ramal relacionado ao telefone |
string |
Não |
Numero
|
Número do Telefone |
string |
Sim |
Endereco
Atributo
|
Descrição |
Tipo |
Obrigatório |
Logradouro
|
Descrição do Logradouro |
string |
Sim |
Numero
|
Número do logradouro |
string |
Sim |
Complemento
|
Complemento |
string |
Sim |
CEP
|
CEP do endereço (sem formatação) |
string |
Sim |
Bairro
|
Bairro |
string |
Sim |
Cidade
|
Município |
string |
Sim |
UF
|
Unidade Federativa (abreviação) |
string |
Sim |
ItemPedido
Atributo
|
Descrição |
Tipo |
Obrigatório |
Nome
|
Nome do produto |
string |
Sim |
Quantidade
|
Quantidade do produto comprada |
int |
Sim |
ValorUnitario
|
Valor unitário do produto |
decimal |
Sim |
Fabricante
|
Nome do Fabricante |
string |
Não |
Modelo
|
Código do Modelo do produto |
string |
Não |
PartNumber
|
Part Number do produto |
string |
Não |
RetornoEnvioDadosCompra
Atributo
|
Descrição |
Tipo |
NumeroPedido
|
Número do pedido |
string |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoRetorno
|
Código que identifica o tipo de retorno
|
string |
DataHoraProcessamento
|
Data e hora do retorno o processamento |
Data (yyyy-mm-ddThh:mm:ss) |
IdTransacao
|
Número da transação interna gerada pelo iVarejo |
GUID |
QuantidadeParcelas
|
Quantidade de parcelas escolhida pelo consumidor |
int |
ValorParcela
|
Valor da parcela |
decimal |
CodigoRetorno:
- IVJ.ECOMMERCE.RET.001: Cadastro de pedido realizado com sucesso. Chamar método ProcessarTransacaoCompra.
Caso ocorra algum problema no processo de envio de dados do pedido uma mensagem ErroServico será retornada.
ErroServico
Atributo
|
Descrição |
Tipo |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoExcecao
|
Código da exceção |
string |
Excecao
|
Exceção retornada do processamento da iVarejo |
Excecao |
Mensagem
|
Mensagem curta descritiva do erro capturado |
string
|
Exceções (Codigo da exceção - Mensagem):
- IVJ.ECOMMERCE.ERR.001 - "Acesso não autorizado."
- IVJ.ECOMMERCE.INTERNALFAULT - "Erro interno."
A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.
Excecao
Atributo
|
Descrição |
Tipo |
MensagemExcecao
|
Mensagem de erro |
string |
StackTrace
|
Dump da stack de execução |
string |
LocalErro
|
Local onde a exceção foi gerada |
string |
ExcecaoInterna
|
Exceção interna que representa um erro em um subnível de execução |
Excecao |
1.2 - ProcessarTransacaoCompra Avalia os dados do pedido em confrontação com as regras de negócio do cliente e analisa o risco e a possibilidade de fraude.
- Mensagem de requisição: DadosTransacaoCompra
- Mensagem de resposta: RetornoProcessamentoCompra
- Erro na execução do serviço: ErroServico
a) Diagrama:
b) Dicionário:DadosTransacaoCompra
Atributo
|
Descrição |
Tipo |
Obrigatório |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
Sim |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID | Sim |
IdTransacao
|
Número da transação interna gerada pelo iVarejo |
GUID |
Sim |
RetornoProcessamentoCompra
Atributo
|
Descrição |
Tipo |
NumeroPedido
|
Número do pedido |
string |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoRetorno
|
Código que identifica o tipo de retorno
|
string |
DataHoraProcessamento
|
Data e hora do retorno o processamento |
Data (yyyy-mm-ddThh:mm:ss) |
IdTransacao
|
Número da transação interna gerada pelo iVarejo |
GUID |
IdFinanciamento
|
Número identificador interno da compra |
int |
PagamentoAutorizado
|
Identifica se o pagamento foi ou não autorizado |
bool |
CodigoRetorno:
- IVJ.ECOMMERCE.RET.002 - Compra autorizada via Boleto Parcelado iVarejo. Chamar método ObterBoletosCompra.
- IVJ.ECOMMERCE.RET.003 - Compra não autorizada via Boleto Parcelado iVarejo. Não chamar método ObterBoletosCompra.
Caso ocorra algum problema no processo de envio de dados do pedido uma mensagem ErroServico será retornada.
ErroServico
Atributo
|
Descrição |
Tipo |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoExcecao
|
Código da exceção |
string |
Excecao
|
Exceção retornada do processamento da iVarejo |
Excecao |
Mensagem
|
Mensagem curta descritiva do erro capturado |
string
|
Exceções (Codigo da exceção - Descrição do Erro):
- IVJ.ECOMMERCE.INTERNALFAULT - "Erro interno."
- IVJ.ECOMMERCE.ERR.001 - "Acesso não autorizado."
- IVJ.ECOMMERCE.ERR.002 - "O pedido referente a transação <IdTransacao> não foi localizado."
- IVJ.ECOMMERCE.ERR.003 - "Erro na finalização processo captura."
- IVJ.ECOMMERCE.ERR.004
- "|MSG1:A data da entrada não pode ser menor do que a data de hoje."
- "|MSG4:O financiamento deve ter um máximo de <Quantidade máxima de parcelas da regra de negócio> parcelas."
- "|MSG5:O financiamento deve ter um mínimo de <Quantidade mínima de parcelas da regra de negócio> parcelas."
- "|MSG6:O financiamento deve ter um valor máximo de <Valor máximo para o parcelamento da regra de negócio>."
- "|MSG7:O financiamento deve ter um valor mínimo de <Valor mínimo para o parcelamento da regra de negócio>."
- "|MSG8:O CPF informado não é válido."
A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.
Excecao
Atributo
|
Descrição |
Tipo |
MensagemExcecao
|
Mensagem de erro |
string |
StackTrace
|
Dump da stack de execução |
string |
LocalErro
|
Local onde a exceção foi gerada |
string |
ExcecaoInterna
|
Exceção interna que representa um erro em um subnível de execução |
Excecao |
1.3 - ObterBoletosCompraEnvia os boletos do pedido para o email cadastrado do consumidor.
- Mensagem de requisição: DadosTransacaoCompra
- Mensagem de resposta: RetornoBoletosCompra
- Erro na execução do serviço: ErroServico
a) Diagrama:
b) Dicionário:DadosTransacaoCompra
Atributo
|
Descrição |
Tipo |
Obrigatório |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
Sim |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID | Sim |
IdTransacao
|
Número da transação interna gerada pelo iVarejo |
GUID |
Sim |
RetornoBoletosCompra
Atributo
|
Descrição |
Tipo |
URLBoletos
| URL para visualização dos boletos gerados para a transação em questão
| string |
MensagemRetorno
|
Retorma mensagem de confirmação de envio boletos por email |
string |
ErroServico
Atributo
|
Descrição |
Tipo |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoExcecao
|
Código da exceção |
string |
Excecao
|
Exceção retornada do processamento da iVarejo |
Excecao |
Mensagem
|
Mensagem curta descritiva do erro capturado |
string
|
Exceções (Codigo da exceção - Descrição do Erro):
- IVJ.ECOMMERCE.INTERNALFAULT - "Erro interno."
- IVJ.ECOMMERCE.ERR.001 - "Acesso não autorizado."
A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.
Excecao
Atributo
|
Descrição |
Tipo |
MensagemExcecao
|
Mensagem de erro |
string |
StackTrace
|
Dump da stack de execução |
string |
LocalErro
|
Local onde a exceção foi gerada |
string |
ExcecaoInterna
|
Exceção interna que representa um erro em um subnível de execução |
Excecao |
1.4 - ObterPlanosPagamentoCompraObtêm os planos de pagamento possíveis para um pedido.
- Mensagem de requisição: DadosValorProduto
- Mensagem de resposta: RetornoPlanosPagamento
- Erro na execução do serviço: ErroServico
a) Diagrama:
b) Dicionário: DadosValorProduto
Atributo
|
Descrição |
Tipo |
Obrigatório |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
Sim |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID | Sim |
CpfConsumidor
|
CPF do consumidor |
string |
Sim |
ValorProduto
|
Valor do Produto |
decimal |
Sim |
RetornoPlanosPagamento
Atributo
|
Descrição |
Tipo |
PlanosPagamento |
Coleção de planos de pagamento |
Collection <PlanoPagamento> |
PlanoPagamento
Atributo
|
Descrição |
Tipo |
NumeroParcelas
|
Número de parcelas de um plano |
int |
ValorParcela
|
Valor da parcela de um plano |
decimal |
ErroServico
Atributo
|
Descrição |
Tipo |
CodigoEntidade
|
Código gerado pela iVarejo para identificar o e-Commerce |
GUID |
CodigoCanal | Código gerado pela iVarejo para identificar o Canal de Venda | GUID |
CodigoExcecao
|
Código da exceção |
string |
Excecao
|
Exceção retornada do processamento da iVarejo |
Excecao |
Mensagem
|
Mensagem curta descritiva do erro capturado |
string
|
Exceções (Codigo da exceção - Descrição do Erro):
- IVJ.ECOMMERCE.INTERNALFAULT - "Erro interno."
- IVJ.ECOMMERCE.ERR.001 - "Acesso não autorizado."
- IVJ.ECOMMERCE.ERR.002 - "O pedido referente a transação <IdTransacao> não foi localizado."
A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.
Excecao
Atributo
|
Descrição |
Tipo |
MensagemExcecao
|
Mensagem de erro |
string |
StackTrace
|
Dump da stack de execução |
string |
LocalErro
|
Local onde a exceção foi gerada |
string |
ExcecaoInterna
|
Exceção interna que representa um erro em um subnível de execução |
Excecao |
Observações
- As mensagens de retorno devem ser devidamente tratadas na implementação do e-Commerce para prover uma melhor resposta aos usuários finais.