# Pedidos

> Ciclo de vida completo de um pedido entre a loja e o ERP — criação, reserva de estoque, número no ERP, status, nota fiscal, cancelamento e alteração.

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


## Resumo em 30 segundos

1. O cliente fecha o pedido na loja. A ViaShopModa **já baixa o estoque** dos itens nesse momento.
2. A ViaShopModa envia um **webhook** ao ERP com o pedido — **em qualquer status**, inclusive não pago.
3. O ERP cria o pedido no sistema dele e **reserva o estoque**.
4. O ERP informa à ViaShopModa o número que o pedido ganhou no ERP: [`pedido/associar_codexterno`](#3-o-erp-informa-o-numero-do-pedido-no-erp).
5. Conforme o pedido anda no ERP, o ERP atualiza o status na loja: [`pedido/atualizar`](#4-o-erp-atualiza-o-status).
6. Ao faturar, o ERP envia a nota fiscal: [`pedido/atualizar_notafiscal`](#5-nota-fiscal).

Quando a vendedora **altera** um pedido, a ViaShopModa **cancela o pedido original e cria um novo** — veja [Alteração de pedido](#alteracao-de-pedido-cancelamento-4-minutos-novo-pedido).

## Quem faz o quê

| Passo | Responsável | Como |
|---|---|---|
| Baixar estoque ao criar o pedido | ViaShopModa | Automático |
| Avisar o ERP de pedido novo, cancelado ou alterado | ViaShopModa | Webhook |
| Criar o pedido no ERP e reservar o estoque | ERP | No sistema do ERP |
| Informar o número do pedido no ERP | ERP | `POST pedido/associar_codexterno` |
| Atualizar status (pago, em transporte, entregue, cancelado) | ERP | `POST pedido/atualizar` |
| Informar a nota fiscal | ERP | `POST pedido/atualizar_notafiscal` |
| Cancelar o pedido e liberar a reserva quando receber o webhook de cancelamento | ERP | No sistema do ERP |
| Enviar à loja o estoque atualizado depois de qualquer movimentação | ERP | `POST estoque/atualizar` |

## Fluxo de um pedido novo

```text
Cliente          Loja (ViaShopModa)                      ERP
   |  fecha pedido     |                                     |
   |------------------>|                                     |
   |                   | baixa o estoque dos itens           |
   |                   |-- webhook: pedido 111111 ---------->|
   |                   |                                     | cria o pedido e reserva o estoque
   |                   |<-- POST pedido/associar_codexterno -| {"numero_pedido":"111111","numero_pedido_externo":"ERP-98765"}
   |                   |                                     |
   |                   |<-- POST pedido/atualizar -----------| status "Pagamento autorizado, aguardando envio"
   |                   |<-- POST pedido/atualizar_notafiscal-| URL da nota
   |                   |<-- POST pedido/atualizar -----------| status "Pedido em transporte" + rastreio
   |                   |<-- POST pedido/atualizar -----------| status "Pedido entregue"
```

### 1. O pedido é criado na loja

A ViaShopModa baixa o estoque assim que o pedido é criado, **antes do pagamento**. Por isso o ERP também precisa receber e reservar o pedido desde a criação.

> **Não espere o pedido ser pago para levá-lo ao ERP.** Se o ERP só importar pedidos pagos, durante esse intervalo ele vai considerar disponíveis peças que a loja já vendeu, e os saldos dos dois sistemas vão divergir.

### 2. O ERP recebe o webhook

O formato do webhook de pedido está na [documentação de webhooks](https://documenter.getpostman.com/view/9868245/2sBXcHhyfT).

Se precisar dos dados completos do pedido (cliente, itens, pagamento, vendedor), consulte:

```bash
curl "https://api.viashopmoda.com.br/via/pedido/consultar/SEU_TOKEN?pedido=111111"
```

O número do pedido na ViaShopModa tem sempre **6 dígitos** (ex.: `111111`).

### 3. O ERP informa o número do pedido no ERP

Depois de criar o pedido, o ERP envia o número que o pedido ganhou no sistema dele. É isso que liga os dois registros.

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/pedido/associar_codexterno/{TOKEN}` |
| **Corpo** | Objeto JSON `{ ... }`, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |
| **Processamento** | **Assíncrono.** A resposta confirma que a ação entrou na fila (`automacao_id`). Acompanhe com [`automacao/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/automacao/consultar&formato=md). |


```json
{
  "numero_pedido": "111111",
  "numero_pedido_externo": "ERP-98765"
}
```

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `numero_pedido` | string | **sim** | Número do pedido na ViaShopModa (6 dígitos). |
| `numero_pedido_externo` | string | **sim** | Número do pedido no ERP. |

A resposta de sucesso confirma que a associação **entrou na fila** e será gravada em seguida:

```json
{
  "retorno": true,
  "msg": "A automação 'pedido.cadastrar_codexterno' foi cadastrada e será processada.",
  "automacao_id": "123456",
  "consultar_automacao": "via/automacao/consultar/{TOKEN}?id=123456"
}
```

Para confirmar que foi gravada, use [`automacao/consultar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/automacao/consultar&formato=md) ou consulte o pedido por `?numero_pedido_externo=`.

Respostas de erro (`msg_erro`) — estas são verificadas na hora, antes de entrar na fila:

| Mensagem | Significado |
|---|---|
| `numero_pedido e numero_pedido_externo são obrigatórios.` | Faltou um dos dois campos. |
| `associação já realizada.` | Esse par já estava associado. Pode tratar como sucesso. |
| `numero_pedido_externo já associado ao pedido NNNNNN.` | O número do ERP já está ligado a **outro** pedido. Verifique o ERP. |
| `pedido não encontrado.` | O `numero_pedido` não existe na loja. |
| `pedido já associado ao numero_pedido_externo:XXXX.` | O pedido já tem outro número de ERP. Um pedido só aceita uma associação. |

### 4. O ERP atualiza o status

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/pedido/atualizar/{TOKEN}` |
| **Corpo** | Objeto JSON `{ ... }`, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |


```json
{
  "pedido": {
    "numero_pedido": "111111",
    "status_pedido": "Pedido em transporte",
    "rastreio_frete": "BR123456789BR"
  }
}
```

`status_pedido` precisa ser **exatamente** um destes textos (com as mesmas maiúsculas e acentos):

| Status | Conta como pago? |
|---|---|
| `Pedido em análise` | não |
| `Aguardando Pagamento` | não |
| `Falha na tentativa de pagamento` | não |
| `Pagamento efetuado, aguardando captura` | sim |
| `Pagamento autorizado, aguardando envio` | sim |
| `Pedido em transporte` | sim |
| `Pedido entregue` | sim |
| `Pedido cancelado` | — |

> **Atenção:** `Aguardando Pagamento` tem o "P" maiúsculo. `Aguardando pagamento` é recusado.

Outros campos aceitos em `pedido/atualizar`: `forma_pagamento`, `url_notafiscal` e, dentro de `subpedido` (ou do próprio `pedido`), `parcelas_pagamento`, `numero_comprovante` e `rastreio_frete`.

**Cancelar pela API devolve o estoque.** Quando o ERP envia `Pedido cancelado`, a ViaShopModa devolve ao estoque da loja os itens que tinham sido baixados. Um pedido cancelado pode voltar para outro status; a loja registra isso nas observações do pedido.

### 5. Nota fiscal

| | |
|---|---|
| **Método** | `POST` |
| **URL** | `https://api.viashopmoda.com.br/via/pedido/atualizar_notafiscal/{TOKEN}` |
| **Corpo** | Objeto JSON `{ ... }`, cabeçalho `Content-Type: application/json` |
| **Token** | Substitua `{TOKEN}` pelo token da loja. Ele vai no caminho da URL, não em cabeçalho. |


```json
{
  "pedido": {
    "numero_pedido": "111111",
    "url_notafiscal": "https://seu-erp.com.br/nfe/35260000000000000000550010000012341000012345.xml"
  }
}
```

Resposta de sucesso: `{"retorno": true, "msg": "Url da nota fiscal cadastrada com sucesso."}`. A URL também pode ir no campo `url_notafiscal` de `pedido/atualizar`.

## Alteração de pedido (cancelamento + 4 minutos + novo pedido)

No atacado é comum a vendedora incluir ou tirar itens depois que o pedido foi feito. A ViaShopModa **não edita** o pedido original: ela **cancela** o original e **cria um pedido novo**, com outro número.

```text
Loja (ViaShopModa)                                    ERP
   | cancela o pedido 111111                         |
   |-- webhook: pedido 111111 cancelado ------------>| cancela no ERP e LIBERA a reserva de estoque
   |                                                 |
   |   ... espera 4 minutos ...                      |
   |                                                 |
   | cria o pedido 111112 (com os itens novos)       |
   |-- webhook: pedido 111112 ---------------------->| cria o pedido e reserva o estoque
   |<-- POST pedido/associar_codexterno -------------| {"numero_pedido":"111112", "numero_pedido_externo":"ERP-98766"}
```

1. **Cancelamento do original.** O ERP precisa cancelar o pedido e liberar a reserva.
2. **Intervalo de 4 minutos.** É só uma margem de segurança: a ViaShopModa **não** recebe confirmação de que o ERP terminou o cancelamento.
3. **Pedido novo.** O ERP cria e reserva como em um pedido novo comum, e associa o número dele.

> **Importante:** processe o cancelamento **antes** de reservar o pedido novo. Se o pedido novo chegar e o cancelamento ainda não tiver sido processado, a mesma peça fica reservada duas vezes.

Para saber qual pedido substituiu o cancelado, consulte o pedido cancelado: a resposta traz `numero_pedido_alterado` com o número do pedido novo.

## Pedidos criados fora da loja

Vendas feitas no ERP, na loja física ou em marketplace podem ser registradas na ViaShopModa com [`pedido/cadastrar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/pedido/cadastrar&formato=md). Esse endpoint **não mexe no estoque**: depois de cadastrar, o ERP envia o saldo novo com `estoque/atualizar`.

## Conferência periódica (reconciliação)

Webhooks podem falhar (ERP fora do ar, timeout). Uma conferência periódica — por exemplo, uma vez por hora — evita pedidos perdidos sem gastar o limite diário:

```bash
curl "https://api.viashopmoda.com.br/via/pedido/consultar/SEU_TOKEN?data_inicial=2026-11-16&data_final=2026-11-16&data_alteracao=S"
```

- `data_alteracao=S` busca pelos pedidos **alterados** no período (não só os criados).
- O resultado é paginado em 20 por página (`pagina=2`, `pagina=3`…).
- **Não** faça essa consulta a cada poucos segundos: o limite de 2.500 requisições por dia é da loja inteira.

## Erros comuns de integração

- Importar no ERP só pedidos pagos. → Estoque divergente. Importe todos, desde a criação.
- Enviar o status com outra grafia (`"pago"`, `"PG"`, `"Aguardando pagamento"`). → Recusado. Use a tabela de status acima. (Os códigos `AN`, `PG`, `EN`… valem **só** em `pedido/cadastrar`.)
- Tratar o pedido novo de uma alteração antes do cancelamento do original. → Reserva em dobro.
- Esquecer o `pedido/associar_codexterno`. → A loja não sabe qual pedido do ERP corresponde a qual, e a conferência fica manual.
- Usar `pedido/cadastrar` para pedidos que **vieram da loja**. → Pedido duplicado. Pedidos da loja já existem; o ERP só associa o número dele.

## Endpoints deste processo

- [`pedido/cadastrar`](https://api.viashopmoda.com.br/docs-api/?p=recursos/pedido/cadastrar&formato=md) — registrar pedido criado fora da loja
- `pedido/consultar` — consultar um pedido, por período, por cliente ou pelo número no ERP
- `pedido/associar_codexterno` — informar o número do pedido no ERP
- `pedido/atualizar` — atualizar status, pagamento, rastreio
- `pedido/atualizar_notafiscal` — informar a nota fiscal
- `estoque/atualizar` — enviar o saldo depois de movimentações
