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
- Pedido.svc
- Captura.svc
- Conciliacao.svc
- 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: RequisicaoPedidosEfetivadosNaoEfetivadosAtributo
| 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 |
RespostaPedidosEfetivadosNaoEfetivados Atributo | Descrição | Tipo |
ListaPedidosEfetivadosNaoEfetivados
| Lista com os pedidos que foram efetivados e/ou não efetivados na data consultada | Collection <Pedido> |
PedidoAtributo
| 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 |
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.
ValidationFaultAtributo
| 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.