Roteiro de integração com Ecom - Varejonline/api GitHub Wiki

Roteiro de integração com ecom

Preparamos um roteiro para direcionamento da construção de integrações com plataformas de e-commerce.

Escopo da integração

  1. Integração dos produtos da VO para o Ecom
  2. Integração da posição de estoque da VO para o Ecom
  3. Integração dos clientes do Ecom para a VO
  4. Integração das vendas do Ecom para a VO
  5. Integração das notas fiscais do VO para o Ecom
  6. Integração das transições de status dos pedidos entre os sistemas
  7. Integração da etiqueta de transporte do Ecom (TMS) para a VO
  8. Cancelamento de pedidos

1 - Integração dos produtos VO para Ecom

Aplicável nos cenários em que o cadastro do produto do ecommerce será alimentado pelo ERP VO.

Endpoint e fluxo:

Utilize este endpoint para coletar os produtos novos e alterados no ERP VO.

Sugerimos o uso dos seguintes filtros:

  • somenteComFotos: Filtra somente produtos com fotos (true) ou todos (false)
  • somenteEcommerce: Filtra somente produtos integráveis no ecommerce (true) ou todos (false)
  • somenteMarketplace: Filtra somente produtos integráveis no marketplace (true) ou todos (false)

No cadastro de produtos do varejOnline é possível informar quais produtos fazem parte do catálogo disponibilizado online. Caso o cliente utilize esse recurso, a integração pode captar apenas dados de produtos marcados utilizando as flags citadas.

O cadastro de produtos opera no sistema de webhooks, portanto, pode ser contruído um fluxo de integração unitário para acobertar integrações das alterações ou criações de produtos.

2 - Integração da posição de estoque da VO para o Ecom

Objetivo: Manter a posição de estoque do ecom alinhado ao saldo em estoque disponível na loja física ou no estoque que atende o ecom.

Endpoint e fluxo:

Utilize este endpoint para coletar as atualizações de estoque das mercadorias no ERP VO.

Sugerimos o uso dos seguintes filtros:

  • somenteEcommerce: Permite filtrar somente produtos integráveis no ecommerce (true) ou todos (false)
  • somenteMarketplace: Permite filtrar somente produtos integráveis no marketplace (true) ou todos (false)

Lembrando que para utilizar esse recurso é necessário que o cliente informe quais produtos fazem parte do seu catálogo online.

Visto que o controle de estoques não opera no sistema de webhooks, sugerimos o uso da coleta incremental.

3 - Integração dos clientes do Ecom para a VO

Objetivo: Integrar o cliente associado aos pedidos para viabilizar a integração dos pedidos.

Endpoints e fluxo:

Utilize o GET para verificar se o cadastro do cliente jé existe no VO. Isso pode ser feito de forma simples utilizando o parâmetro de consulta "documento".

Caso o retorno da API seja vazio, indicando que o cadastro é inexistente, utilize o POST para gravar o novo cadastro.

Caso o retorno da API seja o cadastro do cliente previamente realizado no ERP, atualize os dados do cliente e efetue o PUT do cadastro.

4 - Integração das vendas do Ecom para a VO

Objetivo: Integrar as vendas realizadas no ecom para o ERP efetuar o faturamento.

Endpoints e fluxo:

Para cenários de estoque compartilhado entre loja física e virtual, sugerimos a criação da reserva do estoque durante o período de autorização de pagamento da venda no ecom, para assegurar que a peça não seja vendida na loja física.

Este mecanismo de reserva só opera se o ERP do cliente está parametrizado para trabalhar apenas com estoque positivo, impedindo a venda de peças sem estoque.

Para executar o fluxo, assim que o pedido for colocado no e-commerce, antes mesmo da confirmação do pagamento, inclua no VarejOnline um orçamento de venda com reserva de estoque pelo endpoint POST Orçamento. Lembre-se de informar true no atributo "reservarEstoque". Isso marcará o saldo consumido na venda pendente do ecom como reservado na loja física, impedindo sua venda no PDV.

Uma vez confirmado o pagamento no ecom, faça a deleção do orçamento pelo endpoint DELETE Orçamentos e logo em seguida, cadastre o pedido associado à venda no VO pelo endpoin POST Pedido.

