Documentação da API Paylog Documentação da API Paylog API pública v1
API v1

Pedidos

Liste, consulte e execute comandos explícitos no ciclo de vida dos pedidos.

Nesta página 29

A API v1 permite listar, consultar e executar comandos explícitos sobre pedidos do produtor autenticado. As duas formas de criação possuem páginas dedicadas.

Importante

Todas as rotas desta página exigem Authorization: Bearer {token} e Accept: application/json. O token precisa pertencer ao produtor dos dados consultados. A API aplica o escopo da conta em todas as operações e nunca retorna pedidos de outro produtor.

Observação

Nenhuma rota desta página 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).

Operações disponíveis

Método Rota Permissão do token Finalidade
GET /api/v1/pedidos listar_pedido_api Listar e filtrar pedidos
GET /api/v1/pedidos/{id} listar_pedido_api Consultar um pedido
GET /api/v1/pedidos/{id}/rastreamento listar_pedido_api Consultar o histórico de rastreamento
POST /api/v1/pedidos criar_pedido_api Criar um pedido com um pacote
POST /api/v1/pedidos/carrinho criar_pedido_api Criar um pedido informando os produtos
POST /api/v1/pedidos/{id}/aprovar editar_pedido_api Aprovar e enviar o pedido para processamento
POST /api/v1/pedidos/{id}/cancelar editar_pedido_api Cancelar um pedido que ainda não saiu
POST /api/v1/pedidos/{id}/pausar editar_pedido_api Pausar o processamento do pedido
POST /api/v1/pedidos/{id}/retomar editar_pedido_api Retomar um pedido pausado

Convenções dos campos

As tabelas desta página usam as seguintes classificações:

Classificação Significado
Obrigatório Deve ser enviado em toda requisição daquela operação
Opcional Pode ser omitido
Condicional Torna-se obrigatório quando o objeto ou a operação relacionada é enviada
Sempre A chave sempre aparece na resposta
Nullable A chave sempre aparece, mas pode conter null
Omitido A chave não faz parte da resposta

Valores monetários nas respostas

Os valores monetários do pedido formatado são inteiros em centavos:

json
{
  "frete": 5781,
  "valor_unitario": 12990,
  "subtotal": 12990
}

Por exemplo, 12990 representa R$ 129,90. Essa regra vale para frete, itens[].valor_unitario e itens[].subtotal.

Listar pedidos

GET

http
GET /api/v1/pedidos

A listagem retorna somente pedidos vinculados aos clientes do produtor autenticado, com até 500 pedidos por página.

Filtros

Parâmetro Tipo Obrigatoriedade Regra
email string Opcional Correspondência exata com o e-mail do cliente
cpf string Opcional Aceita CPF com ou sem pontuação; a comparação também usa apenas os dígitos
status integer Opcional Código válido de status entre 1 e 20
order string Opcional asc ou desc; padrão asc, ordenado pelo ID do pedido
page integer Opcional Página da resposta paginada; padrão 1

Os filtros podem ser combinados:

bash
curl --request GET \
  --get 'https://ev.paylog.cash/api/v1/pedidos' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN' \
  --data-urlencode 'status=7' \
  --data-urlencode '[email protected]' \
  --data-urlencode 'cpf=529.982.247-25' \
  --data-urlencode 'order=desc' \
  --data-urlencode 'page=1'

Resposta 200

