Criar Pedido Carrinho

O endpoint recebe os produtos avulsos do pedido. A integração não envia pacote_id: a Paylog valida a composição e reutiliza ou cria um pacote normal para o produtor autenticado.

http

POST /api/v1/pedidos/carrinho

Quando usar

Operação	Use quando
`POST /api/v1/pedidos`	A integração já conhece um `pacote_id` ativo.
`POST /api/v1/pedidos/carrinho`	A integração conhece os produtos, quantidades e valores, mas não possui um pacote previamente cadastrado.

Comportamento

O token define o produtor e exige a permissão criar_pedido_api.
cliente_id e todos os produto_id precisam pertencer ao produtor autenticado.
Cada item da composição inclui produto_id, quantidade e o valor_unitario obrigatório.
Produtos repetidos no payload são rejeitados para evitar valores unitários ambíguos.
A Paylog procura um pacote ativo com a mesma composição; se não existir, cria um pacote normal com embalagem, peso e dimensões válidos.
A operação cria um único pedido e calcula valor_venda pela soma de quantidade × valor_unitario.
Uma transportadora pode ser pré-selecionada usando os códigos retornados pela Calculadora de Frete. A Paylog recalcula e valida a cotação antes de gravá-la.
Sem frete_selecionado, o pedido segue o leilão de frete configurado para a conta.
parametros_rastreamento é opcional; quando omitido ou vazio, nenhum registro de rastreamento é criado.

Parâmetros de rastreamento

O contrato usa o mesmo objeto opcional de Criar Pedido com Pacote. Todos os seus campos internos são opcionais, mas a lista de chaves é fechada: qualquer chave fora da lista abaixo faz a requisição falhar com 422.

jsonc

{
  "parametros_rastreamento": {           // objeto opcional; pode ser omitido ou ser null
    "utm_source": "instagram",           // opcional, string até 255
    "utm_medium": "paid-social",         // opcional, string até 255
    "utm_campaign": "lancamento-julho",  // opcional, string até 255
    "utm_content": "criativo-a",         // opcional, string até 255
    "utm_term": "frete-gratis",          // opcional, string até 255
    "utm_id": "camp-9981",               // opcional, string até 255
    "src": "checkout",                   // opcional, string até 255
    "sck": "affiliate-42",               // opcional, string até 255
    "xcod": "cod-externo-1",             // opcional, string até 2048
    "campaign_code": "LANC07",           // opcional, string até 100
    "campaign_name": "Lançamento Julho", // opcional, string até 255
    "origin_url": "https://loja.example.com/oferta", // opcional, URL http/https até 2048
    "query_params": {                    // opcional; somente valores simples
      "fbclid": "fb-click-123"
    }
  }
}

query_params aceita somente estas 11 chaves de atribuição, com valores escalares (string, número, booleano ou null) de no máximo 1000 caracteres: fbclid, gclid, gbraid, wbraid, ttclid, msclkid, twclid, ref, referrer, source_id, first_visit. Objetos, listas ou qualquer outra chave retornam 422 em parametros_rastreamento.query_params.

Se parametros_rastreamento for omitido, enviado como null ou {}, ou contiver somente valores vazios, o pedido será criado normalmente e não terá uma linha em order_tracking_sources.

Criar com frete pré-selecionado

POST

bash

curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/pedidos/carrinho' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "cliente_id": 291955,
    "referencia_externa": "PEDIDO-LOJA-10045",
    "faturar": true,
    "itens": [
      {
        "produto_id": 7867,
        "quantidade": 2,
        "valor_unitario": 4990
      },
      {
        "produto_id": 8120,
        "quantidade": 1,
        "valor_unitario": 2990
      }
    ],
    "frete_selecionado": {
      "transportadora_codigo": "correios",
      "servico_codigo": "03298"
    }
  }'

http

POST /api/v1/pedidos/carrinho HTTP/1.1
Host: ev.paylog.cash
Accept: application/json
Authorization: Bearer SEU_TOKEN
Content-Type: application/json

{
  "cliente_id": 291955,
  "referencia_externa": "PEDIDO-LOJA-10045",
  "faturar": true,
  "itens": [
    { "produto_id": 7867, "quantidade": 2, "valor_unitario": 4990 },
    { "produto_id": 8120, "quantidade": 1, "valor_unitario": 2990 }
  ],
  "frete_selecionado": {
    "transportadora_codigo": "correios",
    "servico_codigo": "03298"
  }
}

json

{
  "cliente_id": 291955,
  "referencia_externa": "PEDIDO-LOJA-10045",
  "faturar": true,
  "itens": [
    {
      "produto_id": 7867,
      "quantidade": 2,
      "valor_unitario": 4990
    },
    {
      "produto_id": 8120,
      "quantidade": 1,
      "valor_unitario": 2990
    }
  ],
  "frete_selecionado": {
    "transportadora_codigo": "correios",
    "servico_codigo": "03298"
  }
}

jsonc

