Criar pedido

POST /api/v1/pedidos

Cria um pedido usando um cliente e um pacote pertencentes ao produtor autenticado. O pacote define os itens do pedido; campos livres de itens enviados pelo cliente da API não são usados. Com tipo_frete: false, a Paylog usa o leilão de frete configurado na conta. Com tipo_frete: true, frete_selecionado deve conter exatamente os códigos retornados pela calculadora de frete; a Paylog refaz a cotação e persiste apenas os valores confiáveis do servidor. O campo opcional faturar controla o próximo passo: true solicita o início do fluxo de faturamento, que pode ser imediato ou agendado conforme o prazo de faturamento configurado na conta; omitido ou false mantém o pedido pendente para revisão e posterior aprovação por POST /api/v1/pedidos/{id}/aprovar. Quando notafiscal é enviado, o fluxo fiscal usa a nota própria informada.

POST Requisição

bash

curl -X POST "https://ev.paylog.cash/api/v1/pedidos" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "cliente_id": 0,
    "pacote_id": 0,
    "tipo_frete": true,
    "frete_selecionado": {
      "transportadora_codigo": "string",
      "servico_codigo": "string"
    },
    "valor_venda": 0,
    "referencia_externa": "string",
    "faturar": true,
    "parametros_rastreamento": {
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "utm_id": "string",
      "src": "string",
      "sck": "string",
      "xcod": "string",
      "campaign_code": "string",
      "campaign_name": "string",
      "origin_url": "https://example.com",
      "query_params": {}
    },
    "info_extra_notafiscal": {
      "descricao": "string",
      "duplicatas": [
        {
          "codigo": 0,
          "data_vencimento": "string",
          "valor": 0
        }
      ]
    },
    "notafiscal": {
      "chave": "string",
      "numero": 0,
      "valor": 0,
      "imposto": 0,
      "link_pdf": "https://example.com",
      "link_xml": "https://example.com"
    }
  }'

php

use Illuminate\Support\Facades\Http;

$response = Http::withToken('YOUR_TOKEN')
    ->acceptJson()
    ->post('https://ev.paylog.cash/api/v1/pedidos', [
    'cliente_id' => 0,
    'pacote_id' => 0,
    'tipo_frete' => true,
    'frete_selecionado' => [
      'transportadora_codigo' => 'string',
      'servico_codigo' => 'string'
    ],
    'valor_venda' => 0,
    'referencia_externa' => 'string',
    'faturar' => true,
    'parametros_rastreamento' => [
      'utm_source' => 'string',
      'utm_medium' => 'string',
      'utm_campaign' => 'string',
      'utm_content' => 'string',
      'utm_term' => 'string',
      'utm_id' => 'string',
      'src' => 'string',
      'sck' => 'string',
      'xcod' => 'string',
      'campaign_code' => 'string',
      'campaign_name' => 'string',
      'origin_url' => 'https://example.com',
      'query_params' => []
    ],
    'info_extra_notafiscal' => [
      'descricao' => 'string',
      'duplicatas' => [
        [
          'codigo' => 0,
          'data_vencimento' => 'string',
          'valor' => 0
        ]
      ]
    ],
    'notafiscal' => [
      'chave' => 'string',
      'numero' => 0,
      'valor' => 0,
      'imposto' => 0,
      'link_pdf' => 'https://example.com',
      'link_xml' => 'https://example.com'
    ]
  ]);

javascript

const response = await fetch("https://ev.paylog.cash/api/v1/pedidos", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "cliente_id": 0,
    "pacote_id": 0,
    "tipo_frete": true,
    "frete_selecionado": {
      "transportadora_codigo": "string",
      "servico_codigo": "string"
    },
    "valor_venda": 0,
    "referencia_externa": "string",
    "faturar": true,
    "parametros_rastreamento": {
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "utm_id": "string",
      "src": "string",
      "sck": "string",
      "xcod": "string",
      "campaign_code": "string",
      "campaign_name": "string",
      "origin_url": "https://example.com",
      "query_params": {}
    },
    "info_extra_notafiscal": {
      "descricao": "string",
      "duplicatas": [
        {
          "codigo": 0,
          "data_vencimento": "string",
          "valor": 0
        }
      ]
    },
    "notafiscal": {
      "chave": "string",
      "numero": 0,
      "valor": 0,
      "imposto": 0,
      "link_pdf": "https://example.com",
      "link_xml": "https://example.com"
    }
  }),
});

