Integração API

Introdução

Este documento tem como finalidade demonstrar a implementação da integração com a API da iVarejo.


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 o cliente.


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 Serviços

A IVAREJO fornece uma lista de serviços organizados por Domínio. Abaixo segue a lisa de serviços atualmente fornecidos:
  • BackOffice
    1. Pedido.svc
    2. Captura.svc
    3. Conciliacao.svc
    4. Servicos.svc

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).


- Métodos Fornecidos:


1 - BackOffice :: Pedido.svc


1.1 - ObterStatusPedidoPorCodigoPedido


Obtém o status de um pedido de uma relação Entidade/Canal.
  • Mensagem de requisição: RequisicaoStatusPedidoPorCodigoPedido
  • Mensagem de resposta: RespostaStatusPedidoPorCodigoPedido
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoStatusPedidoPorCodigoPedido

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente  da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 CodigoPedido

  Código do pedido
 string
 Sim


RespostaStatusPedidoPorCodigoPedido

Atributo

 Descrição Tipo
 CodigoPedido

  Código do pedido  GUID
 DataCompra

  Data da compra (captura)  GUID
 Status

  Status do pedido  string
Status do Pedido:
  • Em Cobrança: Pedido que está em processo de cobrança por atraso de pagamento (boletos fora do prazo de aceite);
  • Alerta: Pedido que teve algum evento de inconsistência bancária;
  • Baixado: Pedido que teve seus boletos baixados pela não efetivação da compra pelo pagamento do 1° boleto;
  • Primeira parcela não paga: Pedido que não teve a primeira parcela paga;
  • Atrasado: Pedido que tem alguns algum de seus boletos não pagos mas dentro da data de aceite de recebimento;
  • Finalizado: Pedido finalizado (todos os boletos pagos;
  • Em Andamento: Pedido que encontra-se no processo de pagamento das parcelas sem atrasos no pagamento;

ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoPedido deve conter entre 1 e 50 caracteres."
  • "CodigoCanal inválido."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




1.2 - ObterPedidosPrimeiraParcelaPaga


Lista todos os pedidos de uma relação Entidade/Canal que tiveram a primeira parcela paga em uma determinada data.
  • Mensagem de requisição: RequisicaoPedidosPrimeiraParcelaPaga
  • Mensagem de resposta: RespostaPedidosPrimeiraParcelaPaga
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoPedidosPrimeiraParcelaPaga

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 Data

  Data do pagamento
  data (yyyy-mm-dd)  Sim


RespostaPedidosPrimeiraParcelaPaga

Atributo Descrição Tipo
 ListaPedidosPrimeiraParcelaPaga

  Lista com os pedidos que tiveram a primeira parcela paga na data consultada  Collection
 <PedidoPrimeiraParcela
 Paga>


PedidoPrimeiraParcelaPaga

Atributo

 Descrição Tipo
 DataCaptura

  Data em que o Pedido foi capturado  data (yyyy-mm-dd)
 NumeroPedido

  Código do Pedido  string
 QuantidadeParcelas

  Quantidade de parcelas do Pedido  int
 Valor

  Valor do Pedido
  decimal


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do erro  string
Exceções (Codigo da exceção - Descrição do erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.
 
 
1.3 - ObterPedidosEfetivadosNaoEfetivados 


Lista todos os pedidos de uma relação Entidade/Canal que foram efetivados e/ou não efetivados em determinada data.
  • Mensagem de requisição: RequisicaoPedidosEfetivadosNaoEfetivados
  • Mensagem de resposta: RespostaPedidosEfetivadosNaoEfetivados
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:


b) Dicionário:

RequisicaoPedidosEfetivadosNaoEfetivados

Atributo

DescriçãoTipoObrigatório
 CodigoAplicacao

 Código gerado pela iVarejo para identificar a aplicação cliente da API GUID Sim
 CodigoEntidade

 Código gerado pela iVarejo para identificar o Varejista na plataforma GUID Sim
 CodigoCanal

 Código gerado pela iVarejo para identificar o canal de venda do Varejista GUID Sim
 Data

 Data do pagamento
 data (yyyy-mm-dd) Sim


RespostaPedidosEfetivadosNaoEfetivados

AtributoDescriçãoTipo
 ListaPedidosEfetivadosNaoEfetivados

 Lista com os pedidos que foram efetivados e/ou não efetivados na data consultada Collection
 <Pedido>


Pedido

Atributo

DescriçãoTipo
 DataCaptura

 Data em que o Pedido foi capturado data (yyyy-mm-dd)
 NumeroPedido

 Código do Pedido string
 QuantidadeParcelas

 Quantidade de parcelas do Pedido int
 Valor

 Valor do Pedido
 decimal
 Efetivado Indica se o pedido está efetivado(true) ou não efetivado(false) booleano


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

 Código da exceção string
 Mensagem

 Descrição do erro string
Exceções (Codigo da exceção - Descrição do erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

 Descrição do erro
 string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.


1.4 - ObterPedidosCapturadosPorData


Lista todos os pedidos capturados em uma determinada data de uma relação Entidade/Canal.
  • Mensagem de requisição: RequisicaoPedidosCapturadosPorData
  • Mensagem de resposta: RespostaPedidosCapturadosPorData
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoPedidosCapturadosPorData

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 Data

  Data da captura
  data (yyyy-mm-dd)  Sim


RespostaPedidosCapturadosPorData

Atributo

 Descrição Tipo
 ListaPedidosCapturados

  Lista com os pedidos que capturados na data consultada  Collection
<PedidoCapturado>


PedidoCapturado

Atributo

 Descrição Tipo
 CodigoPedido

  Código do Pedido  string
 DataCaptura

  Data em que o pedido foi capturado  data (yyyy-mm--dd)
 QuantidadeParcelas

  Quantidade de parcelas do Pedido  int
 Valor

  Valor do Pedido  decimal


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."
  • "Data deve ser entre 01/01/2010 e 31/12/2019."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




1.5 - ObterStatusRecebiveisPorCodigoPedido


Lista o status de todos os recebíveis de um pedido de uma relação Canal/Pedido.
  • Mensagem de requisição: RequisicaoStatusRecebiveisPorCodigoPedido
  • Mensagem de resposta: RespostaStatusRecebiveisPorCodigoPedido
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoStatusRecebiveisPorCodigoPedido

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 CodigoPedido

  Código do Pedido  string  Sim


RespostaStatusRecebiveisPorCodigoPedido

Atributo

 Descrição Tipo
ListaStatusRecebiveis Lista com os status dos recebíveis (boletos) de um Pedido Collection
<StatusRecebivel>


StatusRecebivel

Atributo

 Descrição Tipo
 CodigoPedido

  Código do Pedido
  string
 CodigoRecebivel

  Código do recebível (boleto)  string
 DataCompra

  Data da compra  data (yyyy-mm--dd)
 DataPagamento

  Data do pagamento do recebível (boleto), quando já performado  data (yyyy-mm--dd)
 DataVencimento

  Data de vencimento do recebível (boleto)  data (yyyy-mm--dd)
 Status

  Status do Pedido  string


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."
  • "CodigoPedido deve conter entre 1 e 50 caracteres."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




1.6 - CadastrarNotaFiscal


Cadastra a nota fiscal referente à um determinado Pedido.
  • Mensagem de requisição: RequisicaoCadastrarNotaFiscal
  • Mensagem de resposta: RespostaCadastroNotaFiscal
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoCadastroNotaFiscal

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 CodigoPedido

  Código do Pedido  string  Sim
 NumeroNotaFiscal

 Número da nota fiscal
 string Sim
 NotaFiscalXml

 Nota fiscal em formato XML
 xml Não
 NotaFiscalPdf

 Nota fiscal em formato pdf
 byte[] Não

É obrigatório o envio da nota fiscal em formato XML e/ou pdf. Não é possível cadastrar apenas o número da nota fiscal.


RespostaCadastroNotaFiscal

Atributo

 Descrição Tipo
NotaFiscalCadastrada

  Confirmação do cadastro da nota fiscal.
 bool


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."
  • "CodigoPedido deve conter entre 1 e 50 caracteres."
  • "NumeroNotaFiscal deve conter entre 1 e 50 caracteres."
  • "O cadastro de uma NotaFiscalXml e/ou uma NotaFiscalPdf é obrigatório."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




2 - BackOffice :: Captura.svc


2.1 - ObterStatusCapturaPorCodigoPedido


Obtêm o status da captura através de uma relação Canal/Pedido.
  • Mensagem de requisição: RequisicaoStatusCapturaPorCodigoPedido
  • Mensagem de resposta: RespostaStatusCapturaPorCodigoPedido
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoStatusCapturaPorCodigoPedido

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 CodigoCanal

  Código gerado pela iVarejo para identificar o canal de venda do Varejista  GUID  Sim
 CodigoPedido

  Código do Pedido  string  Sim


RespostaStatusCapturaPorCodigoPedido

Atributo

 Descrição Tipo
 AprovacaoRiscoCredito

  Indica se houve ou não aprovação na análise de risco  boolean
 AprovacaoRiscoFraude

  Indica se houve ou não aprovação na análise de fraude  boolean
 CodigoPedido

  Código do Pedido  string
 DataCaptura

  Data da captura do Pedido  data (yyyy-mm-dd)
 ModeloFraude

  Nome do modelo utilizado para análise de fraude  string
 ModeloRisco

  Nome do modelo utilizado para análise de risco  string
 ScoreModeloFraude

  Score (pontuação) da análise de fraude  int
 ScoreModeloRisco

  Score (pontuação) da análise de risco  int


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "CodigoCanal inválido."
  • "CodigoPedido deve conter entre 1 e 50 caracteres."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




3 - BackOffice :: Conciliacao.svc


3.1 - ObterConciliacaoPorAnoMes


Obtêm a conciliação de um determinado mês/ano.
  • Mensagem de requisição: RequisicaoConciliacaoPorAnoMes
  • Mensagem de resposta: RespostaConciliacaoPorAnoMes
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoConciliacaoPorAnoMes

Atributo Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente  da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 Ano

  Ano  int  Sim
 Mes

  Mês  int  Sim


RespostaConciliacaoPorAnoMes

Atributo

 Descrição Tipo
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  string
 QuantidadeRecebiveisPlanejado

  Quantidade de recebíveis planejados para o ano e mês consultado  int
 QuantidadeRecebiveisRealizado

  Quantidade de recebíveis realizados (performados) para o ano e mês consultado  int
 ValorPlanejado

  Valor total planejado  decimal
 ValorRealizado

  Valor total realizado (performado)  decimal
 Ano

 Ano int
 Mes

 Mês int


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "Ano deve ser entre os valores 2010 e 2019."
  • "Mês inválido."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.




4 - BackOffice :: Servicos.svc


4.1 - ObterExtratoUsoServicosPorCodigoEntidade


Obtêm o extrato de uso de serviços de um determinado mês/ano.
  • Mensagem de requisição: RequisicaoExtratoUsoServicosPorCodigoEntidade
  • Mensagem de resposta: RespostaExtratoUsoServicosPorCodigoEntidade
  • Erro na execução do serviço: ErroServico
  • Erro de validação de parâmetros: ValidationFault


a) Diagrama:



b) Dicionário:

RequisicaoExtratoUsoServicosPorCodigoEntidade

Atributo

 Descrição Tipo Obrigatório
 CodigoAplicacao

  Código gerado pela iVarejo para identificar a aplicação cliente  da API  GUID  Sim
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  GUID  Sim
 Ano

  Ano  int  Sim
 Mes

  Mês  int  Sim


RespostaExtratoUsoServicosPorCodigoEntidade

Atributo

 Descrição Tipo
 ListaExtratoUsoServicos

  Lista com o extrato do uso de serviços  Collection
<ExtratoUsoServicos>


ExtratoUsoServico

Atributo

 Descrição Tipo
 CodigoEntidade

  Código gerado pela iVarejo para identificar o Varejista na plataforma  string
 Credito

  Valor de crédito (caso seja uma operação de crédito)  decimal
 Data

  Data da utilização do serviço  data (yyyy-mm-dd)
 Debito

  Valor de débito (caso seja uma operação de débito)  decimal
 Operacao

  Descrição da operação  string
 Saldo

  Saldo da conta referente ao CodigoEntidade consultado  decimal


ErroServico

Atributo

Descrição Tipo
 CodigoExcecao

  Código da exceção  string
 Mensagem

  Descrição do Erro  string
Exceções (Codigo da exceção - Descrição do Erro):
  • IVJ.API.ERR.001 - "Acesso não autorizado."
  • IVJ.API.INTERNALFAULT - "Erro interno."

A mensagem ErroServico é enviada encapsulada em uma instância do tipo FaultException.

ValidationFault

Atributo

Descrição Tipo
 Detail.Details[]

  Descrição do erro
  string

Exceções (Descrição do Erro):
  • "CodigoAplicacao inválido."
  • "CodigoEntidade inválido."
  • "Ano deve ser entre os valores 2010 e 2019."
  • "Mês inválido."

A mensagem ValidationFault é enviada encapsulada em uma instância do tipo FaultException.