{
  "cliente_id": 291955, // Obrigatório: cliente pertencente ao produtor do token.
  "referencia_externa": "PEDIDO-LOJA-10045", // Opcional: referência do pedido no seu sistema.
  "faturar": true, // Opcional: true inicia o faturamento; omitido ou false mantém o pedido pendente.
  "itens": [ // Obrigatório: ao menos uma linha de produto.
    {
      "produto_id": 7867, // Obrigatório: produto ativo e aprovado da conta autenticada.
      "quantidade": 2, // Obrigatório: inteiro entre 1 e 100.
      "valor_unitario": 4990 // Obrigatório: valor de uma unidade em centavos; aceita zero.
    },
    {
      "produto_id": 8120,
      "quantidade": 1,
      "valor_unitario": 2990
    }
  ],
  "frete_selecionado": { // Opcional: omita o objeto inteiro para usar a escolha automática.
    "transportadora_codigo": "correios", // Condicional: código retornado pela calculadora.
    "servico_codigo": "03298" // Condicional: código do serviço da mesma cotação.
  }
}

Neste exemplo, valor_venda será calculado como (2 × 4.990) + (1 × 2.990) = 12.970 centavos.

Corpo mínimo

O frete pré-selecionado e os campos de integração podem ser omitidos:

json

{
  "cliente_id": 291955,
  "itens": [
    {
      "produto_id": 7867,
      "quantidade": 1,
      "valor_unitario": 12990
    }
  ]
}

jsonc

{
  "cliente_id": 291955, // Obrigatório: sempre limitado à conta do token.
  "itens": [
    {
      "produto_id": 7867, // Obrigatório: produto ativo e aprovado da mesma conta.
      "quantidade": 1, // Obrigatório: quantidade inteira.
      "valor_unitario": 12990 // Obrigatório: inteiro em centavos, maior ou igual a zero.
    }
  ]
  // referencia_externa, faturar e frete_selecionado são opcionais.
}

Campos da requisição

Campo	Tipo	Presença	Regra
`cliente_id`	`integer`	Obrigatório	Cliente existente e pertencente ao produtor autenticado.
`referencia_externa`	`string`	Opcional	Referência do pedido no sistema da integração; até 255 caracteres. Aceita `null`.
`faturar`	`boolean`	Opcional	`true` inicia o faturamento; omitido ou `false` mantém o pedido pendente.
`parametros_rastreamento`	`object`	Opcional	UTMs e identificadores de campanha; omitido, `null` ou vazio não cria registro. Lista de chaves fechada.
`itens`	`array`	Obrigatório	Entre 1 e 100 linhas, sem repetir `produto_id`.
`itens[].produto_id`	`integer`	Obrigatório	Produto ativo, aprovado e pertencente ao produtor autenticado.
`itens[].quantidade`	`integer`	Obrigatório	Inteiro entre `1` e `100`.
`itens[].valor_unitario`	`integer`	Obrigatório	Valor de uma unidade em centavos; de `0` a `2147483647`.
`frete_selecionado`	`object`	Opcional	Omita para usar o leilão de frete configurado na sua conta.
`frete_selecionado.transportadora_codigo`	`string`	Condicional	Obrigatório quando `frete_selecionado` for enviado; até 100 caracteres.
`frete_selecionado.servico_codigo`	`string`	Condicional	Obrigatório quando `frete_selecionado` for enviado; até 100 caracteres.

O total do pedido (Σ quantidade × valor_unitario) também é limitado a 2147483647 centavos. Um item ou um total acima do teto retorna 422 em itens.{índice}.valor_unitario ou em itens.

Atenção

Os três objetos aninhados deste contrato não aceitam chaves extras. itens[] aceita exatamente produto_id, quantidade e valor_unitario; frete_selecionado aceita exatamente transportadora_codigo e servico_codigo; parametros_rastreamento aceita apenas as chaves listadas acima. Qualquer chave adicional dentro de um desses objetos faz a requisição inteira falhar com 422 — não é ignorada em silêncio. Um campo aparentemente inofensivo como sku, preco_frete ou utm_channel derruba um payload que seria válido.

A mensagem devolvida nesse caso é a mensagem genérica de tipo, não uma mensagem de "chave desconhecida" — é o erro mais confuso deste endpoint, porque você enviou um array e mesmo assim recebe "deve ser um array":

json

{
  "message": "Os dados fornecidos são inválidos.",
  "errors": {
    "itens.0": ["itens.0 deve ser um array."],
    "frete_selecionado": ["frete selecionado deve ser um array."],
    "parametros_rastreamento": ["parametros rastreamento deve ser um array."]
  }
}

Ao receber esse erro com um objeto que você acredita estar correto, procure a chave a mais antes de qualquer outra hipótese. O erro é reportado na chave do objeto (itens.{índice}, frete_selecionado, parametros_rastreamento), nunca na chave extra em si.

Importante