json
{
  "current_page": 1,
  "data": [
    {
      "id": 64913,
      "referencia_externa": null,
      "codigo_transacao": "DOCS-ORDER-20260722123523",
      "status": "Enviado",
      "status_code_id": 7,
      "motivo_parado_id": null,
      "motivo_devolucao_id": null,
      "frete": 5781,
      "data_saida": "2026-07-22T19:13:00-03:00",
      "data_entrega": null,
      "created_at": "2026-07-22 12:35:23",
      "updated_at": "2026-07-22 12:35:23",
      "qnt_itens": 1,
      "itens": [
        {
          "id": 63619,
          "pedido_id": 64913,
          "quantidade": 1,
          "valor_unitario": 12990,
          "subtotal": 12990,
          "pacote_id": 1481,
          "codigo_plataforma": "7867",
          "descricao": "Kit Exemplo API",
          "created_at": "2026-07-22T15:35:23.000000Z",
          "updated_at": "2026-07-22T15:35:23.000000Z"
        }
      ],
      "documentos_fiscais": [],
      "cliente": {
        "id": 291955,
        "nome": "Cliente Exemplo API",
        "email": "[email protected]",
        "cpf": "52998224725",
        "data_nascimento": "1972-05-14T03:00:00.000000Z",
        "endereco": "Avenida Paulista",
        "cep": "01310100",
        "numero": "1000",
        "complemento": "Conjunto 101",
        "estado": "SP",
        "bairro": "Bela Vista",
        "cidade": "Sao Paulo",
        "pais": "Brasil",
        "celular": "11999887766",
        "telefone": "1133221100",
        "created_at": "2026-07-22T15:35:23.000000Z",
        "updated_at": "2026-07-22T15:36:57.000000Z",
        "referencia_externa": "CLIENTE-EXTERNO-001"
      },
      "transportadora": {
        "codigo": "correios",
        "nome": "Correios"
      },
      "rastreamento": {
        "codigo": "AD123456789BR",
        "transportadora": {
          "codigo": "correios",
          "nome": "Correios"
        },
        "servico": "SEDEX",
        "url_rastreamento": "https://ev.paylog.cash/rastreio/AD123456789BR",
        "url_transportadora": "https://rastreamento.correios.com.br/app/index.php?objetos=AD123456789BR",
        "status": {
          "codigo": 30,
          "descricao": "Em trânsito"
        },
        "comprovante_entrega": null
      }
    }
  ],
  "first_page_url": "https://ev.paylog.cash/api/v1/pedidos?page=1",
  "from": 1,
  "last_page": 1,
  "last_page_url": "https://ev.paylog.cash/api/v1/pedidos?page=1",
  "links": [
    {
      "url": null,
      "label": "Anterior",
      "page": null,
      "active": false
    },
    {
      "url": "https://ev.paylog.cash/api/v1/pedidos?page=1",
      "label": "1",
      "page": 1,
      "active": true
    },
    {
      "url": null,
      "label": "Próxima",
      "page": null,
      "active": false
    }
  ],
  "next_page_url": null,
  "path": "https://ev.paylog.cash/api/v1/pedidos",
  "per_page": 500,
  "prev_page_url": null,
  "to": 1,
  "total": 1
}

Campos da paginação

Campo Tipo Presença Descrição
current_page integer Sempre Página atual
data array<pedido> Sempre Pedidos da página; pode ser um array vazio
first_page_url string Sempre URL da primeira página
from integer|null Nullable Posição inicial nesta página
last_page integer Sempre Número da última página
last_page_url string Sempre URL da última página
links array<object> Sempre Links de navegação gerados pelo paginador
next_page_url string|null Nullable URL da próxima página
path string Sempre URL base da coleção
per_page integer Sempre Fixo em 500
prev_page_url string|null Nullable URL da página anterior
to integer|null Nullable Posição final nesta página
total integer Sempre Total de pedidos encontrados

Filtros inválidos

Um status fora da tabela de códigos retorna 400:

json
{
  "code": 400,
  "message": "Requisição inválida",
  "erros": [
    "Parametro 'status' contém um valor não encontrado"
  ]
}

Um order diferente de asc ou desc retorna 400 com a mensagem correspondente:

json
{
  "code": 400,
  "message": "Requisição inválida",
  "erros": [
    "Parametro 'order' contém um valor não válido"
  ]
}

email e cpf não são validados: um valor sem correspondência simplesmente devolve uma página vazia (total: 0), não um erro.

Consultar um pedido

GET

http
GET /api/v1/pedidos/{id}

O identificador pode ser:

  1. o ID numérico do pedido no Paylog; ou
  2. o codigo_transacao de um pedido criado pela integração API.