Uma boa prática ao colocar o orçamento e o pedido é utilizar o atributo "numeroPedidoCliente" nos dois endpoints. Utilize esse campo para informar o número do pedido no ecommerce. Dessa forma, antes de realizar o POST, pode ser realizado um GET com o parâmetro de consulta "numeroPedidoCliente" para checar se o pedido já foi previamente integrado, impedindo a integração em duplicidade.

No POST do pedido, algumas opções são relevantes e precisam ser observadas.

Emissão automática da nota fiscal

Caso todos os dados necessários para emissão da nota fiscal estejam presentes no pedido colocado no ERP, é possível solicitar a emissão automática da nota fiscal informando true no atributo "emitirNotaFiscal". Isso fará com que assim que o pedido for salvo, o sistema já emita a nota fiscal e efetue uma consulta de status depois de alguns segundos. Dessa forma, todo o fluxo de emissão da nota é automatizado.

Dados adicionais de controle nos pedidos

Ao colocar um pedido no ERP é possível informar alguns campos úteis para o gestor controlar suas vendas no ecom, como:

  • origem: origem da venda (ECOMMERCE ou MARKETPLACE)
  • tipo: tipo da venda (NORMAL, SHIP_FROM_STORE, CLICK_COLLECT)
  • intermediador: intermediador da venda (informar id ou documento)

Essas informações vão auxiliar a loja nos processos seguintes de preparação, separação e envio das mercadorias.

O endpoint também conta com o campo "enderecoEntrega", para casos de vendas onde o endereço do comprador (Informado no endpoint de cadastro e atualização do Terceiro) é diferente do endereço de entrega das mercadorias.

Pedidos que são presentes para terceiros

Ao gravar um pedido que será um presente para uma pessoa diferente do comprador, é possível marcar o atributo "emitirNotaFiscalPresente". Dessa forma será possível emitir a nota fiscal de presente para entrega para o destinário final.

Comunicação de notas por email

Caso o ecom já envie as notas fiscais para o email dos clientes, pode ser desejável evitar que o VarejOnline também envie a mesma nota. Isso pode ser feito informando false no atributo "enviarEmailNota" no post do pedido.

5 - Integração das notas fiscais do VO para o Ecom

Objetivo: Após emitidas as notas fiscais de venda no ERP, precisa ser enviado o documento ao Ecom.

Endpoints e fluxo:

Existem duas formas de obter o doc fiscal. O primeiro é obter os dados da nota fiscal pelo GET de notas fiscais. Todas as informações relevantes da nota estão presentes no objeto retornado. A segunda opção é coletar o XML do documento (Mais utilizado).

Como os pedidos colocados no ERP, quando alterados, operam no sistema de webhooks, é possível criar um listener de pedidos e assim que uma nota fiscal for associada ao pedido, o atributo "notasFiscais" do corpo do pedido retornado informará o ID na nota fiscal associada e com esse ID é possível coletar os dados da nota pelos dois endpoints anteriores. Como ao salvar um novo pedido foi informado o número do pedido no ecom dentro do atributo "numeroPedidoCliente", é possível filtrar apenas os pedidos relevantes no fluxo de ecom.

6 - Integração das transições de status dos pedidos entre os sistemas

Um pedido no VO pode ter seu status constantemente alterado, com base na posição do pedido dentro do workflow de pedidos de ecommerce. Da mesma forma, algumas mudanças de status no ecom podem ser informadas em pedidos já colocados no ERP. Para isso, utilize o endpoint POST Pedidos alterar status para alterar o status de um pedido já integrado no ERP ou ao obter um webhook de alteração de pedidos do ERP, analise o atributo "statusVenda" do corpo do pedido lido para atualizar o status do pedido no ECOM

7 - Integração da etiqueta de transporte do Ecom (TMS) para a VO

Caso sua integração tenha o recurso de integração da etiqueta de transporte, é possível informar a URL para impressão da etiqueta por meio do endpoint POST Pedido atribuir etiqueta. Dessa forma, ao detalhar um pedido no VO com a etiqueta vinculada, o usuário pode clicar no link que levará para a impressão da etiqueta de transporte daquele pedido.

8 - Cancelamento de pedidos

Para cancelar pedidos dentro do prazo de cancelamento legal, utilize o endpoint POST Cancelar pedidos

Outras informações

Consulte a página Endpoints Pedidos para capturar mais algumas dicas relevantes.