Criar Pedido com Pacote

Use esta operação quando a integração já conhece um pacote_id ativo. O pacote define a composição do pedido e precisa pertencer ao produtor autenticado.

http

POST /api/v1/pedidos

Importante

A rota exige Authorization: Bearer {token}, Accept: application/json e a permissão criar_pedido_api. O cliente, o pacote e todos os produtos do pacote precisam pertencer ao produtor autenticado e estar habilitados. Um token sem a permissão recebe 403 antes de a validação rodar.

Observação

Esta rota não possui limite de requisições próprio. Na API v1 somente POST /api/v1/frete/calcular é limitado (60 requisições por minuto e por usuário).

Corpo mínimo

json

{
  "cliente_id": 291955,
  "pacote_id": 1481,
  "tipo_frete": false,
  "valor_venda": 12990
}

jsonc

{
  "cliente_id": 291955,  // obrigatório; cliente da conta autenticada
  "pacote_id": 1481,    // obrigatório; pacote ativo da conta autenticada
  "tipo_frete": false,  // obrigatório; false = usar o leilão de frete configurado na conta
  "valor_venda": 12990  // obrigatório; valor unitário em centavos
}

Cada chamada cria um pedido com um item e quantidade 1. Campos livres como item_pedido não substituem o pacote informado.

Seleção do frete

tipo_frete define quem escolhe o serviço de entrega:

`tipo_frete`	Comportamento
`false`	Omita `frete_selecionado`. A Paylog usa o leilão de frete configurado na conta do produtor
`true`	Envie `frete_selecionado` com a transportadora e o serviço retornados por `POST /api/v1/frete/calcular`

Ao receber uma seleção explícita, a Paylog executa uma nova cotação no servidor e persiste somente os valores confiáveis dessa cotação. Preços, prazos ou percentuais enviados pelo cliente são ignorados.

json

{
  "cliente_id": 291955,
  "pacote_id": 1481,
  "tipo_frete": true,
  "frete_selecionado": {
    "transportadora_codigo": "correios",
    "servico_codigo": "03220"
  },
  "valor_venda": 12990
}

Campo	Tipo	Obrigatoriedade	Observação
`frete_selecionado`	`object`	Obrigatório quando `tipo_frete` for `true`; proibido quando for `false`	Seleção obtida na calculadora de frete
`frete_selecionado.transportadora_codigo`	`string`	Condicional	Código da transportadora retornado pela Calculadora de Frete
`frete_selecionado.servico_codigo`	`string`	Condicional	Código do serviço retornado em `cotacoes[].servicos[].codigo`

Importante

Se a combinação não estiver mais disponível na nova cotação, a criação retorna 400. Execute a calculadora novamente e apresente as opções atualizadas ao cliente.

Parâmetros de rastreamento

parametros_rastreamento é totalmente opcional. Envie somente quando quiser associar UTMs ou identificadores de campanha ao pedido.

Se o objeto for omitido, nenhum registro de rastreamento será criado.
Se o objeto for enviado vazio ou somente com valores vazios, nenhum registro será criado.
Cada campo interno também é opcional; envie apenas os dados realmente disponíveis.
Os dados ficam associados somente ao pedido recém-criado.

json

{
  "cliente_id": 291955,
  "pacote_id": 1481,
  "tipo_frete": false,
  "valor_venda": 12990,
  "referencia_externa": "PEDIDO-ERP-2026-0001",
  "parametros_rastreamento": {
    "utm_source": "instagram",
    "utm_medium": "paid-social",
    "utm_campaign": "lancamento-julho",
    "utm_content": "video-01",
    "utm_term": "bem-estar",
    "utm_id": "campaign-2026-07",
    "src": "checkout",
    "sck": "affiliate-42",
    "xcod": "creative.variation.3",
    "campaign_code": "CMP-2026-07",
    "campaign_name": "Lançamento Julho",
    "origin_url": "https://loja.example.com/oferta",
    "query_params": {
      "fbclid": "fb-click-123",
      "source_id": 42,
      "first_visit": true
    }
  }
}

jsonc

{
  "cliente_id": 291955,                  // obrigatório
  "pacote_id": 1481,                    // obrigatório
  "tipo_frete": false,                  // obrigatório
  "valor_venda": 12990,                 // obrigatório; centavos
  "referencia_externa": "PEDIDO-ERP-2026-0001", // opcional
  "parametros_rastreamento": {           // objeto opcional; pode ser omitido
    "utm_source": "instagram",          // opcional; origem da campanha
    "utm_medium": "paid-social",        // opcional; mídia/canal
    "utm_campaign": "lancamento-julho", // opcional; campanha
    "utm_content": "video-01",          // opcional; variação do criativo
    "utm_term": "bem-estar",            // opcional; termo
    "utm_id": "campaign-2026-07",       // opcional; ID externo da campanha
    "src": "checkout",                  // opcional; código de origem
    "sck": "affiliate-42",              // opcional; código de rastreamento
    "xcod": "creative.variation.3",      // opcional; código complementar
    "campaign_code": "CMP-2026-07",     // opcional
    "campaign_name": "Lançamento Julho", // opcional
    "origin_url": "https://loja.example.com/oferta", // opcional; URL HTTP/HTTPS
    "query_params": {                   // opcional; somente chaves seguras documentadas
      "fbclid": "fb-click-123",         // string, número, booleano ou null
      "source_id": 42,
      "first_visit": true
    }
  }
}