A busca é feita em uma única consulta que casa o ID do Paylog ou o codigo_transacao, este último limitado aos pedidos criados pela plataforma API. Em ambos os casos, o pedido precisa pertencer ao produtor autenticado; caso contrário a resposta é 401.

bash
curl --request GET \
  --url 'https://ev.paylog.cash/api/v1/pedidos/64913' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

Resposta 200

json
{
  "code": 200,
  "pedido": {
    "id": 64913,
    "referencia_externa": null,
    "codigo_transacao": "DOCS-ORDER-20260722123523",
    "status": "Enviado",
    "status_code_id": 7,
    "motivo_parado_id": null,
    "motivo_devolucao_id": null,
    "frete": 5781,
    "data_saida": "2026-07-22T19:13:00-03:00",
    "data_entrega": null,
    "created_at": "2026-07-22 12:35:23",
    "updated_at": "2026-07-22 12:35:23",
    "qnt_itens": 1,
    "itens": [
      {
        "id": 63619,
        "pedido_id": 64913,
        "quantidade": 1,
        "valor_unitario": 12990,
        "subtotal": 12990,
        "pacote_id": 1481,
        "codigo_plataforma": "7867",
        "descricao": "Kit Exemplo API",
        "created_at": "2026-07-22T15:35:23.000000Z",
        "updated_at": "2026-07-22T15:35:23.000000Z"
      }
    ],
    "documentos_fiscais": [
      {
        "tipo": "nfe_danfe",
        "formato": "pdf",
        "nome": "DANFE da NF-e",
        "url": "https://example.com/notas/21230.pdf",
        "chave": "35260741904774000124550010000109841929722483",
        "numero": 10984
      },
      {
        "tipo": "nfe_xml",
        "formato": "xml",
        "nome": "XML da NF-e",
        "url": "https://example.com/notas/21230.xml",
        "chave": "35260741904774000124550010000109841929722483",
        "numero": 10984
      },
      {
        "tipo": "mini_danfe",
        "formato": "pdf",
        "nome": "Mini DANFE",
        "url": "https://cdn.paylog.cash/minidanfe/MINIDANFE-10984.pdf",
        "chave": "35260741904774000124550010000109841929722483",
        "numero": 10984
      },
      {
        "tipo": "declaracao_conteudo",
        "formato": "pdf",
        "nome": "Declaração de Conteúdo",
        "url": "https://cdn.paylog.cash/dcs/DC-64913.pdf",
        "chave": null,
        "numero": null
      },
      {
        "tipo": "dace",
        "formato": "pdf",
        "nome": "DACE da DC-e",
        "url": "https://cdn.paylog.cash/dace/DACE-64913.pdf",
        "chave": "35260741904774000124550010000109841929722483",
        "numero": "10984"
      }
    ],
    "cliente": {
      "id": 291955,
      "nome": "Cliente Exemplo API",
      "email": "[email protected]",
      "cpf": "52998224725",
      "data_nascimento": "1972-05-14T03:00:00.000000Z",
      "endereco": "Avenida Paulista",
      "cep": "01310100",
      "numero": "1000",
      "complemento": "Conjunto 101",
      "estado": "SP",
      "bairro": "Bela Vista",
      "cidade": "Sao Paulo",
      "pais": "Brasil",
      "celular": "11999887766",
      "telefone": "1133221100",
      "created_at": "2026-07-22T15:35:23.000000Z",
      "updated_at": "2026-07-22T15:36:57.000000Z",
      "referencia_externa": "CLIENTE-EXTERNO-001"
    },
    "transportadora": {
      "codigo": "correios",
      "nome": "Correios"
    },
    "rastreamento": {
      "codigo": "AD123456789BR",
      "transportadora": {
        "codigo": "correios",
        "nome": "Correios"
      },
      "servico": "SEDEX",
      "url_rastreamento": "https://ev.paylog.cash/rastreio/AD123456789BR",
      "url_transportadora": "https://rastreamento.correios.com.br/app/index.php?objetos=AD123456789BR",
      "status": {
        "codigo": 30,
        "descricao": "Em trânsito"
      },
      "comprovante_entrega": null
    }
  }
}
Observação

A API de pedidos retorna somente o resumo mais recente em rastreamento. Para consultar a linha do tempo completa, use Rastrear Pedido. Mudanças de rastreio também são entregues pelos Webhooks v2.

Campos do pedido formatado

Campo Tipo Presença Descrição
id integer Sempre ID do pedido no Paylog
referencia_externa string|null Nullable Referência definida pela integração
codigo_transacao string|null Nullable Identificador da transação na plataforma de origem; também pode localizar pedidos criados pela integração API
status string Sempre Descrição do status atual
status_code_id integer Sempre Código do status atual
motivo_parado_id integer|null Nullable Motivo do bloqueio quando o pedido está parado
motivo_devolucao_id integer|null Nullable Motivo atual quando o pedido está em devolução
frete integer|null Nullable Valor cobrado pelo frete em centavos
data_saida string|null Nullable Data e hora da expedição em ISO 8601; null enquanto não houver bip de saída
data_entrega string|null Nullable Data de entrega registrada
created_at string Sempre Criação em YYYY-MM-DD HH:mm:ss
updated_at string Sempre Última atualização em YYYY-MM-DD HH:mm:ss
qnt_itens integer Sempre Quantidade total de itens
itens array<item> Sempre Itens do pedido; pode ser vazio em registros legados inconsistentes
documentos_fiscais array<documento> Sempre Arquivos fiscais registrados e disponíveis para download; array vazio quando inexistentes
cliente object Sempre Cliente vinculado ao pedido
transportadora object|null Nullable Somente codigo e nome; identifica a transportadora atribuída mesmo antes da emissão do rastreio
rastreamento object|null Nullable Resumo mais recente; consulte Rastrear Pedido para o histórico completo

Campos de itens[]

Campo Tipo Presença Descrição
id integer Sempre ID do item
pedido_id integer Sempre ID do pedido
quantidade integer Sempre Quantidade do item
valor_unitario integer Sempre Valor unitário em centavos
subtotal integer Sempre Subtotal em centavos
pacote_id integer|null Nullable Pacote relacionado
codigo_plataforma string|null Nullable Código do item na plataforma de origem
descricao string|null Nullable Descrição registrada no item
created_at string|null Nullable Timestamp ISO 8601
updated_at string|null Nullable Timestamp ISO 8601

Campos de documentos_fiscais[]

Campo Tipo Presença Descrição
tipo string Sempre nfe_danfe, nfe_xml, mini_danfe, declaracao_conteudo ou dace
formato string Sempre Formato do arquivo: pdf ou xml
nome string Sempre Nome legível do documento
url string Sempre URL para baixar o arquivo registrado
chave string|null Nullable Chave fiscal, quando aplicável
numero integer|string|null Nullable Número fiscal, quando aplicável

Somente documentos com arquivo ou link registrado são incluídos. A resposta não expõe cálculo de imposto, valores fiscais ou identificadores internos dos documentos.

Campos de cliente

Campo Tipo Presença Descrição
id integer Sempre ID do cliente
nome string|null Nullable Nome completo
email string|null Nullable E-mail
cpf string|null Nullable CPF ou documento cadastrado
data_nascimento string|null Nullable Data em ISO 8601
endereco string|null Nullable Logradouro
cep string|null Nullable CEP
numero string|null Nullable Número do endereço
complemento string|null Nullable Complemento
estado string|null Nullable UF
bairro string|null Nullable Bairro
cidade string|null Nullable Cidade
pais string|null Nullable País
celular string|null Nullable Celular
telefone string|null Nullable Telefone
created_at string|null Nullable Timestamp ISO 8601
updated_at string|null Nullable Timestamp ISO 8601
referencia_externa string|null Nullable Referência externa do cliente

Campos de transportadora

Campo Tipo Presença Descrição
codigo string Sempre quando o objeto existe Código estável da transportadora
nome string Sempre quando o objeto existe Nome de exibição

