Versionamento
Versionamento por path /integration/v1, mudanças aditivas sem aviso, breaking changes em /v2 e o escopo de eventos da v1.
A API é versionada pelo path: /integration/v1. A política abaixo define o
que pode mudar dentro de uma versão e o que exige uma nova.
Mudanças aditivas (sem aviso)
Estas mudanças podem ocorrer a qualquer momento, sem aviso de breaking
change, dentro da v1:
- Novos campos opcionais em respostas.
- Novos tipos de evento de webhook.
- Novos códigos de erro.
Cliente tolerante a desconhecidos
Seu cliente deve ignorar campos desconhecidos e eventos que não reconhece
(responda 2xx e descarte). É isso que mantém a integração estável diante de
mudanças aditivas.
Mudanças incompatíveis (nova versão)
Mudanças breaking — remover ou renomear um campo, mudar a semântica de um
campo existente — só acontecem em um novo namespace /integration/v2, com
período de convivência entre as versões.
v1.1 dentro da v1
A v1.1 (inversão do fluxo de pedido OnmIA→ERP + order.created + Fidelidade)
manteve o namespace /integration/v1 — é a semântica do spec que evoluiu,
não a URL. A única remoção dura foi POST /orders + PATCH /…/status +
orders:write, que não tinham consumidor de produção.
Escopo de eventos da v1
A v1 emite três eventos de webhook:
| Evento | Quando |
|---|---|
order.created | Uma vez por pedido, na criação, com o pedido completo (todos os canais). |
order.status_changed | A cada transição de status relevante do pedido. |
webhook.test | Pelo endpoint de teste (POST /webhooks/:id/test). |
Os eventos abaixo estão no roadmap e serão adicionados de forma aditiva (novos tipos de evento, conforme a política acima):
catalog.product_updatedstock.changed- Push de fidelidade (webhook quando o saldo de pontos muda) —
UCP-INT-v121-W-C.
Como são aditivos, ao chegarem não quebram sua integração — desde que seu
receptor responda 2xx e descarte eventos que ainda não reconhece.