O que a integração faz #
A integração mantém a loja virtual e o ERP com os mesmos dados. Cada lado é dono de uma parte:
| Dado | Dono (quem cria e altera) | Direção |
|---|---|---|
| Produtos, variações, fotos | ERP | ERP → loja, pela API |
| Estoque | ERP | ERP → loja, pela API |
| Preços | ERP | ERP → loja, pela API |
| Clientes | Os dois (o cliente pode se cadastrar na loja) | Loja → ERP por webhook; ERP → loja pela API |
| Pedidos feitos na loja | Loja | Loja → ERP por webhook |
| Status, rastreio e nota fiscal do pedido | ERP | ERP → loja, pela API |
| Pedidos feitos fora da loja (opcional) | ERP | ERP → loja, pela API |
API (o ERP chama)
┌────────────────────────────┐
│ produtos, estoque, preços, │
│ clientes, status, NF │
ERP ───┘ └──▶ Loja (ViaShopModa)
◀──┐ ┌───
│ pedido novo / cancelado, │
│ cliente novo, lead, ... │
└────────────────────────────┘
Webhooks (a loja avisa)Ordem de implementação recomendada #
- Leia a Introdução e o Glossário.
- Catálogo — carga inicial de produtos com estoque. Guia Catálogo: carga inicial.
- Estoque e preço contínuos — enviar só o que mudou. Guia Estoque e preço.
- Pedidos — receber por webhook, reservar estoque, devolver número, status e nota. Guia Pedidos.
- Clientes — receber os cadastros da loja e, se for o caso, enviar os do ERP. Guia Clientes.
- Webhooks — configurar as URLs e tratar reenvios. Guia Webhooks.
- Antes de produção — Checklist.
Responsabilidades do ERP #
- Receber os webhooks e responder rápido; processar em segundo plano se precisar.
- Processar todos os pedidos desde a criação, pagos ou não, e reservar o estoque.
- Processar cancelamentos e liberar a reserva — inclusive o cancelamento que acontece quando um pedido é alterado.
- Informar o número do pedido no ERP (
pedido/associar_codexterno) depois de criar cada pedido. - Enviar ao estoque da loja só as variações que mudaram, logo depois de cada movimentação.
- Tratar erros: ler
msg_erro, corrigir e não reenviar a mesma requisição em loop. - Respeitar os limites: 1 requisição por segundo, 2.500 por dia (compartilhado entre todos os tokens da loja), 20 itens por lote.
- Não fazer consultas repetidas para "descobrir novidades" que chegam por webhook.
Responsabilidades da ViaShopModa #
- Baixar o estoque da loja no momento em que o pedido é criado.
- Avisar o ERP por webhook sobre pedidos, clientes, leads e sacolas abandonadas.
- Em alteração de pedido: cancelar o original, esperar 4 minutos e criar o novo.
- Validar cada requisição e responder com o motivo quando recusar.
Por que webhooks e não consultas periódicas #
Consultar a API a cada poucos segundos para ver se há pedido novo consome o limite diário da loja inteira (2.500 requisições, compartilhadas entre todos os tokens). Os webhooks avisam no momento em que algo acontece, sem custo de requisição para o ERP.
Uma conferência periódica com folga (por exemplo, de hora em hora, pedidos alterados no período) é bem-vinda para recuperar webhooks perdidos. O que não deve existir é polling em intervalos curtos.
Se a integração precisar de mais requisições do que o limite, fale com api@viashopmoda.com.br antes de ir para produção: ampliar o limite pode gerar custo adicional de infraestrutura para a loja.