Campos aceitos

Campo	Tipo	Obrigatoriedade	Limite
`parametros_rastreamento`	`object`	Opcional	Somente as chaves documentadas
`utm_source`	`string`	Opcional	255 caracteres
`utm_medium`	`string`	Opcional	255 caracteres
`utm_campaign`	`string`	Opcional	255 caracteres
`utm_content`	`string`	Opcional	255 caracteres
`utm_term`	`string`	Opcional	255 caracteres
`utm_id`	`string`	Opcional	255 caracteres
`src`	`string`	Opcional	255 caracteres
`sck`	`string`	Opcional	255 caracteres
`xcod`	`string`	Opcional	2.048 caracteres
`campaign_code`	`string`	Opcional	100 caracteres
`campaign_name`	`string`	Opcional	255 caracteres
`origin_url`	`string`	Opcional	URL HTTP/HTTPS de até 2.048 caracteres
`query_params`	`object`	Opcional	Somente chaves seguras documentadas; sem objetos ou listas aninhados

As únicas chaves aceitas em query_params são:

fbclid, gclid, gbraid, wbraid, ttclid, msclkid, twclid, ref, referrer, source_id e first_visit.

Cada valor pode ser uma string de até 1.000 caracteres, número, booleano ou null. Objetos, listas e qualquer chave fora dessa lista são rejeitados; isso impede que segredos, tokens de sessão ou dados arbitrários sejam persistidos.

Iniciar o faturamento

faturar é opcional e o padrão é false. Há duas formas de iniciar o faturamento:

envie "faturar": true na criação para enviar o pedido direto para a rotina de faturamento;
omita faturar ou envie false e, depois da revisão, use POST /api/v1/pedidos/{id}/aprovar.

Com faturar: true (ou com notafiscal presente) o pedido nasce no status 10 (Pago - Aguardando NF/DC). O disparo respeita o prazo de faturamento configurado no produto do pacote: sem prazo o processamento é imediato, a partir de 1 hora o pedido é agendado para daqui a N horas e a partir de 24 horas ele é agendado para o próximo dia útil.

Sem faturar e sem notafiscal, o pedido nasce no status 1 (Pendente).

Importante

Janela de edição do produtor. Quando a conta tem a pausa de pedidos habilitada e faturar não foi enviado (nem notafiscal), o pedido criado é imediatamente movido para o status 8 (Parado) com motivo_parado_id igual a 13 (Aguardando Edição do Produtor) e uma data de retomada automática. Ele volta sozinho para o status 10 quando a janela expira, ou antes disso via POST /api/v1/pedidos/{id}/aprovar. Pedidos do Mercado Livre e pedidos agregados (order-bumps) nunca entram nessa janela. Um pedido criado por esta rota, portanto, pode aparecer como 1 ou 8 na consulta imediatamente seguinte — sempre confira status_code_id em vez de assumir 1.

Observação

Enviar notafiscal registra a nota fiscal própria e inicia o fluxo de faturamento mesmo sem faturar. Isso não pula validações de endereço, estoque ou configuração fiscal, e desativa a janela de edição descrita acima.

Nota fiscal própria

notafiscal e info_extra_notafiscal são opcionais. Quando um deles é enviado, seus campos internos indicados como condicionais tornam-se obrigatórios.

json

{
  "cliente_id": 291955,
  "pacote_id": 1481,
  "tipo_frete": false,
  "valor_venda": 12990,
  "referencia_externa": "PEDIDO-ERP-2026-0001",
  "notafiscal": {
    "chave": "35260741904774000124550010000109841929722483",
    "numero": 10984,
    "valor": 12990,
    "imposto": 0,
    "link_pdf": "https://example.com/notas/10984.pdf",
    "link_xml": "https://example.com/notas/10984.xml"
  },
  "info_extra_notafiscal": {
    "descricao": "Referente ao contrato ERP-2026-0001",
    "duplicatas": [
      {
        "codigo": 1,
        "data_vencimento": "2026-08-21",
        "valor": 12990
      }
    ]
  }
}

Campos de `notafiscal`

Campo	Tipo	Obrigatoriedade	Observação
`chave`	`string`	Condicional	Obrigatório quando `notafiscal` é enviado. Chave de acesso da NF-e
`numero`	`integer`	Condicional	Obrigatório quando `notafiscal` é enviado. Número da nota
`valor`	`integer`	Condicional	Obrigatório quando `notafiscal` é enviado. Valor total em centavos
`imposto`	`integer`	Opcional	Imposto em centavos; quando omitido é gravado como `0`
`link_pdf`	`string`	Condicional	Obrigatório quando `notafiscal` é enviado. URL do DANFE
`link_xml`	`string`	Opcional	URL do XML da NF-e; gravado como `null` quando omitido

