Eventos
Catálogo dos eventos que podem ser assinados, o que dispara cada ação e como buscar o estado do recurso que mudou.
Todo evento tem o formato <recurso>.<ação> — por exemplo sales-orders.update ou customers.create. Você assina os pares que interessam à sua integração; cada evento assinado gera uma entrega independente.
As quatro ações
| Ação | Quando é disparada |
|---|---|
create | O registro foi criado |
update | Qualquer campo do registro mudou — incluindo mudanças de status, baixas, alocações e autorizações fiscais |
delete | O registro foi removido (exclusão lógica — ver DELETE é de mão única) |
restore | Um registro removido foi restaurado |
restore só acontece pelo painel
A API de Integrações não expõe restauração em nenhum recurso — desfazer uma exclusão é
uma operação de usuário. Assine restore se a sua integração precisa reagir a esse
desfazer feito por alguém dentro do bitERP.
Recursos assináveis
Cada recurso abaixo aceita as quatro ações. A coluna Hidratação indica se existe GET /<recurso>/:id na API de Integrações para buscar o estado completo depois de receber o evento.
Cadastros
| Recurso | Eventos | Hidratação |
|---|---|---|
products | products.create, .update, .delete, .restore | GET /products/:id |
customers | customers.create, .update, .delete, .restore | GET /customers/:id |
suppliers | suppliers.create, .update, .delete, .restore | GET /suppliers/:id |
Financeiro
| Recurso | Eventos | Hidratação |
|---|---|---|
financial-accounts | financial-accounts.create, .update, .delete, .restore | GET /financial-accounts/:id |
financial-categories | financial-categories.create, .update, .delete, .restore | GET /financial-categories/:id |
financial-transactions | financial-transactions.create, .update, .delete, .restore | GET /financial-transactions/:id |
receivables | receivables.create, .update, .delete, .restore | GET /receivables/:id |
payables | payables.create, .update, .delete, .restore | GET /payables/:id |
Vendas e faturamento
| Recurso | Eventos | Hidratação |
|---|---|---|
quotes | quotes.create, .update, .delete, .restore | GET /quotes/:id |
sales-orders | sales-orders.create, .update, .delete, .restore | GET /sales-orders/:id |
invoices | invoices.create, .update, .delete, .restore | GET /invoices/:id |
Compras
| Recurso | Eventos | Hidratação |
|---|---|---|
purchase-invoices | purchase-invoices.create, .update, .delete, .restore | GET /purchase-invoices/:id |
Sem endpoint público de hidratação
Estes recursos geram eventos, mas não têm GET /<recurso>/:id na API de Integrações. Você recebe a notificação de que algo mudou, sem uma URL pública para buscar os dados.
| Recurso | Eventos |
|---|---|
fiscal-rules-br | fiscal-rules-br.create, .update, .delete, .restore |
subscription-plans | subscription-plans.create, .update, .delete, .restore |
customer-subscriptions | customer-subscriptions.create, .update, .delete, .restore |
support-tickets | support-tickets.create, .update, .delete, .restore |
email-dispatches | email-dispatches.create, .update, .delete, .restore |
tenant-email-identities | tenant-email-identities.create, .update, .delete, .restore |
Mudanças em itens contam como update do pai
Itens e dados específicos do país não têm eventos próprios — eles fazem parte do recurso a que pertencem:
- Adicionar, alterar ou remover um item de um pedido de venda gera
sales-orders.update, com oiddo pedido. - O mesmo vale para itens de orçamento (
quotes.update), tributos de regra fiscal (fiscal-rules-br.update) e mensagens ou anexos de chamado (support-tickets.update). - Alterar os dados fiscais brasileiros de um produto gera
products.update, com oiddo produto — não um evento separado.
Na prática: uma operação de negócio produz um evento por endpoint assinante, apontando sempre para o registro principal. Você não recebe uma enxurrada de eventos ao salvar um pedido com dez itens.
O que não gera evento
- Recursos administrativos: usuários e permissões, API Keys, configurações da empresa, instalações OAuth, integrações nativas e mapeamento de entidades não são assináveis.
- Dados de referência: bancos, formas de pagamento, unidades de medida, países, estados e cidades são catálogos somente leitura e não produzem eventos.
- Leituras: consultas via API, MCP ou painel nunca disparam webhooks — só escritas.
- A própria configuração de webhooks: alterar endpoints ou entregas não gera evento, o que evita laços de realimentação.
Do evento ao dado completo
O payload identifica o recurso, não o seu conteúdo. Para os recursos com hidratação, o caminho é:
GET /sales-orders/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer sk_...Para eventos create, update e restore, o GET simples basta.
No evento delete, use with_deleted=true
Quando a entrega do evento delete chega, o registro já saiu das consultas padrão — um
GET comum devolve 404. Busque com ?with_deleted=true para receber o registro com o
campo deleted_at preenchido:
GET /sales-orders/550e8400-e29b-41d4-a716-446655440000?with_deleted=trueSe o recurso não tem endpoint público, guarde o evento e trate a notificação como um sinal (por exemplo, para avisar uma pessoa) — não há URL alternativa para buscar o conteúdo.