Campos de rastreamento

rastreamento é null enquanto o pedido não possui código de rastreio. Quando existe, representa somente o estado mais recente:

Campo Tipo Presença Descrição
codigo string Sempre quando o objeto existe Código de rastreio atual
transportadora object|null Nullable Transportadora vinculada a este rastreamento
servico string|null Nullable Serviço ou modalidade usada, como SEDEX
url_rastreamento string|null Nullable Página pública de rastreamento da Paylog (/rastreio/{codigo}) — igual para todas as transportadoras
url_transportadora string|null Nullable Página da própria transportadora, quando ela oferece uma URL por código
status object|null Nullable Código numérico e descrição legível do último status conhecido
comprovante_entrega object|null Nullable Comprovante enviado pela transportadora após a entrega — ver Rastrear Pedido
Importante

O objeto não possui uma chave eventos. Use Rastrear Pedido para consultar o histórico detalhado em ordem cronológica.

Pedido inexistente ou fora da conta

Os dois casos retornam a mesma resposta para não revelar a existência de dados de outro produtor:

json
{
  "code": 401,
  "message": "Não autorizado"
}
Observação

401 cobre token ausente/inválido e pedido inacessível. Um token válido sem a permissão listar_pedido_api recebe 403 antes de o controller rodar — o corpo vem do tratador global de exceções e usa a chave errors (uma string), não message: { "errors": "User does not have the right permissions.", "code": 403 }.

Criar um pedido com pacote

A criação com pacote_id possui uma página dedicada com payloads, seleção de frete, aprovação, nota fiscal e parâmetros opcionais de rastreamento:

Comandos do pedido

Após a criação, o pedido não aceita atualização genérica. Cada mudança de estado usa uma rota POST própria:

Comando Rota Corpo Status resultante Regra principal
Aprovar /api/v1/pedidos/{id}/aprovar Nenhum 10 Pago - Aguardando NF/DC Inicia o faturamento de um pedido pendente ou encerra antecipadamente sua janela de edição
Cancelar /api/v1/pedidos/{id}/cancelar motivo opcional 9 Cancelado Permitido antes da expedição, sujeito às regras da plataforma e do documento fiscal
Pausar /api/v1/pedidos/{id}/pausar motivo opcional 8 Parado (motivo 16 Parado manualmente) Interrompe manualmente um pedido elegível que já entrou no fluxo operacional
Retomar /api/v1/pedidos/{id}/retomar Nenhum 10 Pago - Aguardando NF/DC Retoma somente um pedido pausado manualmente por esta API

O parâmetro {id} aceita somente o ID numérico do pedido no Paylog — a rota é restrita a [0-9]+. codigo_transacao não é aceito nas rotas de comando; um identificador não numérico não casa com a rota e resulta em 404.

Corpo dos comandos

Somente cancelar e pausar aceitam corpo, e ele é opcional:

Campo Tipo Obrigatoriedade Regra
motivo string|null Opcional Máximo de 1.000 caracteres; espaços nas pontas são removidos e um valor vazio equivale a não enviar. Fica registrado no histórico e nas observações do pedido

aprovar e retomar ignoram qualquer corpo enviado.

Aprovar

POST

http
POST /api/v1/pedidos/{id}/aprovar

Aprova um pedido e o envia para a rotina de faturamento, deixando-o no status 10 (Pago - Aguardando NF/DC).

O comando só é aceito quando o pedido não possui data_saida e está em uma destas situações:

  1. status 1 (Pendente); ou
  2. status 8 (Parado) com a janela de edição do produtor ativa e motivo_parado_id igual a 13 (Aguardando Edição do Produtor) — nesse caso a janela é encerrada antecipadamente.

Qualquer outro estado é recusado com 422 e a mensagem Este pedido não pode mais ser aprovado.. O comando não libera pedidos parados por estoque, crédito, erro fiscal ou qualquer outro motivo operacional.

bash
curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/pedidos/64914/aprovar' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

Cancelar

POST

