Especificação de Eventos
Referência canônica para as categorias de eventos integradas — propósito, campos comuns e restrições de ordenação.
Last updated on
Esta página é a referência canônica para a modelagem de eventos no nível macro/base.
Categorias lógicas de eventos integradas
| Tipo | Propósito |
|---|---|
ACTOR | Concede ou atualiza papéis/permissões de participantes na linha do tempo do documento. |
CLOSE | Encerra o documento para atualizações futuras (exceto fluxos de relação específicos). |
CANCEL | Cancela o documento e bloqueia ações futuras. Exige um reason. |
RELATED | Cria vínculos de relação entre documentos. |
UPDATE | Atualiza campos selecionados relacionados à visibilidade do documento. |
OUTPUT | Nome convencional para um evento que cria um documento downstream. |
CUSTOM | Nomes de eventos específicos da metodologia/aplicação. |
Um documento downstream é criado pela presença do objeto target em qualquer evento, não pelo
nome do evento — OUTPUT é o nome convencional para esse padrão, e é tratado como evento CUSTOM.
Um evento CANCEL precisa carregar uma entrada metadata.attributes chamada reason com valor não
vazio; omiti-la retorna 400 com The reason metadata is required for CANCEL events.
Para padrões de implementação usando categorias de eventos específicas, consulte:
ACTOR: Guia de PermissõesCANCEL/CLOSE: Guia de Tratamento de ErrosRELATED/OUTPUT: Submetendo um MassIDUPDATE: Guia de Privacidade e MascaramentoCUSTOM: Definidos por metodologia — consulte os guias de integração por metodologia para os eventos e regras de validação específicos.
Campos comuns de eventos
A maioria dos payloads de eventos compartilha estes campos principais:
nameexternalCreatedAtisPublicmetadataparticipantId(ou um objetoparticipantinline, que faz find-or-create do registro)addressId(ou um objetoaddressinline, que faz find-or-create do registro)
Todo evento precisa carregar exatamente um entre participantId/participant e exatamente um entre
addressId/address. Enviar as duas formas, ou nenhuma, falha com 400 VALIDATION_ERROR
(You must pass participantId or participant field, not both, not neither). A regra é idêntica nos
endpoints de evento individual e de lote.
attachments(opcional)deduplicationId(opcional)
Dê a todo evento ACTOR um label — o label é o papel do participante. O schema não impõe isso, então é uma exigência da plataforma, não da validação da requisição. Cada guia de integração por metodologia define os labels permitidos e a ordem obrigatória. Não utilize campos de papel descontinuados como actor-type.
Um label ausente ou não reconhecido não gera erro. O evento é aceito, mas o participante não recebe
nenhuma parcela de recompensa e seu nome é retido do registro público — uma falha que você só percebe
mais adiante. Os labels de documentos MassID são Bin Custodian, Hauler, Integrator, Processor,
Recycler e Waste Generator (Integrator normaliza para o papel Network Integrator).
Eventos CUSTOM
Eventos CUSTOM aceitam qualquer name — Integradores podem definir e enviar quaisquer eventos operacionais adequados ao seu fluxo de trabalho. A plataforma não restringe nomes de eventos CUSTOM no nível da API.
Metodologias definem seus próprios vocabulários de eventos CUSTOM esperados e os validam por meio de regras de aplicação. Consulte o guia de integração por metodologia relevante para os eventos específicos e regras de validação aplicáveis.
Restrições de ordenação e propagação
- Os timestamps dos eventos devem permanecer cronologicamente consistentes.
- O comportamento de propagação é restrito e deve ser explicitamente validado em testes de integração.
- Utilize padrões de retentativas determinísticos para evitar entradas duplicadas na linha do tempo.
Referência de endpoint: API de Eventos.