API ViaShopModa documentação

pedido/cadastrar

Cadastrar pedido criado fora da loja

Registra na loja um pedido que nasceu fora dela (venda no ERP, loja física, marketplace), cadastrando o cliente se ele ainda não existir.

Ver como Markdown Baixar coleção Postman Atualizado em 18/11/2026

O que faz #

Cria um pedido na ViaShopModa a partir dos dados enviados pelo ERP: localiza ou cadastra o cliente, grava o pedido com o status informado e os itens. A loja gera um número de pedido novo (6 dígitos) e devolve na resposta.

Quando usar: a venda aconteceu fora da loja virtual e você quer que ela apareça no histórico da loja e do cliente.

Quando não usar:

  • Para pedidos que vieram da loja — eles já existem. Use pedido/associar_codexterno para ligar ao número do ERP.
  • Para mudar status de um pedido existente — use pedido/atualizar.

Requisição #

MétodoPOST
URLhttps://api.viashopmoda.com.br/via/pedido/cadastrar/{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.

Campos #

Estrutura do corpo JSON:

{
  "cliente": {...}
  "pedido": {...}
  "subpedido": {...}
  "produtos": [ {...}, {...} ]
}

cliente (objeto) #

Dados do cliente, no mesmo formato de cliente/cadastrar. Se o CPF, CNPJ ou e-mail já existir, o cliente existente é usado e não é cadastrado de novo.

CampoTipoObrigatórioLimitesDescrição
cliente.tipo_pessoastringsimmáx. 1'F' = pessoa física: , 'J' = pessoa jurídica e 'E' = cliente do exterior.
cliente.emailstringsimmín. 5, máx. 150Usado como contato e para acessar a loja virtual.
cliente.senhastringsimmín. 4Senha para acessar a loja virtual.
cliente.tipo_clientestringsimmáx. 100Sempre se 'tipo_pessoa'=F será 'Revendedor' e 'tipo_pessoa'=J será 'Lojista'. Somente será alterado se enviado como 'Consignado' e o 'compra_maxima_atacado' passa a ser necessário o envio.
cliente.cpfnumericsimmín. 11, máx. 11Somente números. Obrigatório quando pessoa física.
cliente.nome_completostringsimmáx. 150Nome completo do cliente. Obrigatório quando pessoa física.
cliente.rgstringnãomáx. 25Caso inexistente enviar 'Isento'. Obrigatório quando pessoa física.
cliente.data_nascimentodatesimmáx. 10Formato 'aaaa-mm-dd'. Obrigatório quando pessoa física.
cliente.sexostringsim'Masculino', 'Feminino' ou 'Nenhum'. Obrigatório quando pessoa física.
cliente.cnpjstringsimmín. 14, máx. 14Somente números. Obrigatório quando pessoa jurísica.
cliente.nome_empresastringsimmáx. 150Nome fantasia da empresa. Obrigatório quando pessoa jurídica.
cliente.responsavel_empresastringsimmáx. 150Nome do responsável pela empresa. Obrigatório quando pessoa jurídica.
cliente.iestringsimmáx. 25Caso inexistente enviar 'Isento'. Obrigatório quando pessoa jurídica.
cliente.moedastringnãomáx. 3Para os clientes do exterior, é possível alterar sua moeda enviando o código no padrão ISO 4217. USD para dolar, EUR para euro e etc.
cliente.condicao_diferenciadadoublenãomáx. 11Representa a porcentagem de acréscimo ou desconto nos preços dos produtos.
cliente.compra_minima_atacadodoublenãomáx. 11Valor minimo para compra de atacado.
cliente.compra_maxima_atacadodoublenãomáx. 11Usado para quando tipo_cliente=Consignado, limitando o valor máximo a ser comprado. Se não enviado será zero.
cliente.cepnumericsimmín. 8, máx. 8Somente números no formato '37001000'.
cliente.enderecostringsimmáx. 150Caso cliente do exterior, será usado como endereço completo.
cliente.numerostringsimmáx. 10Não utilizado para clientes do exterior.
cliente.complementostringnãomáx. 50Não utilizado para clientes do exterior.
cliente.bairrostringsimmáx. 50Não utilizado para clientes do exterior.
cliente.cidadestringsimmáx. 50
cliente.estadostringsimmáx. 2Sigla do estado com dois caracteres. Não utilizado para clientes do exterior.
cliente.paisstringnãomáx. 50Para países diferente de 'Brasil' usar o campo cod_pais.
cliente.cod_paisstringnãomáx. 2Código do país no padrão ISO-2, se não enviado será utilizado 'BR'.
cliente.codigo_ddistringnãomín. 1, aceita nullSe não enviado sempre será 55.
cliente.telefone_celularstringsimmáx. 50Se não enviado no formato: '+{CODIGO_DDI}{NUMERO_TELEFONE}' será acrescentado o DDI (relativo ao cod_pais) ao número enviado.
cliente.operadora_celularstringnãomáx. 20Nome da operadora de telefonia. Se não enviado será cadastrado 'Outras'
cliente.utm_sourcestringnãomáx. 70Se enviado é necessário enviar utm_medium e utm_campaign
cliente.utm_mediumstringnãomáx. 70Se enviado é necessário enviar utm_source e utm_campaign
cliente.utm_campaignstringnãomáx. 70Se enviado é necessário enviar utm_source e utm_medium
cliente.crmarraynãoFrases relacionadas ao CRM do cliente
cliente.assinar_newsletterstringnãomáx. 1'S' ou 'N', se não enviado será cadastrado 'N'.
cliente.data_cadastrodatetimenãomáx. 19Data de cadastro do cliente. Padrão DATETIME 'aaaa-mm-dd hh:mm:ss'.
cliente.liberado_para_comprarstringnãomáx. 1Padrão 'N'. Podendo ser 'S' ou 'N'. Onde 'S' está liberado e 'N' NÃO está liberado. Observações: (1) O 'N' não signifca bloqueio algum, mas a não possibilidade de login. (2) Se não enviado será cadastrado como 'N'. (3) Se enviado como 'S' poderá ser alterado caso a cidade ou o estado enviado for considerado uma região exclusiva.
cliente.vendedorobjectnãoObjeto para consulta do vendedor. Poderá ser usado: vendedor.id, vendedor.email ou vendedor.whatsapp para localizar o vendedor a ser atrelado ao cliente. Para consultar o vendedor vendedores/consultar. Se enviar 'sortear' será sorteado entre os vendedores habilitados. Se não existir, cadastro não será vinculado a nenhum vendedor.

pedido (objeto) #

Cabeçalho do pedido: status, valores e endereço de entrega.

CampoTipoObrigatórioLimitesDescrição
pedido.numero_pedido_externostringsimaceita nullCódigo do pedido no sistema de origem
pedido.status_pedidostringsimmáx. 50Opções de status: 'AN' = Análise, 'PG' = Pago ou 'EN' = Entregue.
pedido.url_notafiscalstringnãomáx. 200URL completa da nota fiscal do pedido. Usado quando o pedido já estiver pago/faturado.
pedido.data_pedidodatesimmáx. 11Formato 'aaaa-mm-dd'.
pedido.tipo_fretestringnãomáx. 50Opcional para 'status_pedido' = 'EN', se não informado será cadastrado valor padrão.
pedido.valor_pedidodoublesimmáx. 11Obrigatório para 'status_pedido' = 'EN' e 'PG'.
pedido.valor_descontodoublesimmáx. 11Obrigatório para 'status_pedido' = 'EN' e 'PG'. Caso não tenha enviar '0.00'
pedido.valor_fretedoublesimmáx. 11Obrigatório para 'status_pedido' = 'EN'.
pedido.valor_totaldoublesimmáx. 11Valor total do pedido. Somatória dos produtos + 'valor_pedido' - 'valor_desconto' + 'valor_frete'.
pedido.cep_entreganumericsimmín. 8, máx. 8Somente números no formato '37001000'.
pedido.endereco_entregastringsimmáx. 150Caso cliente do exterior, será usado como endereço completo.
pedido.numero_entregastringsimmáx. 10Não utilizado para clientes do exterior.
pedido.complemento_entregastringnãomáx. 50Não utilizado para clientes do exterior.
pedido.bairro_entregastringsimmáx. 50Não utilizado para clientes do exterior.
pedido.cidade_entregastringsimmáx. 50
pedido.estado_entregastringsimmáx. 2Sigla do estado com dois caracteres. Não utilizado para clientes do exterior.

subpedido (objeto) #

Tipo de venda, pagamento e rastreio.

CampoTipoObrigatórioLimitesDescrição
subpedido.tipo_pedidostringsimmáx. 50'A' = Atacado e 'V' = Varejo. Se não enviado, será cadastrado como 'Atacado'.
subpedido.parcelas_pagamentointegernãomáx. 2Número de parcelas.
subpedido.rastreio_fretestringnãomáx. 100Código de rastreamento do pedido na transportadora.

produtos[] (lista) #

Itens do pedido. Não enviar quando pedido.tipo = "compra_rapida".

CampoTipoObrigatórioLimitesDescrição
produtos[].quantidadeintegersimQuantidade do produto no pedido.
produtos[].precodoublesimPreço unitário do produto.
produtos[].cod_barrasstringnãoCódigo de barras do produto.

Regras (valem acima da tabela) #

Estas regras foram conferidas com o código da API. Quando a descrição de um campo na tabela disser algo diferente, vale o que está aqui.

pedido.status_pedido — use um destes códigos (não o nome do status):

CódigoStatus gravadoConta como pago?
ANPedido em análisenão
AGAguardando Pagamentonão
PAPagamento autorizado, aguardando envionão (ver nota)
PGPagamento autorizado, aguardando enviosim
ETPedido em transportesim
ENPedido entreguesim

Nota: PA grava o mesmo status de PG, mas sem marcar o pedido como pago. Em caso de dúvida, use PG.

Para clientes do exterior (tipo_pessoa = "E"), CPF, CNPJ, RG, CEP, número, complemento, bairro e estado deixam de ser obrigatórios.

subpedido.tipo_pedido — obrigatório: "A" (atacado) ou "V" (varejo). Qualquer outro valor, ou não enviar, é recusado. (A descrição antiga dizia que o padrão era atacado; não é.)

Valores — a API confere duas contas, com 2 casas decimais:

  1. pedido.valor_pedido = soma de quantidade × preco de todos os itens de produtos.
  2. pedido.valor_total = valor_pedido − valor_desconto + valor_frete.

Envie valor_desconto e valor_frete como 0 quando não houver.

Itens (produtos[]) — cada item é localizado pelo cod_barras (o mesmo código de barras cadastrado na variação do produto). Envie cod_barras em todos os itens, mesmo a tabela mostrando "não". Se preco vier vazio, a loja usa o preço de atacado do produto.

pedido.numero_pedido_externo — obrigatório e único. É recusado se já estiver associado a outro pedido.

Cliente — se o CPF, CNPJ ou e-mail já existir na loja, o cliente existente é usado e os dados enviados não alteram o cadastro. Os campos de pessoa física (cpf, nome_completo, data_nascimento, sexo, rg) só são exigidos quando tipo_pessoa = "F"; os de pessoa jurídica (cnpj, nome_empresa, responsavel_empresa, ie) só quando tipo_pessoa = "J".

Compra rápida — para registrar só o financeiro, sem itens: envie "tipo": "compra_rapida" dentro de pedido e não envie produtos.

Preenchido pela loja (não envie): número do pedido, forma de pagamento (sempre "Na Loja Física (Offline)"), moeda (BRL), vendedor (o do cliente).

Exemplo mínimo #

Pessoa física, dois itens, pago:

{
  "cliente": {
    "tipo_pessoa": "F",
    "nome_completo": "MARIA JOSÉ DA SILVA",
    "cpf": "12345678909",
    "data_nascimento": "1986-02-15",
    "sexo": "Feminino",
    "rg": "Isento",
    "email": "maria@exemplo.com.br",
    "senha": "troque123",
    "tipo_cliente": "Revendedor",
    "cep": "37002000",
    "endereco": "Avenida Imigrantes",
    "numero": "10",
    "bairro": "Centro",
    "cidade": "Varginha",
    "estado": "MG",
    "telefone_celular": "35988887777"
  },
  "pedido": {
    "numero_pedido_externo": "ERP-98765",
    "status_pedido": "PG",
    "data_pedido": "2026-11-16",
    "valor_pedido": 249.76,
    "valor_desconto": 10.00,
    "valor_frete": 25.50,
    "valor_total": 265.26,
    "cep_entrega": "37002000",
    "endereco_entrega": "Avenida Imigrantes",
    "numero_entrega": "10",
    "bairro_entrega": "Centro",
    "cidade_entrega": "Varginha",
    "estado_entrega": "MG"
  },
  "subpedido": {
    "tipo_pedido": "A"
  },
  "produtos": [
    { "cod_barras": "7890000000017", "quantidade": 3, "preco": 43.32 },
    { "cod_barras": "7890000000024", "quantidade": 2, "preco": 59.90 }
  ]
}

Conta: 3 × 43,32 + 2 × 59,90 = 249,76 (valor_pedido); 249,76 − 10,00 + 25,50 = 265,26 (valor_total).

curl -X POST "https://api.viashopmoda.com.br/via/pedido/cadastrar/SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d @pedido.json

Respostas #

Sucesso:

{
  "retorno": true,
  "msg": "Pedido '111112' cadastrado com sucesso.",
  "numero_pedido": "111112",
  "numero_pedido_externo": "ERP-98765"
}

Erros (retorno: false, motivo em msg_erro):

MensagemCausaComo resolver
Objeto 'cliente' não enviadoFalta cliente.Envie o objeto.
Objeto 'pedido' não enviadoFalta pedido.Envie o objeto.
'numero_pedido_externo' não enviado no objeto 'pedido'Falta o número do ERP.Envie pedido.numero_pedido_externo.
Objeto 'subpedido' não enviadoFalta subpedido.Envie ao menos {"tipo_pedido": "A"}.
Objeto 'produtos' não enviadoFalta produtos (e não é compra rápida).Envie os itens.
Pedido não cadastrado. 'numero_pedido_externo' 'X' está associado ao pedido 'NNNNNN'Esse número do ERP já foi usado.É um reenvio: o pedido já existe (veja abaixo).
status_pedido' desconhecido ou não enviadoCódigo de status fora da lista.Use AN, AG, PA, PG, ET ou EN.
tipo_pedido' desconhecido ou não enviadosubpedido.tipo_pedido diferente de A/V.Envie "A" ou "V".
Resultado: X (valor_pedido - valor_desconto + valor_frete) não é igual ao valor_total de Y informadoConta 2 das regras não fecha.Recalcule valor_total.
A somatória dos produtos enviados de X não confere com o valor_total de Y.Conta 1 não fecha (apesar do texto dizer valor_total, a comparação é com valor_pedido).Ajuste valor_pedido ou os itens.
Mensagens de validação do clienteAlgum campo de cliente inválido.Veja a tabela de cliente.

Pode reenviar? #

Sim, com segurança. Como numero_pedido_externo é único, um reenvio do mesmo pedido é recusado com a mensagem "está associado ao pedido 'NNNNNN'" — e esse NNNNNN é o número que a loja já deu ao pedido. Trate essa resposta como "já cadastrado".

Efeitos colaterais #

  • Não altera o estoque. Depois de cadastrar, envie o saldo novo com estoque/atualizar.
  • Pode cadastrar o cliente, se ele ainda não existir.
  • As observações do pedido recebem "Integração ERP {nome da integração}".

Onde entra no processo #

Guia Pedidos → Pedidos criados fora da loja.

Erros comuns de integração #

  • Enviar o nome do status ("Pedido entregue") em vez do código ("EN"). Aqui é código; em pedido/atualizar é nome.
  • Mandar os campos de pedido soltos na raiz do JSON. Eles vão dentro de "pedido": { ... }.
  • valor_total calculado sobre os itens em vez de sobre valor_pedido.
  • Esperar que o estoque seja baixado automaticamente.