Status e histórico do pedido

Endpoints de /api2/history para alterar o status do pedido (ex.: nota_fiscal_emitida, enviado, aguardando_pagamento ou qualquer status custom) com validação automática contra os status configurados na Yep, e listar o histórico completo com comentários, transições e eventos do sistema.

REST JSON Bearer Token Novo em 2026

Visão geral

O recurso de history serve a dois propósitos complementares: auditoria (consulta cronológica de tudo que aconteceu no pedido) e orquestração (registrar comentários e promover transições de status a partir de sistemas externos como ERP, OMS ou WMS). Para regras gerais (paginação, datas, status HTTP), consulte a página principal de Pedidos.

Identificadoresorder_id, order_increment_id ou increment_id.

opt

Mudança de statusstatus aplica e registra a transição.

E-mail automáticoEsta rota não dispara e-mail ao cliente.

Sem alias pluralUse somente /api2/history.

GET/api2/history

Listar histórico do pedido. Identifique o pedido com order_id, order_increment_id ou increment_id.

Por `order_id`

GET /api2/history?order_id=123
Authorization: Bearer {{token}}

Por `order_increment_id`

GET /api2/history?order_increment_id=100000123
Authorization: Bearer {{token}}

Por `increment_id` (alias)

GET /api2/history?increment_id=100000123
Authorization: Bearer {{token}}

Por JSON body

{
  "order_id": 123
}

POST/api2/history

Criar registro de histórico no pedido. Quando status é enviado, o histórico é registrado e o pedido também recebe esse status (validado contra os status existentes).

order_id / order_increment_id

Identificação do pedido.

comment

Texto do comentário no histórico.

status Opcional

Quando enviado, aplica o status ao pedido. Validado contra os status configurados.

is_customer_notified Opcional

Apenas grava a flag no histórico. Este endpoint não dispara e-mail para o cliente.

is_visible_on_front Opcional

Define se o comentário aparece para o cliente no painel.

Comentário interno (sem mudar status)

POST /api2/history
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "comment": "Comentário criado pela API.",
  "is_customer_notified": false,
  "is_visible_on_front": false
}

Mudança de status com comentário visível

POST /api2/history
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "comment": "Pedido enviado para separação.",
  "status": "processing",
  "is_customer_notified": true,
  "is_visible_on_front": true
}

Sobre `is_customer_notified`

Esta flag apenas marca o histórico como "cliente notificado", para fins de relatório. Ela não envia e-mail. Para acionar comunicação ao cliente, use POST /api2/invoice/email ou POST /api2/shipment/email conforme o contexto.

Não existe alias plural — use somente /api2/history.

Formas de uso suportadas

Combinações testadas e homologadas para o recurso History.

Histórico por IDGET /api2/history?order_id=123

Histórico por númeroGET /api2/history?order_increment_id=100000123

Comentário internoPOST /api2/history + comment

Mudança de statusPOST /api2/history + status

Comentário visível ao clientePOST /api2/history + is_visible_on_front=true

Recomendações para integração

Evitar

Esperar que is_customer_notified=true dispare e-mail — ele apenas registra a flag.
Tentar usar /api2/histories ou /api2/historic — o recurso é singular.
Mudar de status sem comentário — a auditoria fica menos rastreável depois.

Trilha de auditoria

Para integrações que precisam justificar transições para auditoria interna ou compliance, padronize o formato do comment: ex.: "[ERP-XYZ #1234] Status atualizado por job de sincronização.". Isso facilita a busca posterior pelo histórico do pedido.

Erros comuns

Status	Exemplo de body	Quando ocorre
`400`	`{"error": "Invalid status"}`	`status` enviado não corresponde a nenhum status configurado na Yep.
`400`	`{"error": "Comment is required"}`	Body sem `comment`.
`401`	`{"error": "Unauthorized"}`	`Authorization` ausente ou token expirado.
`404`	`{"error": "Order not found"}`	`order_id` ou `increment_id` inexistente.
`409`	`{"error": "Conflict on save"}`	Duplicidade ou deadlock em gravação concorrente.