Resumo em 30 segundos #
- O cliente fecha o pedido na loja. A ViaShopModa já baixa o estoque dos itens nesse momento.
- A ViaShopModa envia um webhook ao ERP com o pedido — em qualquer status, inclusive não pago.
- O ERP cria o pedido no sistema dele e reserva o estoque.
- O ERP informa à ViaShopModa o número que o pedido ganhou no ERP:
pedido/associar_codexterno. - Conforme o pedido anda no ERP, o ERP atualiza o status na loja:
pedido/atualizar. - Ao faturar, o ERP envia a nota fiscal:
pedido/atualizar_notafiscal.
Quando a vendedora altera um pedido, a ViaShopModa cancela o pedido original e cria um novo — veja Alteração de 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 #
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.
Se precisar dos dados completos do pedido (cliente, itens, pagamento, vendedor), consulte:
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. |
{
"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:
{
"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 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. |
{
"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 Pagamentotem 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. |
{
"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.
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"}- Cancelamento do original. O ERP precisa cancelar o pedido e liberar a reserva.
- Intervalo de 4 minutos. É só uma margem de segurança: a ViaShopModa não recebe confirmação de que o ERP terminou o cancelamento.
- 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. 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:
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=Sbusca 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ódigosAN,PG,EN… valem só empedido/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/cadastrarpara 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— registrar pedido criado fora da lojapedido/consultar— consultar um pedido, por período, por cliente ou pelo número no ERPpedido/associar_codexterno— informar o número do pedido no ERPpedido/atualizar— atualizar status, pagamento, rastreiopedido/atualizar_notafiscal— informar a nota fiscalestoque/atualizar— enviar o saldo depois de movimentações