Formatos de Dados

Convenções de formato de dados — nomenclatura, datas, números, Title Case e restrições de campos.

Use estas convenções para reduzir erros de validação e manter a interoperabilidade dos dados.

Nomes de atributos de metadados

Use Title Case para nomes de atributos de metadados (ex: Vehicle License Plate, Gross Weight, Issue Date). Não use kebab-case ou nomes concatenados em minúsculas nos metadados de eventos. A única exceção é o reason de um evento CANCEL, que a plataforma compara em minúsculas.

Data e hora

Use timestamps UTC no formato ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) para campos de data e hora.
Para campos apenas de data, use o formato de data ISO 8601 e, quando exigido pela API, inclua um atributo format (ex: DATE).
Preserve a cronologia da origem nas submissões de eventos.

Identificadores

Mantenha os IDs estáveis e determinísticos entre retentativas.
Use deduplicationId como chave de idempotência de criação única em escritas passíveis de retentativa; uma repetição é rejeitada, não reexecutada — veja Tratamento de Erros.
externalId é armazenado para a sua própria correlação e não é usado para deduplicação.

Convenções de nomenclatura

Use nomes de atributos consistentes e evite duplicatas sinônimas.
Prefira metadados estruturados em vez de strings de texto livre.

Valores numéricos e unidades

Envie campos numéricos como números, não como strings localizadas.
Quando a API exigir uma unidade ou escala, use o atributo format com o valor apropriado (ex: KILOGRAM, LITER, CUBIC_METER para massa/volume).
Mantenha a escolha de unidade consistente durante o ciclo de vida do documento.

Dados sensíveis

Para atributos que contêm dados sensíveis ou pessoais (ex: placas de veículos, identificadores de motoristas):

Envie o valor completo no payload — não mascare ou redija previamente.
Defina sensitive: true nos metadados. Ele governa o mascaramento na página pública do documento; é um sinal que você envia, não o mecanismo que mantém um atributo fora das superfícies públicas de MassID da própria Carrot, que publicam um conjunto fixo de atributos mantido no código da Carrot.
Consulte Privacidade e Mascaramento para controles de visibilidade.

Identidade do participante em eventos ACTOR

A superfície pública de MassID da Carrot nomeia participantes apenas a partir de eventos ACTOR — um participante ligado a um evento CUSTOM ou outro nunca é nomeado ali, independentemente das flags. A visibilidade de um participante é decidida uma vez para o documento inteiro, a partir de todos os eventos que o mencionam:

isPublic: true em cada um desses eventos. Esse campo é obrigatório, então omiti-lo falha na validação em vez de mudar o que é publicado.
preserveSensitiveData em cada um desses eventos: false para Processadores, Recicladores e Integradores, true para Geradores de Resíduos, Transportadores, Gestores de Resíduos e todos os demais papéis da cadeia de suprimentos. true em qualquer um desses eventos mantém o participante sem nome em todo o documento; deixar o campo de fora aplica o padrão do papel, sob o qual Processadores, Recicladores e Integradores podem ser nomeados e os demais papéis não. Um participante que é ao mesmo tempo transportador e processador ou reciclador no mesmo documento é a exceção: deixe o campo de fora em todo evento que o menciona, e ele pode ser nomeado na página pública do documento.

Alguns papéis nunca são nomeados na superfície pública de MassID da Carrot, independentemente das flags. Veja Privacidade e Mascaramento para saber quais papéis podem ser nomeados.

Referências relacionadas: