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 — resolva cada um primeiro (recupere por chave ou crie) para poder referenciá-lo por participantId e addressId, como mostrado na Etapa 1
• Familiaridade com os conceitos fundamentais — especialmente o modelo imutável baseado em eventos

Etapa 1: Resolver participantes e endereços

Todo documento e todo evento precisa de um participante e de um endereço. Referencie-os por ID — a forma usada neste guia — ou envie os objetos inline, o que faz find-or-create deles. Antes de enviar, resolva cada um — busque por chave ou crie — e guarde o participantId e o addressId retornados.

Recuperar por chave. Busque um participante existente pela chave natural — código do país, tipo de documento e número do documento:

GET /participants?countryCode=BR&taxIdType=CNPJ&taxId=11111111111111

Se existir, reutilize o participantId retornado e liste seus endereços para encontrar o addressId:

GET /participants/{participantId}/addresses

Criar quando não existir. Se o participante ainda não existir, crie-o e depois adicione um endereço a ele:

POST /participants
{
  "countryCode": "BR",
  "name": "Empresa Exemplo",
  "taxId": "11111111111111",
  "taxIdType": "CNPJ",
  "type": "COMPANY"
}

POST /participants/{participantId}/addresses
{
  "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
}

Cada chamada de criação retorna o id gerado — use-o como participantId / addressId nas próximas etapas. Campos obrigatórios: participante — countryCode, name, taxId, taxIdType, type; endereço — city, countryCode, countryState, name, number, street. Consulte a API de Participantes para o schema completo de requisição e resposta.

Etapa 2: Criar o documento

Crie o registro raiz com classificação e campos de visibilidade base, referenciando o participante e o endereço que você resolveu na Etapa 1:

POST /documents
{
  "category": "MassID",
  "type": "SEU_TIPO_DE_RESÍDUO",
  "measurementUnit": "kg",
  "externalCreatedAt": "2026-03-01T10:00:00.000Z",
  "isPublic": true,
  "isPubliclySearchable": true,
  "participantId": "id-do-participante-da-etapa-1",
  "addressId": "id-do-endereço-da-etapa-1",
  "externalId": "seu-id-interno-de-rastreamento",
  "deduplicationId": "id-único-gerado-antes-da-primeira-tentativa"
}

Referência: API de Documentos.

Etapa 3: 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 do participante e endereço a que se aplica, referenciados por ID:

POST /documents/{documentId}/events
{
  "name": "ACTOR",
  "label": "SEU_LABEL_DE_PAPEL",
  "externalCreatedAt": "2026-03-01T10:05:00.000Z",
  "isPublic": true,
  "participantId": "id-do-participante-ator",
  "addressId": "id-do-endereço-ator"
}

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.

Resolva o participante e o endereço de cada ator da mesma forma que na Etapa 1, e então referencie-os por participantId e addressId.

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 /documents/{documentId}/events
{
  "name": "NOME_DO_SEU_EVENTO",
  "externalCreatedAt": "2026-03-01T11:00:00.000Z",
  "isPublic": true,
  "participantId": "id-do-participante-da-etapa-1",
  "addressId": "id-do-endereço-da-etapa-1",
  "metadata": {
    "attributes": [
      { "name": "NOME_DO_SEU_ATRIBUTO", "value": "valor-do-atributo", "isPublic": true }
    ]
  },
  "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.

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 e CANCEL são aceitos — CANCEL sobrevive ao CLOSE justamente para manter o padrão de CANCEL e recriação disponível em um documento fechado.
• 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 /documents/{documentId}/events
{
  "name": "CLOSE",
  "externalCreatedAt": "2026-03-02T16:00:00.000Z",
  "isPublic": true,
  "participantId": "id-do-participante-integrador",
  "addressId": "id-do-endereço-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 4: 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 5: 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.