Nossos Produtos‎ > ‎API iVarejo‎ > ‎

Integração API iVarejo - Versão 1.0

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:
      • Inicial: Pedido que foi capturado mas ainda não teve seus títulos custodiados no banco de custódia de títulos;
      • Em Andamento: Pedido que encontra-se no processo de pagamento das parcelas sem atrasos no pagamento;
      • Primeira parcela não paga: Pedido que não teve a primeira parcela paga;
      • Em Cobrança: Pedido que está em processo de cobrança por atraso de pagamento (boletos fora do prazo de aceite);
      • Finalizado: Pedido finalizado (todos os boletos pagos;
      • Atrasado: Pedido que tem alguns algum de seus boletos não pagos mas dentro da data de aceite de recebimento;
      • 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;

      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 da confirmação 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 - 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.4 - 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
      Status do Recebível:
      • Capturado: estado inicial do recebível quando a captura autoriza o pagamenteo de um pedido pela iVarejo;
      • Em Contra Cobrança: recebível que foi registrado na conta custódia da iVarejo;
      • Performado: recebível que teve seu pagamento realizado;
      • Não performado: recebível não pago após sua data de venciamento;
      • Em processo de baixa: recebível em que foi realizado o comando de baixa da custódia bancária;
      • Baixado da custódia: recebível que teve sua baixa realizada com sucesso;
      • Erro na custódia: erro no registro do recebível na conta custódia da iVarejo;
      • Erro no processo de baixa: erro na execução da baixa da conta custódia da iVarejo;
      • Em alegação pelo consumidor: recebível que foi contestado pelo consumidor.
         

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