# Integração ERP — visão geral

> O que o ERP envia para a loja, o que a loja avisa ao ERP e a ordem de implementação recomendada.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=guias/integracao-erp · Atualizado em 18/11/2026


## 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 |

```text
              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

1. **Leia** a [Introdução](https://api.viashopmoda.com.br/docs-api/?p=inicio&formato=md) e o [Glossário](https://api.viashopmoda.com.br/docs-api/?p=glossario&formato=md).
2. **Catálogo** — carga inicial de produtos com estoque. Guia [Catálogo: carga inicial](https://api.viashopmoda.com.br/docs-api/?p=guias/catalogo-carga-inicial&formato=md).
3. **Estoque e preço contínuos** — enviar só o que mudou. Guia [Estoque e preço](https://api.viashopmoda.com.br/docs-api/?p=guias/estoque-e-preco&formato=md).
4. **Pedidos** — receber por webhook, reservar estoque, devolver número, status e nota. Guia [Pedidos](https://api.viashopmoda.com.br/docs-api/?p=guias/pedidos&formato=md).
5. **Clientes** — receber os cadastros da loja e, se for o caso, enviar os do ERP. Guia [Clientes](https://api.viashopmoda.com.br/docs-api/?p=guias/clientes&formato=md).
6. **Webhooks** — configurar as URLs e tratar reenvios. Guia [Webhooks](https://api.viashopmoda.com.br/docs-api/?p=guias/webhooks&formato=md).
7. **Antes de produção** — [Checklist](https://api.viashopmoda.com.br/docs-api/?p=guias/checklist-producao&formato=md).

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