python

import requests

response = requests.post(
    "https://ev.paylog.cash/api/v1/pedidos",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json",
    },
    json={
    "cliente_id": 0,
    "pacote_id": 0,
    "tipo_frete": True,
    "frete_selecionado": {
      "transportadora_codigo": "string",
      "servico_codigo": "string"
    },
    "valor_venda": 0,
    "referencia_externa": "string",
    "faturar": True,
    "parametros_rastreamento": {
      "utm_source": "string",
      "utm_medium": "string",
      "utm_campaign": "string",
      "utm_content": "string",
      "utm_term": "string",
      "utm_id": "string",
      "src": "string",
      "sck": "string",
      "xcod": "string",
      "campaign_code": "string",
      "campaign_name": "string",
      "origin_url": "https://example.com",
      "query_params": {}
    },
    "info_extra_notafiscal": {
      "descricao": "string",
      "duplicatas": [
        {
          "codigo": 0,
          "data_vencimento": "string",
          "valor": 0
        }
      ]
    },
    "notafiscal": {
      "chave": "string",
      "numero": 0,
      "valor": 0,
      "imposto": 0,
      "link_pdf": "https://example.com",
      "link_xml": "https://example.com"
    }
  },
)

ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://ev.paylog.cash/api/v1/pedidos")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer YOUR_TOKEN"
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request.body = {
  "cliente_id" => 0,
  "pacote_id" => 0,
  "tipo_frete" => true,
  "frete_selecionado" => {
    "transportadora_codigo" => "string",
    "servico_codigo" => "string"
  },
  "valor_venda" => 0,
  "referencia_externa" => "string",
  "faturar" => true,
  "parametros_rastreamento" => {
    "utm_source" => "string",
    "utm_medium" => "string",
    "utm_campaign" => "string",
    "utm_content" => "string",
    "utm_term" => "string",
    "utm_id" => "string",
    "src" => "string",
    "sck" => "string",
    "xcod" => "string",
    "campaign_code" => "string",
    "campaign_name" => "string",
    "origin_url" => "https://example.com",
    "query_params" => {}
  },
  "info_extra_notafiscal" => {
    "descricao" => "string",
    "duplicatas" => [
      {
        "codigo" => 0,
        "data_vencimento" => "string",
        "valor" => 0
      }
    ]
  },
  "notafiscal" => {
    "chave" => "string",
    "numero" => 0,
    "valor" => 0,
    "imposto" => 0,
    "link_pdf" => "https://example.com",
    "link_xml" => "https://example.com"
  }
}.to_json

response = http.request(request)

200 Resposta

json

{
  "code": 0,
  "message": "string",
  "pedido": 0
}

Corpo da requisição

application/json

object

cliente_id integer Obrigatório

Obrigatório. Cliente existente e pertencente ao produtor.
pacote_id integer Obrigatório

Obrigatório. Pacote existente, não excluído e pertencente ao produtor.
tipo_frete boolean Obrigatório

Obrigatório. false usa o leilão de frete configurado na conta. true exige frete_selecionado com os códigos retornados por POST /api/v1/frete/calcular.
frete_selecionado object
Opção retornada pela calculadora de frete. A Paylog refaz a cotação e não aceita preço, prazo, custo ou margem enviados pela integração.
- transportadora_codigo string Obrigatório
  
  Código estável da transportadora retornado pela calculadora.
- servico_codigo string Obrigatório
  
  Código exato do serviço retornado pela calculadora.
valor_venda integer Obrigatório

Obrigatório. Valor da venda em centavos.
referencia_externa string

Opcional. Identificador do pedido no sistema de origem.
faturar boolean

Opcional. true inicia o faturamento imediatamente; omitido ou false mantém o pedido pendente para aprovação posterior.
parametros_rastreamento object aceita nulo
Opcional. UTMs e identificadores de campanha associados ao pedido. Todos os campos internos também são opcionais. Quando omitido, vazio ou composto somente por valores vazios, nenhum registro de rastreamento é criado.
- utm_source string aceita nulo
  
  Opcional. Origem da campanha.
