Enviando um MassID

Use esta sequência como padrão base de implementação para enviar o ciclo de vida completo de um MassID através da Carrot API.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma conta de Integrador registrada com credenciais de API válidas
• Dados de participante e endereço prontos — eles são criados inline no seu primeiro envio (nenhuma etapa separada de criação é necessária)
• Familiaridade com os conceitos fundamentais — especialmente o modelo imutável baseado em eventos

Etapa 1: Criar o documento

Crie o registro raiz com classificação e campos de visibilidade base. Dados de participante e endereço podem ser enviados inline como objetos na primeira requisição. Nas requisições seguintes, você pode reutilizar os IDs retornados pela plataforma.

POST /v1/documents
{
  "category": "MassID",
  "type": "SEU_TIPO_DE_RESÍDUO",
  "measurementUnit": "kg",
  "externalCreatedAt": "2026-03-01T10:00:00.000Z",
  "isPublic": true,
  "isPubliclySearchable": true,
  "participant": {
    "countryCode": "BR",
    "name": "Empresa Exemplo",
    "taxId": "11111111111111",
    "taxIdType": "CNPJ",
    "type": "COMPANY"
  },
  "address": {
    "name": "Unidade Principal",
    "street": "Rua das Colinas",
    "number": "500",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "countryState": "São Paulo",
    "countryCode": "BR",
    "zipCode": "08575720",
    "latitude": -23.5489,
    "longitude": -46.6388
  },
  "externalId": "seu-id-interno-de-rastreamento",
  "deduplicationId": "id-único-gerado-antes-da-primeira-tentativa"
}

* Envie participant (objeto inline) ou participantId (ID), não ambos.

** Envie address (objeto inline) ou addressId (ID), não ambos.

Campos obrigatórios do participant inline:

Referência: API de Documentos.

Etapa 2: Adicionar eventos à linha do tempo

Adicione eventos em ordem cronológica para representar as etapas operacionais. Cada evento é imutável após criado.

Eventos ACTOR

Eventos ACTOR registram papéis de participantes na linha do tempo do documento. Cada um requer um label identificando o papel, além de um participante e endereço:

POST /v1/documents/{documentId}/events
{
  "name": "ACTOR",
  "label": "SEU_LABEL_DE_PAPEL",
  "externalCreatedAt": "2026-03-01T10:05:00.000Z",
  "isPublic": true,
  "participant": {
    "countryCode": "BR",
    "name": "Nome do Participante",
    "taxId": "22222222222",
    "taxIdType": "CPF",
    "type": "PERSON"
  },
  "address": {
    "name": "Ponto de Coleta",
    "street": "Rua das Colinas",
    "number": "500",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "countryState": "São Paulo",
    "countryCode": "BR",
    "zipCode": "08575720",
    "latitude": -23.5489,
    "longitude": -46.6388
  }
}

O valor de label (ex. "Waste Generator", "Hauler", "Processor") é definido por cada metodologia. Consulte o guia da sua metodologia para os papéis obrigatórios e seus labels.

Após a primeira criação inline, você pode usar participantId e addressId para eventos subsequentes que referenciem o mesmo participante ou endereço.

Eventos CUSTOM

Eventos CUSTOM representam etapas operacionais específicas da metodologia. O nome do evento, atributos de metadados obrigatórios e a sequência são todos definidos pela metodologia:

POST /v1/documents/{documentId}/events
{
  "name": "NOME_DO_SEU_EVENTO",
  "externalCreatedAt": "2026-03-01T11:00:00.000Z",
  "isPublic": true,
  "participantId": "id-do-participante-da-resposta-anterior",
  "addressId": "id-do-endereço-da-resposta-anterior",
  "metadata": {
    "attributes": [
      { "name": "NOME_DO_SEU_ATRIBUTO", "value": "valor-do-atributo" }
    ]
  },
  "value": 150.5
}

O campo value nos eventos contribui para o currentValue do documento. Por exemplo, um evento de pesagem com value: 150.5 define o peso rastreado.

Campos obrigatórios do address inline:

Ciclo de vida do status do documento

Documentos seguem um ciclo de vida de status estrito:

• OPEN — Status padrão após a criação. Eventos podem ser adicionados livremente.
• Evento CLOSE — Transiciona o documento para CLOSED. Após o fechamento, apenas eventos RELATED são aceitos.
• Evento CANCEL — Transiciona o documento para CANCELLED. Nenhum evento adicional é aceito.

Envie um evento CLOSE quando o ciclo de vida da cadeia de suprimentos estiver completo:

POST /v1/documents/{documentId}/events
{
  "name": "CLOSE",
  "externalCreatedAt": "2026-03-02T16:00:00.000Z",
  "isPublic": true,
  "participantId": "id-do-participante-integrador"
}

Consulte a Especificação de Eventos para a lista completa de categorias de eventos.

Referência: API de Eventos.

Para integrações de alto volume, considere o endpoint de eventos em lote para enviar múltiplos eventos por requisição.

Etapa 3: Anexar arquivos de evidência (opcional)

Algumas regras de metodologia exigem anexos de evidência (ex. tickets de balança, manifestos de transporte). O padrão é:

1. Solicitar uma URL de upload pré-assinada via a API de Anexos
2. Fazer upload do arquivo diretamente para a URL pré-assinada
3. Referenciar o anexo no array attachments do evento relevante

Anexos são vinculados a eventos específicos, não ao documento como um todo. Isso garante que cada evidência esteja vinculada à etapa operacional que ela documenta.

Referência: API de Anexos.

Etapa 4: Recuperar e validar o estado final

Consulte o documento e verifique antes de considerar o envio completo:

• Contagem e ordenação de eventos — todos os eventos esperados estão presentes em ordem cronológica
• Status é CLOSED — o documento foi devidamente fechado
• currentValue > 0 — o documento tem um valor rastreado positivo
• Pelo menos um evento ACTOR — os papéis de participante obrigatórios estão registrados
• Links de participante e endereço — todas as referências resolvem corretamente
• Completude dos metadados — atributos obrigatórios estão presentes em cada evento conforme a metodologia

Referência: GET documento por ID.

Dicas operacionais

• Use externalId em documentos e eventos para reconciliação com seus sistemas internos.
• Trate 4xx como problemas de dados/integração e 5xx como falhas transitórias — veja Tratamento de Erros.
• Mantenha sua estratégia de timestamps determinística — veja Formatos de Dados.