http
POST /api/v1/pedidos/{id}/cancelar

O cancelamento é avaliado nesta ordem e a primeira regra que falhar devolve 422 com a mensagem correspondente:

# Regra Mensagem retornada
1 O status não pode ser final — 7 Enviado, 9 Cancelado, 6 Estornado, 5 Devolvido, 14 Entregue ou 15 Reenviado Pedido já foi enviado (passou pelo BIPAR) e não pode ser cancelado. · Pedido já está cancelado. · Pedido já foi estornado. · Pedido já foi devolvido. · Pedido já foi entregue. · Pedido foi reenviado e não pode ser cancelado.
2 O pedido não pode ter data_saida preenchida Pedido já foi despachado e não pode ser cancelado.
3 O pedido não pode ser do Mercado Livre Pedidos do Mercado Livre devem ser cancelados diretamente na plataforma.
4 O pedido não pode ter nota fiscal emitida Pedido possui Nota Fiscal emitida. Entre em contato com o suporte.

Aprovado o cancelamento, o pedido vai para o status 9 (Cancelado), o evento de estorno dispara (cancelamento da etiqueta, estorno de custos e de estoque, cancelamento da NF-e) e motivo é registrado no histórico e nas observações.

Atenção

O cancelamento é em cascata: todo pedido agregado (order-bump com status 12, vinculado ao pedido principal) é cancelado na mesma transação, com estorno de estoque e de custos próprio. Cancelar o pedido principal cancela os agregados dele.

json
{
  "motivo": "Cancelado pelo sistema de origem"
}

Pausar

POST

http
POST /api/v1/pedidos/{id}/pausar

Pausa temporariamente um pedido elegível que ainda não saiu. O pedido passa para o status 8 (Parado) com motivo_parado_id igual a 16 (Parado manualmente), e a etiqueta gerada é invalidada.

Somente estes status são pausáveis:

Código Descrição
2 Aguardando Faturamento
3 Faturado
4 Preparação
10 Pago - Aguardando NF/DC
11 Correção
13 Falha no Faturamento
16 Aguardando Transportadora
17 Etiqueta Pronta

As recusas retornam 422 com uma destas mensagens:

  • Não é possível pausar um pedido que já foi enviado. — o pedido possui data_saida;
  • O pedido já está pausado. — o pedido já está no status 8;
  • Este pedido não está disponível para pausa. — qualquer outro status fora da tabela acima, inclusive 1 (Pendente), 7 (Enviado), 9 (Cancelado) e 14 (Entregue).

O comando não cancela o pedido nem altera sua composição. motivo é opcional, aceita até 1.000 caracteres e fica registrado para auditoria.

bash
curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/pedidos/64914/pausar' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

Retomar

POST

http
POST /api/v1/pedidos/{id}/retomar

Retoma o fluxo normal somente de um pedido pausado manualmente por esta API. As três condições são cumulativas: status 8 (Parado), motivo_parado_id igual a 16 (Parado manualmente) e data_saida vazia. O pedido volta para o status 10 (Pago - Aguardando NF/DC) e é reenviado para a rotina de faturamento.

Qualquer outra combinação retorna 422 com Este pedido não está disponível para retomada.. Bloqueios por falta de estoque, falta de crédito, erro fiscal, edição do produtor (motivo_parado_id 13) ou qualquer outro motivo operacional não podem ser liberados por esta rota — para a janela de edição do produtor use Aprovar.

bash
curl --request POST \
  --url 'https://ev.paylog.cash/api/v1/pedidos/64914/retomar' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer SEU_TOKEN'

Resposta dos comandos

Os quatro comandos retornam o pedido no mesmo formato de Campos do pedido formatado. A mensagem descreve a ação executada:

jsonc
{
  "code": 200,
  "message": "Pedido cancelado com sucesso.",
  "pedido": {
    "id": 64914,
    "codigo_transacao": "64914",
    "status": "Cancelado",
    "status_code_id": 9,
    "data_saida": null,
    "documentos_fiscais": [],
    "rastreamento": null
    // Demais campos seguem o formato completo documentado acima.
  }
}

