Integração Web-Services

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ço

A 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:
  1. ServiçoCapturaMA.svc
    • EnviarDadosCompra
    • ProcessarTransacaoCompra
    • 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 - EnviarDadosCompra


Envia 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 - ObterBoletosCompra


Envia 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 - ObterPlanosPagamentoCompra


Obtê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.

ċ
ExemplosIntegracaoEcommerceiVarejo.zip
(182k)
Usuário desconhecido,
19 de abr de 2011 15:17