API ViaShopModa documentação

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.

Ver como Markdown 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.
  5. Conforme o pedido anda no ERP, o ERP atualiza o status na loja: pedido/atualizar.
  6. 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ê #

PassoResponsávelComo
Baixar estoque ao criar o pedidoViaShopModaAutomático
Avisar o ERP de pedido novo, cancelado ou alteradoViaShopModaWebhook
Criar o pedido no ERP e reservar o estoqueERPNo sistema do ERP
Informar o número do pedido no ERPERPPOST pedido/associar_codexterno
Atualizar status (pago, em transporte, entregue, cancelado)ERPPOST pedido/atualizar
Informar a nota fiscalERPPOST pedido/atualizar_notafiscal
Cancelar o pedido e liberar a reserva quando receber o webhook de cancelamentoERPNo sistema do ERP
Enviar à loja o estoque atualizado depois de qualquer movimentaçãoERPPOST 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étodoPOST
URLhttps://api.viashopmoda.com.br/via/pedido/associar_codexterno/{TOKEN}
CorpoObjeto JSON { ... }, cabeçalho Content-Type: application/json
TokenSubstitua {TOKEN} pelo token da loja. Ele vai no caminho da URL, não em cabeçalho.
ProcessamentoAssí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"
}
CampoTipoObrigatórioDescrição
numero_pedidostringsimNúmero do pedido na ViaShopModa (6 dígitos).
numero_pedido_externostringsimNú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:

MensagemSignificado
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étodoPOST
URLhttps://api.viashopmoda.com.br/via/pedido/atualizar/{TOKEN}
CorpoObjeto JSON { ... }, cabeçalho Content-Type: application/json
TokenSubstitua {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):

StatusConta como pago?
Pedido em análisenão
Aguardando Pagamentonão
Falha na tentativa de pagamentonão
Pagamento efetuado, aguardando capturasim
Pagamento autorizado, aguardando enviosim
Pedido em transportesim
Pedido entreguesim
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étodoPOST
URLhttps://api.viashopmoda.com.br/via/pedido/atualizar_notafiscal/{TOKEN}
CorpoObjeto JSON { ... }, cabeçalho Content-Type: application/json
TokenSubstitua {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"}
  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. 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=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 — 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