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_codexternopara ligar ao número do ERP. - Para mudar status de um pedido existente — use
pedido/atualizar.
Requisição #
| Método | POST |
| URL | https://api.viashopmoda.com.br/via/pedido/cadastrar/{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. |
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.
| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
cliente.tipo_pessoa | string | sim | máx. 1 | 'F' = pessoa física: , 'J' = pessoa jurídica e 'E' = cliente do exterior. |
cliente.email | string | sim | mín. 5, máx. 150 | Usado como contato e para acessar a loja virtual. |
cliente.senha | string | sim | mín. 4 | Senha para acessar a loja virtual. |
cliente.tipo_cliente | string | sim | máx. 100 | Sempre 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.cpf | numeric | sim | mín. 11, máx. 11 | Somente números. Obrigatório quando pessoa física. |
cliente.nome_completo | string | sim | máx. 150 | Nome completo do cliente. Obrigatório quando pessoa física. |
cliente.rg | string | não | máx. 25 | Caso inexistente enviar 'Isento'. Obrigatório quando pessoa física. |
cliente.data_nascimento | date | sim | máx. 10 | Formato 'aaaa-mm-dd'. Obrigatório quando pessoa física. |
cliente.sexo | string | sim | 'Masculino', 'Feminino' ou 'Nenhum'. Obrigatório quando pessoa física. | |
cliente.cnpj | string | sim | mín. 14, máx. 14 | Somente números. Obrigatório quando pessoa jurísica. |
cliente.nome_empresa | string | sim | máx. 150 | Nome fantasia da empresa. Obrigatório quando pessoa jurídica. |
cliente.responsavel_empresa | string | sim | máx. 150 | Nome do responsável pela empresa. Obrigatório quando pessoa jurídica. |
cliente.ie | string | sim | máx. 25 | Caso inexistente enviar 'Isento'. Obrigatório quando pessoa jurídica. |
cliente.moeda | string | não | máx. 3 | Para 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_diferenciada | double | não | máx. 11 | Representa a porcentagem de acréscimo ou desconto nos preços dos produtos. |
cliente.compra_minima_atacado | double | não | máx. 11 | Valor minimo para compra de atacado. |
cliente.compra_maxima_atacado | double | não | máx. 11 | Usado para quando tipo_cliente=Consignado, limitando o valor máximo a ser comprado. Se não enviado será zero. |
cliente.cep | numeric | sim | mín. 8, máx. 8 | Somente números no formato '37001000'. |
cliente.endereco | string | sim | máx. 150 | Caso cliente do exterior, será usado como endereço completo. |
cliente.numero | string | sim | máx. 10 | Não utilizado para clientes do exterior. |
cliente.complemento | string | não | máx. 50 | Não utilizado para clientes do exterior. |
cliente.bairro | string | sim | máx. 50 | Não utilizado para clientes do exterior. |
cliente.cidade | string | sim | máx. 50 | |
cliente.estado | string | sim | máx. 2 | Sigla do estado com dois caracteres. Não utilizado para clientes do exterior. |
cliente.pais | string | não | máx. 50 | Para países diferente de 'Brasil' usar o campo cod_pais. |
cliente.cod_pais | string | não | máx. 2 | Código do país no padrão ISO-2, se não enviado será utilizado 'BR'. |
cliente.codigo_ddi | string | não | mín. 1, aceita null | Se não enviado sempre será 55. |
cliente.telefone_celular | string | sim | máx. 50 | Se não enviado no formato: '+{CODIGO_DDI}{NUMERO_TELEFONE}' será acrescentado o DDI (relativo ao cod_pais) ao número enviado. |
cliente.operadora_celular | string | não | máx. 20 | Nome da operadora de telefonia. Se não enviado será cadastrado 'Outras' |
cliente.utm_source | string | não | máx. 70 | Se enviado é necessário enviar utm_medium e utm_campaign |
cliente.utm_medium | string | não | máx. 70 | Se enviado é necessário enviar utm_source e utm_campaign |
cliente.utm_campaign | string | não | máx. 70 | Se enviado é necessário enviar utm_source e utm_medium |
cliente.crm | array | não | Frases relacionadas ao CRM do cliente | |
cliente.assinar_newsletter | string | não | máx. 1 | 'S' ou 'N', se não enviado será cadastrado 'N'. |
cliente.data_cadastro | datetime | não | máx. 19 | Data de cadastro do cliente. Padrão DATETIME 'aaaa-mm-dd hh:mm:ss'. |
cliente.liberado_para_comprar | string | não | máx. 1 | Padrã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.vendedor | object | não | Objeto 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.
| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
pedido.numero_pedido_externo | string | sim | aceita null | Código do pedido no sistema de origem |
pedido.status_pedido | string | sim | máx. 50 | Opções de status: 'AN' = Análise, 'PG' = Pago ou 'EN' = Entregue. |
pedido.url_notafiscal | string | não | máx. 200 | URL completa da nota fiscal do pedido. Usado quando o pedido já estiver pago/faturado. |
pedido.data_pedido | date | sim | máx. 11 | Formato 'aaaa-mm-dd'. |
pedido.tipo_frete | string | não | máx. 50 | Opcional para 'status_pedido' = 'EN', se não informado será cadastrado valor padrão. |
pedido.valor_pedido | double | sim | máx. 11 | Obrigatório para 'status_pedido' = 'EN' e 'PG'. |
pedido.valor_desconto | double | sim | máx. 11 | Obrigatório para 'status_pedido' = 'EN' e 'PG'. Caso não tenha enviar '0.00' |
pedido.valor_frete | double | sim | máx. 11 | Obrigatório para 'status_pedido' = 'EN'. |
pedido.valor_total | double | sim | máx. 11 | Valor total do pedido. Somatória dos produtos + 'valor_pedido' - 'valor_desconto' + 'valor_frete'. |
pedido.cep_entrega | numeric | sim | mín. 8, máx. 8 | Somente números no formato '37001000'. |
pedido.endereco_entrega | string | sim | máx. 150 | Caso cliente do exterior, será usado como endereço completo. |
pedido.numero_entrega | string | sim | máx. 10 | Não utilizado para clientes do exterior. |
pedido.complemento_entrega | string | não | máx. 50 | Não utilizado para clientes do exterior. |
pedido.bairro_entrega | string | sim | máx. 50 | Não utilizado para clientes do exterior. |
pedido.cidade_entrega | string | sim | máx. 50 | |
pedido.estado_entrega | string | sim | máx. 2 | Sigla do estado com dois caracteres. Não utilizado para clientes do exterior. |
subpedido (objeto) #
Tipo de venda, pagamento e rastreio.
| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
subpedido.tipo_pedido | string | sim | máx. 50 | 'A' = Atacado e 'V' = Varejo. Se não enviado, será cadastrado como 'Atacado'. |
subpedido.parcelas_pagamento | integer | não | máx. 2 | Número de parcelas. |
subpedido.rastreio_frete | string | não | máx. 100 | Código de rastreamento do pedido na transportadora. |
produtos[] (lista) #
Itens do pedido. Não enviar quando pedido.tipo = "compra_rapida".
| Campo | Tipo | Obrigatório | Limites | Descrição |
|---|---|---|---|---|
produtos[].quantidade | integer | sim | Quantidade do produto no pedido. | |
produtos[].preco | double | sim | Preço unitário do produto. | |
produtos[].cod_barras | string | não | Có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ódigo | Status gravado | Conta como pago? |
|---|---|---|
AN | Pedido em análise | não |
AG | Aguardando Pagamento | não |
PA | Pagamento autorizado, aguardando envio | não (ver nota) |
PG | Pagamento autorizado, aguardando envio | sim |
ET | Pedido em transporte | sim |
EN | Pedido entregue | sim |
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:
pedido.valor_pedido= soma dequantidade × precode todos os itens deprodutos.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.jsonRespostas #
Sucesso:
{
"retorno": true,
"msg": "Pedido '111112' cadastrado com sucesso.",
"numero_pedido": "111112",
"numero_pedido_externo": "ERP-98765"
}Erros (retorno: false, motivo em msg_erro):
| Mensagem | Causa | Como resolver |
|---|---|---|
Objeto 'cliente' não enviado | Falta cliente. | Envie o objeto. |
Objeto 'pedido' não enviado | Falta 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 enviado | Falta subpedido. | Envie ao menos {"tipo_pedido": "A"}. |
Objeto 'produtos' não enviado | Falta 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 enviado | Código de status fora da lista. | Use AN, AG, PA, PG, ET ou EN. |
tipo_pedido' desconhecido ou não enviado | subpedido.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 informado | Conta 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 cliente | Algum 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; empedido/atualizaré nome. - Mandar os campos de
pedidosoltos na raiz do JSON. Eles vão dentro de"pedido": { ... }. valor_totalcalculado sobre os itens em vez de sobrevalor_pedido.- Esperar que o estoque seja baixado automaticamente.