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.
Escopo de eventos da v1
A v1 emite dois eventos de webhook:
| Evento | Quando |
|---|---|
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):
order.createdcatalog.product_updatedstock.changed
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.