# 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.

Fonte: https://api.viashopmoda.com.br/docs-api/?p=recursos/pedido/cadastrar · 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`](https://api.viashopmoda.com.br/docs-api/?p=guias/pedidos&formato=md#3-o-erp-informa-o-numero-do-pedido-no-erp) para 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:

```text
{
  "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](https://api.viashopmoda.com.br/docs-api/?p=recursos/vendedores/consultar&formato=md). 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:
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:

```json
{
  "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`).

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

## Respostas

Sucesso:

```json
{
  "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](https://api.viashopmoda.com.br/docs-api/?p=guias/pedidos&formato=md#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.