- utm_medium string aceita nulo
  
  Opcional. Mídia ou canal.
- utm_campaign string aceita nulo
  
  Opcional. Nome ou código da campanha.
- utm_content string aceita nulo
  
  Opcional. Variação do conteúdo ou criativo.
- utm_term string aceita nulo
  
  Opcional. Termo associado.
- utm_id string aceita nulo
  
  Opcional. ID externo da campanha.
- src string aceita nulo
  
  Opcional. Código de origem.
- sck string aceita nulo
  
  Opcional. Código de rastreamento.
- xcod string aceita nulo
  
  Opcional. Código complementar.
- campaign_code string aceita nulo
  
  Opcional. Código externo da campanha.
- campaign_name string aceita nulo
  
  Opcional. Nome externo da campanha.
- origin_url string uri aceita nulo
  
  Opcional. URL HTTP/HTTPS de origem.
- query_params object aceita nulo
  
  Opcional. Aceita somente identificadores públicos de atribuição da lista permitida. Objetos, listas, segredos, tokens de sessão e chaves arbitrárias não são aceitos.
info_extra_notafiscal object
- descricao string Obrigatório
  
  Obrigatório quando info_extra_notafiscal é enviado.
- duplicatas array Obrigatório
  
  Obrigatório quando info_extra_notafiscal é enviado.
  
  Itens
  
  object
  
  codigo number Obrigatório
  
  Obrigatório dentro de duplicatas. Código da parcela.
  
  data_vencimento string Obrigatório
  
  Obrigatório dentro de duplicatas. Data de vencimento aceita pelo emissor fiscal.
  
  valor integer Obrigatório
  
  Obrigatório dentro de duplicatas. Valor em centavos.
notafiscal object
- chave string Obrigatório
  
  Obrigatório quando notafiscal é enviada. Chave da NF-e.
- numero integer Obrigatório
  
  Obrigatório quando notafiscal é enviada. Número da nota.
- valor integer Obrigatório
  
  Obrigatório quando notafiscal é enviada. Total em centavos.
- imposto integer
  
  Opcional. Imposto em centavos; padrão 0.
- link_pdf string uri Obrigatório
  
  Obrigatório quando notafiscal é enviada. URL do DANFE.
- link_xml string uri
  
  Opcional. URL do XML da NF-e.

Respostas

200

Pedido criado.

application/json

object

code integer Obrigatório
message string Obrigatório
pedido integer Obrigatório

ID interno do pedido criado.

400

Requisição inválida.

application/json

object

code integer

Código legado do erro, normalmente 400.
message string Obrigatório

Resumo do erro de validação.
erros object

Erros por campo retornados pelos endpoints legados.
errors object

Erros por campo retornados por validadores no formato atual.

401

Token ausente/inválido, ou cliente/pacote não pertencente ao produtor.

application/json

object

Mensagem de erro ou informação. Alguns erros legados omitem code.

code integer

Código numérico quando fornecido pelo endpoint.
message string

Mensagem legível.

403

O token é válido, mas a conta não possui a permissão necessária para esta operação. O envelope é gerado pelo tratador global de exceções e usa a chave errors (string), não message.

application/json

object

Envelope produzido pelo tratador global de exceções para falhas HTTP que não são geradas pelos controladores — principalmente 403 (permissão ausente) e 405 (verbo não suportado). Difere dos erros dos controladores por usar errors no lugar de message.

errors string Obrigatório

Mensagem da exceção HTTP.
code integer Obrigatório

Código HTTP repetido no corpo.

422

Dados condicionais da nota fiscal inválidos.

application/json

object

code integer

Código legado do erro, normalmente 400.
message string Obrigatório

Resumo do erro de validação.
erros object

Erros por campo retornados pelos endpoints legados.
errors object

Erros por campo retornados por validadores no formato atual.

500

Falha interna durante o processamento.

application/json

object

Mensagem de erro ou informação. Alguns erros legados omitem code.

code integer

Código numérico quando fornecido pelo endpoint.
message string

Mensagem legível.