Conceitos Fundamentais

Esses conceitos formam a base do modelo de integração da Carrot API. Entenda-os antes de escrever suas primeiras chamadas à API.

O que é um documento?

Um documento é a estrutura de dados raiz para um registro de rastreabilidade. Ele registra e representa o histórico completo de um processo logístico ou fluxo de uma massa — da origem ao destino final — de forma transparente e auditável. Cada documento recebe um identificador único e é classificado por categoria, tipo e subtipo.

Documentos podem se relacionar com outros documentos por meio de eventos, permitindo que a plataforma construa uma visão integrada de processos conectados. Por exemplo, um MassID rastreando um lote de resíduos pela cadeia de suprimentos é um documento que armazena campos de identidade e classificação, enquanto todas as mudanças de estado são representadas por eventos anexados à sua linha do tempo.

Referência: Documents API.

Que história um MassID precisa contar?

Todo MassID deve contar uma história completa — com início, meio e fim claros. Ao enviar dados para a Carrot API, garanta que o registro seja coeso, rastreável e detalhado o suficiente para compreender a origem da massa, sua jornada e seu destino final.

Um MassID bem documentado inclui informações como:

• Ponto de origem — onde o resíduo foi gerado ou coletado
• Etapas logísticas — coleta, pesagem (peso bruto e líquido), identificação do veículo
• Pontos de transbordo — transferências intermediárias ou áreas de preparação
• Participantes envolvidos — cada ator na cadeia de custódia
• Destino final — a unidade de reciclagem ou tratamento biológico

Cada informação fortalece a rastreabilidade, a integridade dos dados e o valor percebido do crédito ambiental resultante. Quanto mais contexto você fornecer, maior a confiança para compradores de créditos e auditores.

Veja Enviando um MassID para o fluxo de implementação passo a passo.

Imutabilidade por eventos

Não há endpoint de atualização ou exclusão. Em vez disso, você adiciona eventos para representar mudanças operacionais ao longo do tempo. A plataforma utiliza um modelo event-sourced: cada submissão é anexada à linha do tempo do documento, e o estado atual é derivado do log de eventos.

Essa imutabilidade é fundamental para o mercado de créditos ambientais. Uma vez que os dados são registrados e os créditos são emitidos e negociados, os compradores precisam da garantia de que os registros subjacentes são permanentes e não podem ser alterados após o fato. Dados imutáveis fortalecem a credibilidade do sistema para compradores, reguladores e auditores.

Se você precisar corrigir um erro, não tente editar o documento. Em vez disso, cancele-o usando um evento CANCEL e crie um novo documento com os dados corrigidos, preservando o fluxo completo de rastreabilidade.

Referência: Events API · Error Handling.

Eventos e metadados

Eventos representam ações operacionais concretas realizadas em um documento — por exemplo, coleta de resíduos, pesagem, transporte ou entrega em uma unidade de reciclagem. Juntos, os eventos formam a linha do tempo do documento: um registro cronologicamente ordenado de tudo que aconteceu com a massa.

Cada evento pode carregar metadados (também chamados de atributos) — pares chave-valor que fornecem contexto adicional sobre o que aconteceu. Exemplos incluem data, localização, placa do veículo, identificador do operador ou medição de peso. Os metadados enriquecem a linha do tempo e tornam o registro de rastreabilidade mais robusto para auditorias e verificação.

Alguns campos de metadados são exigidos por regras da metodologia específicas, enquanto outros são recomendados como boas práticas. Quanto mais detalhes você fornecer, mais forte será o resultado da validação.

Referência: Event Specification · Data Formats.

Ordenação de eventos

A cronologia dos eventos importa. O campo externalCreatedAt deve ser válido em relação às entradas existentes na linha do tempo, portanto sua integração deve preservar a ordem do sistema de origem e as retentativas. A plataforma não permite eventos com data futura — os timestamps devem refletir quando a ação ocorreu no sistema de origem.

Visibilidade e privacidade

A visibilidade pública (isPublic) e a visibilidade pesquisável (isPubliclySearchable) fazem parte do modelo base e podem ser ajustadas por meio de fluxos de eventos.

Guia: Privacy & Masking.

Idempotência e resiliência

Use deduplicationId para retentativas de criação/eventos e trate erros transitórios de forma diferente dos erros de validação.

Guia: Error Handling.