Não envie pacote_id, preço do frete, prazo, custo interno ou margem. O pacote é resolvido pelo servidor e a transportadora pré-selecionada é recalculada com os dados atuais do cliente, da composição e da conta. Chaves desconhecidas na raiz do corpo são descartadas em silêncio (não geram 422): elas nunca chegam à criação do pedido, então não confie nelas para transportar dados. A recusa com 422 por chave extra vale para os objetos aninhados descritos acima.

Pré-seleção de frete

Copie somente transportadora_codigo e cotacoes[].servicos[].codigo da resposta da calculadora:

json

{
  "frete_selecionado": {
    "transportadora_codigo": "correios",
    "servico_codigo": "03298"
  }
}

A Paylog não confiará no preço recebido pelo cliente. Na criação, o serviço será cotado novamente:

se continuar disponível, transportadora, serviço, preço e prazo atuais serão gravados;
se não estiver mais disponível para o destino ou para o pacote, a API retornará 422;
se frete_selecionado for omitido, o pedido seguirá o leilão de frete configurado na conta.

Resposta `201`

json

{
  "code": 201,
  "message": "Pedido criado com sucesso",
  "pedido": {
    "id": 64915,
    "pacote_id": 1902,
    "valor_venda": 12970,
    "logistica_preselecionada": true
  }
}

jsonc

{
  "code": 201, // Sempre: código HTTP repetido no corpo.
  "message": "Pedido criado com sucesso", // Sempre: resumo legível.
  "pedido": {
    "id": 64915, // Sempre: ID do pedido criado.
    "pacote_id": 1902, // Sempre: pacote normal reutilizado ou criado automaticamente.
    "valor_venda": 12970, // Sempre: total calculado em centavos.
    "logistica_preselecionada": true // Sempre: true quando o frete enviado foi validado e aplicado.
  }
}

Segurança e isolamento

O produtor é sempre obtido pelo token. O corpo não aceita produtor_id.
Cliente, produtos e pacote reutilizado são consultados dentro da conta autenticada.
IDs de outra conta devem produzir a mesma resposta de validação usada para um ID inexistente, sem revelar sua existência.
A API recalcula valores derivados e nunca aceita IDs internos de transportadora, custo, margem ou preço de frete.

Erros

Status	Quando
`401`	Token ausente, inválido ou revogado.
`403`	Token sem a permissão `criar_pedido_api`; ou conta que não é um produtor ativo. Neste segundo caso o corpo é `{ "message": "A conta autenticada não está autorizada a criar pedidos." }`.
`422`	Cliente ou produto inválido, produto repetido, chave extra, valor inválido, embalagem indisponível ou serviço de frete indisponível.
`500`	Falha inesperada; o corpo é `{ "message": "Não foi possível criar o pedido." }` e nenhuma criação parcial deve permanecer.

json

{
  "message": "Os dados fornecidos são inválidos.",
  "errors": {
    "itens.0.produto_id": [
      "Um ou mais produtos informados são inválidos."
    ],
    "frete_selecionado": [
      "A transportadora ou o serviço não está disponível. Calcule o frete novamente."
    ]
  }
}

As mensagens mais comuns, com a chave exata em que aparecem:

Chave em `errors`	Mensagem
`cliente_id`	`O cliente informado é inválido.`
`cliente_id`	`O cliente selecionado não possui um CEP válido para cotação.` (somente com `frete_selecionado`)
`itens.{índice}.produto_id`	`Um ou mais produtos informados são inválidos.`
`itens.{índice}.produto_id`	`O mesmo produto não pode aparecer mais de uma vez.`
`itens.{índice}.valor_unitario`	`O valor unitário deve ser um inteiro em centavos.`
`itens.{índice}.valor_unitario`	`O valor do item excede o limite permitido.`
`itens`	`O valor total do pedido excede o limite permitido.`
`itens`	`Não foi possível montar uma embalagem válida para os produtos.`
`frete_selecionado`	`A transportadora ou o serviço não está disponível. Calcule o frete novamente.`
`itens.{índice}`	`itens.{índice} deve ser um array.` (chave extra dentro do item, ou item que não é objeto)
`frete_selecionado`	`frete selecionado deve ser um array.` (chave extra dentro do objeto)
`parametros_rastreamento`	`parametros rastreamento deve ser um array.` (chave extra dentro do objeto)

Limites

Esta operação não faz:

dividir uma compra em vários pedidos;
aceitar SKU ou código externo no lugar de produto_id;
confiar em preço, prazo, custo ou margem de frete enviados pela integração.

#Quando usar

#Comportamento

#Parâmetros de rastreamento

#Criar com frete pré-selecionado

#Corpo mínimo

#Campos da requisição

#Pré-seleção de frete

#Resposta 201

#Segurança e isolamento

#Erros

#Limites

Quando usar

Comportamento

Parâmetros de rastreamento

Criar com frete pré-selecionado

Corpo mínimo

Campos da requisição

Pré-seleção de frete

Resposta `201`

Segurança e isolamento

Erros

Limites