A nota é registrada com o status autorizada e o pedido entra na rotina de faturamento. Chaves não listadas acima são ignoradas. Erros aqui retornam 400.

Campos de `info_extra_notafiscal`

Campo	Tipo	Obrigatoriedade	Observação
`descricao`	`string`	Condicional	Obrigatório quando `info_extra_notafiscal` é enviado
`duplicatas`	`array<object>`	Condicional	Obrigatório quando `info_extra_notafiscal` é enviado; precisa ter ao menos um item
`duplicatas[].codigo`	`number`	Condicional	Obrigatório em cada duplicata
`duplicatas[].data_vencimento`	`string`	Condicional	Obrigatório em cada duplicata; formato `YYYY-MM-DD`
`duplicatas[].valor`	`integer`	Condicional	Obrigatório em cada duplicata; valor em centavos

Erros neste bloco retornam 422 — diferente do bloco notafiscal, que retorna 400.

Campos da criação

Campo	Tipo	Obrigatoriedade	Aceita `null`	Observação
`cliente_id`	`integer`	Obrigatório	Não	Deve existir e pertencer ao produtor autenticado
`pacote_id`	`integer`	Obrigatório	Não	Deve estar ativo e todos os seus produtos devem estar aprovados
`tipo_frete`	`boolean`	Obrigatório	Não	`false` usa o leilão da conta; `true` exige `frete_selecionado`
`frete_selecionado`	`object`	Condicional	Não	Obrigatório somente quando `tipo_frete` for `true`; proibido quando for `false`. Aceita exatamente `transportadora_codigo` e `servico_codigo`, ambos `string` de até 100 caracteres
`valor_venda`	`integer`	Obrigatório	Não	Valor unitário do item em centavos; mínimo `1`. Vira `valor_unitario` e `subtotal` do item criado
`faturar`	`boolean`	Opcional	Não	Padrão `false`. `true` inicia o faturamento; omitido ou `false` mantém o pedido pendente
`referencia_externa`	`string`	Opcional	Sim	Identificador do pedido no seu sistema. Não é validado pela API e é gravado como texto de até 255 caracteres — valores maiores causam falha interna (`500`)
`parametros_rastreamento`	`object`	Opcional	Sim	UTMs e parâmetros de campanha; vazio não cria registro
`notafiscal`	`object`	Opcional	Não	Se presente, seus campos condicionais são validados
`info_extra_notafiscal`	`object`	Opcional	Não	Dados extras usados no faturamento

Requisição

bash

curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/pedidos' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "cliente_id": 291955,
    "pacote_id": 1481,
    "tipo_frete": false,
    "valor_venda": 12990,
    "referencia_externa": "PEDIDO-ERP-2026-0001"
  }'

Resposta `200`

json

{
  "code": 200,
  "message": "Pedido Criado com Sucesso",
  "pedido": 64914
}

pedido contém somente o ID interno do novo pedido.

Erros

HTTP	Situação	`message`
`400`	Campos principais, `frete_selecionado`, `notafiscal` ou `parametros_rastreamento` inválidos	`Requisicao invalida` (com `erros` por campo)
`401`	Token ausente ou inválido	`Unauthenticated.`
`401`	Cliente inexistente ou fora da conta autenticada	`Cliente Invalido`
`401`	Pacote inexistente, fora da conta, inativo, produtor inativo ou com produto não aprovado	`Pacote Invalido`
`403`	Token válido sem a permissão `criar_pedido_api`	`User does not have the right permissions.` — devolvido na chave `errors` (não `message`), junto de `"code": 403`
`422`	`info_extra_notafiscal` inválido	`Requisicao inválida` (com `erros` por campo)
`500`	Falha interna ao registrar o pedido	`Um erro interno ocorreu ao registrar pedido, tente novamente, se persistir contate o suporte`

Exemplo de erro 400:

json

{
  "code": 400,
  "message": "Requisicao invalida",
  "erros": {
    "valor_venda": [
      "The valor venda field must be at least 1."
    ]
  }
}

Observação

Os quatro casos de 401 são deliberadamente indistinguíveis de um pedido de outro produtor: a API nunca confirma a existência de um cliente ou pacote fora da conta autenticada.

Para listar, consultar ou executar comandos sobre pedidos, consulte Pedidos. Para criar sem conhecer um pacote, consulte Criar Pedido Carrinho.

#Corpo mínimo

#Seleção do frete

#Parâmetros de rastreamento

#Campos aceitos

#Iniciar o faturamento

#Nota fiscal própria

#Campos de notafiscal

#Campos de info_extra_notafiscal

#Campos da criação

#Requisição

#Resposta 200

#Erros

Corpo mínimo

Seleção do frete

Parâmetros de rastreamento

Campos aceitos

Iniciar o faturamento

Nota fiscal própria

Campos de `notafiscal`

Campos de `info_extra_notafiscal`

Campos da criação

Requisição

Resposta `200`

Erros