Criar / Atualizar Pedido

Cria um novo pedido ou atualiza um existente via externalId.

Endpoint

POST/api/public/pedidos

Auth60/min por IP

Visão geral

Use este endpoint para importar pedidos de qualquer plataforma ou sistema personalizado. Se você passar um externalId, a requisição é idempotente: chamadas subsequentes com o mesmo ID atualizam o pedido existente em vez de criar um duplicado.

Ao menos um dos campos identificadores deve estar presente: orderNumber, trackingCode, customerName ou customerEmail.

Corpo da requisição (JSON)

Campo	Tipo	Obrig.	Descrição
`externalId`	string	não	ID único do pedido no seu sistema. Se omitido, um UUID é gerado automaticamente. Use para idempotência.
`orderNumber`	string	não	Número do pedido exibido no dashboard (ex.: "#1001").
`trackingCode`	string	não	Código de rastreio (ex.: AA123456789BR).
`trackingCarrier`	string	não	Nome da transportadora (ex.: "Correios").
`status`	enum	não	Status do pedido: `pendingprocessingshippeddeliveredcancelledunknown`. Padrão: `pending`.
`orderDate`	string (ISO 8601)	não	Data do pedido. Padrão: data/hora atual.
`totalAmount`	integer	não	Valor total em centavos (ex.: 15990 = R$ 159,90).
`currency`	string	não	Código da moeda (3 letras). Padrão: "BRL".
`customerName`	string	não	Nome completo do cliente.
`customerEmail`	string	não	E-mail do cliente.
`phone`	string	não	Telefone do cliente no formato E.164: DDI + número, somente dígitos, sem `+` ou espaços. Exemplos: `5511999999999` (Brasil), `15555551234` (EUA), `351912345678` (Portugal). Pode ser omitido. Se informado e inválido, a requisição é rejeitada com status 400.
`shippingAddress`	object	não	Endereço de entrega. Ver tabela abaixo.
`lineItems`	array	não	Itens do pedido. Ver tabela abaixo. Máximo: 100 itens.

Objeto shippingAddress

Campo	Tipo	Obrig.	Descrição
`street`	string	não	Logradouro (rua, av.).
`number`	string	não	Número.
`complement`	string	não	Complemento.
`neighborhood`	string	não	Bairro.
`city`	string	não	Cidade.
`state`	string	não	UF (2 letras).
`postalCode`	string	não	CEP (até 10 caracteres).
`country`	string	não	País. Padrão: "BR".

Objeto lineItems[]

Campo	Tipo	Obrig.	Descrição
`title`	string	sim	Nome do produto.
`quantity`	integer	sim	Quantidade (mínimo 1).
`price`	number	sim	Preço unitário em reais (ex.: 49.90).
`sku`	string	não	SKU do produto.

Resposta

Status	Significado
`201`	Pedido criado com sucesso.
`200`	Pedido atualizado (externalId existente).
`400`	JSON inválido, campos com erro ou nenhum identificador informado.
`401`	Chave de API ausente ou inválida.
`429`	Limite mensal de pedidos do plano atingido.
`500`	Erro interno.

O corpo de sucesso inclui order.orderId, order.externalId, order.orderNumber, order.trackingCode, order.status, order.orderDate, order.createdAt e order.updatedAt.

Formato do telefone

O campo phone é opcional. Quando informado, deve seguir o padrão E.164: código do país (DDI) concatenado com o número local, somente dígitos (7–15 dígitos no total). Não use +, espaços, hífens ou parênteses — eles são aceitos pela API mas removidos antes da validação.

O WhatsApp só consegue entregar notificações quando o telefone inclui o DDI. Números sem código de país (ex.: 11999999999) serão rejeitados no envio. Sempre envie o DDI: 5511999999999 para Brasil, 15555551234 para EUA, 351912345678 para Portugal.

Idempotência por externalId

Passe sempre o externalId com o ID do pedido no seu sistema. Assim, reenvios (retry de webhook, re-sync) atualizam o registro existente sem duplicar. Sem externalId, cada chamada cria um pedido novo.

Exemplos

curl -X POST https://seurastreio.com.br/api/public/pedidos \
  -H "Authorization: Bearer sr_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderNumber": "#1001",
    "customerName": "Maria Silva",
    "customerEmail": "[email protected]",
    "trackingCode": "AA123456789BR",
    "status": "shipped",
    "totalAmount": 15990,
    "shippingAddress": {
      "street": "Av. Paulista",
      "number": "1578",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310100"
    }
  }'

const response = await fetch("https://seurastreio.com.br/api/public/pedidos", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sr_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    externalId: "minha-loja-1001",
    orderNumber: "#1001",
    customerName: "Maria Silva",
    trackingCode: "AA123456789BR",
    status: "shipped",
    totalAmount: 15990,
  }),
});

const data = await response.json();
// { ok: true, message: "Pedido criado.", order: { orderId, externalId, ... } }

import requests

response = requests.post(
    "https://seurastreio.com.br/api/public/pedidos",
    headers={
        "Authorization": "Bearer sr_live_...",
        "Content-Type": "application/json",
    },
    json={
        "externalId": "minha-loja-1001",
        "orderNumber": "#1001",
        "customerName": "Maria Silva",
        "trackingCode": "AA123456789BR",
        "status": "shipped",
        "totalAmount": 15990,
    },
)
data = response.json()
print(data)  # {'ok': True, 'message': 'Pedido criado.', 'order': {...}}