Eventos

Eventos são o mecanismo principal para evoluir o estado dos documentos. Após a criação de um documento, todas as alterações relevantes são registradas como novos eventos.

Criar evento

curl -X POST "https://example.com/documents/string/events" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "externalCreatedAt": "2020-01-01T00:00:00.000Z",    "isPublic": true,    "name": "CLOSE"  }'

{  "documentId": "28b04f62-8fe2-4332-b854-fe8a922788b5",  "eventId": "JrSRCUhKOxKyUujM2DkH9"}

Utilize POST /documents/{documentId}/events para adicionar um evento à linha do tempo de um documento. Prefira referenciar o participante e o endereço do evento por participantId/addressId; a forma inline participant/address continua suportada e faz find-or-create do registro. Veja Participantes.

Eventos em lote

curl -X POST "https://example.com/documents/events" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "events": [      {        "externalCreatedAt": "2020-01-01T00:00:00.000Z",        "isPublic": true,        "name": "Pick-up"      }    ]  }'

{  "documentId": "28b04f62-8fe2-4332-b854-fe8a922788b5",  "events": [    {      "eventId": "string",      "targetDocumentId": "string"    }  ]}

Utilize POST /documents/events para criar múltiplos eventos para um documento em uma única requisição. O corpo aceita exatamente um entre:

• documentId — adiciona os eventos a um documento existente; ou
• document — um payload completo de documento, criando o documento e seus eventos na mesma requisição.

Enviar os dois, ou nenhum, retorna 400 (Exactly one of documentId or document must be provided).

Cada evento no lote segue o mesmo schema do endpoint de evento individual acima, com uma verificação extra que o endpoint individual não tem: as identidades de participante e endereço são checadas contra conflitos entre os eventos do lote, então a mesma identidade carregando dados diferentes falha.

A regra de identidade em si é a mesma nos dois endpoints — todo evento precisa carregar exatamente um entre participantId/participant e exatamente um entre addressId/address. O endpoint individual delega para este depois de rodar essa verificação por conta própria.

Tipos lógicos de evento

O schema atual define seis schemas de eventos discriminados (CloseEvent, ActorEvent, CancelEvent, RelatedEvent, UpdateEvent, CustomEvent). Qualquer nome de evento que a API não reserva é tratado como evento CUSTOM, OUTPUT incluído.

A criação de um documento downstream é acionada pela presença do objeto target em qualquer evento, não pelo nome do evento. Os dois endpoints informam o documento criado como targetDocumentId — na entrada do evento na resposta do lote, e ao lado de documentId e eventId na resposta do endpoint individual. Note que o schema da resposta individual não declara o campo, então um cliente gerado pode descartá-lo; leia-o do corpo bruto se precisar dele.

Eventos CANCEL exigem que metadata.attributes inclua uma entrada chamada reason com valor não vazio; omiti-la retorna 400 (The reason metadata is required for CANCEL events). O nome é reason em minúsculas — a única exceção à convenção Title Case para nomes de atributos de metadados, e o validador compara exatamente, então Reason não é reconhecido.

Ordenação e consistência

• externalCreatedAt deve ser anterior ao horário atual.
• externalCreatedAt deve ser igual ou posterior ao último evento registrado.
• Utilize deduplicationId ao reenviar submissões de eventos. Um valor repetido no mesmo documento é rejeitado com 409 CONFLICT_ERROR, nunca reexecutado — veja Tratamento de Erros.

Documentos relacionados

Em um evento RELATED, relatedDocument.bidirectional tem padrão true, o que grava o evento espelhado no documento relacionado. Quando bidirectional é true, isPublic é obrigatório no documento relacionado. Quando é false não há evento espelhado a descrever, então eventName, eventLabel e preserveSensitiveData são todos rejeitados.

Para definições completas de eventos e alinhamento com metodologias, consulte Especificação de Eventos.