Changelog

O que mudou na API, do mais novo para o mais antigo.

Cada release tem uma data (o dia em que entrou em produção), um resumo do que muda para quem integra e a lista de mudanças. A mesma lista está em /changelog.json, para o seu sistema acompanhar.

Como ler uma release

Tipo	O que significa	Precisa mexer no seu sistema?
Novo	Rota, campo, filtro, evento ou código de erro que não existia.	Não. O seu sistema deve ignorar o que não conhece.
Alterado	Comportamento que mudou sem quebrar o contrato (um limite, uma mensagem, um padrão).	Só se a linha trouxer uma ação.
Corrigido	Algo que não funcionava como a documentação dizia.	Só se você contornava o defeito.
Segurança	Correção ou endurecimento de segurança.	Leia sempre: pode pedir troca de token ou de segredo.
Descontinuado	Continua funcionando, mas vai sair na próxima versão da API. A rota passa a responder com os cabeçalhos`Deprecation` e `Sunset`.	Sim, com prazo: migre antes da data.
Removido	Deixou de existir. Só acontece numa versão nova da API (`v2`).	Sim.

Dentro da v1 nada quebra Mudanças que acrescentam entram sem aviso prévio e não mudam a versão. Mudanças que quebram integrações só acontecem numa versão nova, anunciada aqui com antecedência e com a anterior mantida por pelo menos 12 meses. Veja Versões.

v1 — Primeira versão

Em testes com os primeiros parceiros — ainda sem data de publicação. A API completa para o sistema do parceiro: catálogo e estoque, clientes, pedidos, financeiro, etiquetas e a loja no HUB, com webhooks e um ambiente de testes.

Autenticação

Novo Integrações com token de acesso, criadas pelo parceiro no painel. Ver
Novo Permissões por integração, dentro do teto liberado pela OTL. Ver
Novo Versão nova dos Termos de Uso da API: prazo de 7 dias para o parceiro aceitar, com o cabeçalho Aviso-Termos-Api durante o prazo e 403 TERMOS_API_PENDENTES depois dele. Ver
Novo A OTL pode suspender uma integração específica: ela responde 403 INTEGRACAO_SUSPENSA até ser religada, e as outras do parceiro seguem funcionando. Ver

Rotas

Novo GET /v1/eu e GET /v1/conta. Ver
Novo GET /v1/produtos, com paginação por cursor e sincronização por atualizadoDesde; GET /v1/produtos/{sku} e …/estoque. Ver
Novo GET /v1/categorias e GET /v1/numeracoes. Ver
Novo GET, POST, PATCH e DELETE em /v1/clientes — a agenda de clientes do parceiro. Ver
Novo GET /v1/pedidos e GET /v1/pedidos/{id} — pedidos em leitura, com resultado, rastreios e anexos. Ver
Novo POST /v1/pedidos — criar pedido, com Idempotency-Key obrigatória e referenciaExterna única por parceiro; POST /v1/pedidos/validar simula sem criar. Ver
Novo Valor de venda, despesas, rastreios e comprovantes de um pedido. Ver
Novo GET /v1/financeiro/saldo e GET /v1/financeiro/extrato. Ver
Novo Etiquetas: GET /v1/superfrete, cotar, emitir (com Idempotency-Key obrigatória), listar e cancelar. Ver
Segurança Envio de arquivo: o formato é conferido pelo conteúdo, não pelo Content-Type declarado. PDF com script, arquivo embutido, formulário ou senha é recusado com 400 VALIDACAO. Ver
Novo /v1/loja-hub — a loja do parceiro no HUB: configuração, publicar e despublicar, seleção de produtos, estatísticas, aparência, banners, logo e o texto próprio de cada produto. Ver

Webhooks

Novo Avisos automáticos para um endereço do parceiro, assinados, com novas tentativas e histórico no painel. Ver
Novo Eventos de produto: estoque, preço, nome, categorias, entrada e saída do catálogo. Ver
Novo Mudança em massa no catálogo chega num aviso só, produto.lote, com a lista do que mudou em cada produto. Ver
Novo Eventos de pedido: criado, status alterado, rastreio adicionado, comprovante validado. Ver
Novo Eventos de etiqueta: emitida e status alterado (impressa, despachada, cancelada). Ver
Novo Eventos de cliente: criado, atualizado, removido — com o resumo do cliente, sem contato nem endereço. Ver
Novo Evento de financeiro: lançamento no saldo. Ver

Sandbox

Novo Ambiente de testes com catálogo espelhado da produção; o token de teste é criado no painel oficial. Ver
Novo Simuladores (/v1/sandbox/…): status do pedido e da etiqueta, validar comprovante e rastreio, lançamento no saldo, estoque de uma numeração e reset da conta. Ver
Novo Webhooks de cada token de teste cadastrados no painel oficial; recebem também os eventos de produto das mudanças reais do catálogo. Ver

Documentação

Novo Painel "Testar agora" em cada página de referência, chamando o ambiente de testes. Ver
Novo Guias: da venda no marketplace ao pedido, pausar o anúncio quando o estoque zera e emitir etiqueta sem cobrança duplicada. Ver
Novo Coleção do Postman gerada da própria documentação, com os simuladores numa pasta à parte. Ver