As mensagens de sucesso são fixas por comando:

Comando message
Aprovar Pedido entrou na rotina de faturamento.
Cancelar Pedido cancelado com sucesso.
Pausar Pedido pausado com sucesso.
Retomar Pedido retomado e reenviado para faturamento.

Erros dos comandos

HTTP Situação Formato do corpo
401 Token ausente ou inválido, pedido inexistente ou pedido fora da conta autenticada { "code": 401, "message": "Não autorizado" }
403 O token existe mas não possui a permissão editar_pedido_api { "errors": "User does not have the right permissions.", "code": 403 } — envelope do tratador global, com errors no lugar de message
422 Estado atual não permite o comando code + message + o pedido completo
422 motivo inválido (não-string ou acima de 1.000 caracteres) envelope de validação do Laravel: { "message": "...", "errors": { "motivo": [...] } }
500 Falha interna ao executar o comando { "code": 500, "message": "Um erro interno ocorreu ao alterar o pedido. Tente novamente." }
Importante

A recusa por estado (422) devolve o mesmo envelope do sucesso, incluindo a chave pedido com o pedido inalterado. Não trate a presença de pedido como sinal de sucesso — use o código HTTP ou o campo code.

Exemplo de conflito de estado:

jsonc
{
  "code": 422,
  "message": "Pedido já foi despachado e não pode ser cancelado.",
  "pedido": {
    "id": 64914,
    "status": "Enviado",
    "status_code_id": 7,
    "data_saida": "2026-07-22T19:13:00-03:00"
    // Demais campos seguem o formato completo documentado acima.
  }
}
Observação

Um {id} não numérico não casa com a rota do comando e retorna 404. Um corpo JSON malformado é rejeitado pelo framework com 400.

Códigos de status aceitos no filtro

O filtro GET /api/v1/pedidos?status={codigo} aceita todos os códigos atuais:

Código Descrição
1 Pendente
2 Aguardando Faturamento
3 Faturado
4 Preparação
5 Devolvido
6 Estornado
7 Enviado
8 Parado
9 Cancelado
10 Pago - Aguardando NF/DC
11 Correção
12 Pedidos Agregado (Upsell)
13 Falha no Faturamento
14 Entregue
15 Reenviado
16 Aguardando Transportadora
17 Etiqueta Pronta
18 Aguardando Retirada
19 Saiu para Entrega
20 Ao Remetente
Importante

A lista acima serve somente para filtrar consultas. Os comandos não recebem um código de status arbitrário; cada rota representa uma única intenção de negócio.

Motivos de bloqueio (motivo_parado_id)

Quando status_code_id é 8 (Parado), o campo motivo_parado_id identifica o bloqueio. Esta é a lista completa:

Código Descrição Liberável pela API?
1 Falta de Estoque Não
2 Falta de Crédito Não
3 Não Conseguiu Contato Não
4 A pedido do produtor Não
5 Erro fiscal Não
6 Tipo De Emissão não Configurado Não
7 Pacote Desativado Não
8 Produto Desativado Não
9 Produtor Desativado Não
10 Produtor Suspenso Não
11 Inadimplência Não
12 Integração Inativa Não
13 Aguardando Edição do Produtor Sim — via POST /api/v1/pedidos/{id}/aprovar
14 Produto Não Associado Não
15 Erro na Baixa de Estoque Não
16 Parado manualmente Sim — via POST /api/v1/pedidos/{id}/retomar
17 Erro fiscal permanente (emissor) Não
Observação

motivo_parado_id é null sempre que o pedido não está parado. Motivos fora de 13 e 16 exigem intervenção operacional ou de suporte — nenhuma rota pública os libera.

Motivos de devolução (motivo_devolucao_id)

Código Descrição
1 Endereço Incorreto
2 Cliente Insatisfeito
3 Devolvido ao Remetente

motivo_devolucao_id é null enquanto não houver devolução registrada.

Atualizado em 24/07/2026