Guia de Integração BOLD Recycling Credit

Guia de integração para a Aplicação BOLD Recycling Credit v1.0.0 — eventos esperados, campos obrigatórios e requisitos de validação.

Este guia explica como submeter documentos MassID que atendem às regras do BOLD Recycling. Ele cobre a sequência de eventos esperada, campos obrigatórios por evento e problemas comuns de validação.

Para o fluxo base da API, consulte Submetendo um MassID. Para o catálogo completo de regras, consulte Regras do BOLD Recycling.

Pré-requisitos

Concluiu o fluxo do Quick Start.
Familiaridade com Conceitos Fundamentais (modelo de documentos, ordenação de eventos, idempotência).
Documento de homologação registrado para o Integrador, o Processador e o Reciclador — a validade do Processador e do Reciclador é verificada quando a metodologia roda. A regra 4 verifica apenas esses três — um Transportador não precisa de homologação, e a do Gerador de Resíduos não é exigida por essa regra.

Campo	Valor obrigatório
`category`	`MassID`
`type`	`Organic`
`measureUnit`	`kg`
`value`	Maior que 0
`subtype`	Um subtipo válido de resíduo orgânico
`isPublic`	Conforme seus requisitos de visibilidade

Sequência esperada de eventos

Submeta eventos em ordem cronológica via POST /documents/{documentId}/events. Consulte Especificação de Eventos para campos comuns de eventos.

A sequência a seguir reflete a ordem validada pelas regras do BOLD Recycling:

Papéis obrigatórios dos participantes

Papel	Label ACTOR	Função
Gerador de Resíduos	`Waste Generator`	Origem do material residual
Transportador	`Hauler`	Transporta resíduos da origem até a instalação
Reciclador	`Recycler`	Opera a instalação de reciclagem ou compostagem
Processador	`Processor`	Processa material triado (pode ser a mesma entidade do reciclador)

1. Eventos ACTOR — registro de participantes

Registre cada participante com um evento ACTOR. A regra 4 — Participant Accreditations & Verifications — verifica documentos de homologação apenas para o Integrador, o Processador e o Reciclador, e a homologação do Processador e do Reciclador precisa estar válida na data da avaliação. Registrar um Transportador ou um Gerador de Resíduos não exige documento de homologação.

Participante	Obrigatório?	Condições
Integrador	Sim	Deve ter um documento de homologação.
Gerador de Resíduos	Condicional	Obrigatório se a origem do resíduo é identificada (regra 8). Omitir se não identificada.
Transportador	Condicional	Obrigatório para a maioria dos tipos de veículos (regra 9). Opcional para carrinho ou tubulação de lodo.
Processador	Sim	Exatamente um processador obrigatório (regra 13).
Reciclador	Sim	Exatamente um reciclador obrigatório (regra 14).

Todo evento ACTOR carrega os identificadores de participante e de endereço. Ele não carrega dados de homologação: a homologação não é enviada pela API — ela vive na camada de homologação, e o pipeline de verificação a lê de lá. A regra 7 — Geolocation Precision — compara o endereço de um evento com o endereço homologado dos participantes que têm homologação registrada.

O formato do payload é idêntico entre atores — apenas o identificador do papel muda.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "preserveSensitiveData": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "label": "Waste Generator",  "name": "ACTOR",  "participantId": "00000000-0000-4000-8000-00000000000a"}

2. Pick-up — coleta de resíduos

O evento Pick-up captura informações do veículo e motorista:

Campo	Obrigatório?	Validado por
Tipo de veículo	Sim	Regra 10 — Vehicle Identification
Placa / identificação	Condicional	Por tipo de veículo (regra 10)
Identificação do motorista	Condicional	Por tipo de veículo (regra 11)
Justificativa de isenção	Condicional	Quando ID do motorista não é obrigatório (regra 11)

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Pick-up",  "participantId": "00000000-0000-4000-8000-00000000000a",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste picked up at the waste generator site"      },      {        "isPublic": true,        "name": "Local Waste Classification ID",        "value": "02 01 03"      },      {        "isPublic": true,        "name": "Local Waste Classification Description",        "value": "Resíduos de tecidos vegetais"      },      {        "sensitive": true,        "isPublic": true,        "name": "Vehicle License Plate",        "value": "ABC1D23"      },      {        "isPublic": true,        "name": "Vehicle Type",        "value": "Truck"      },      {        "sensitive": true,        "isPublic": true,        "name": "Driver Identifier",        "value": "00000000-0000-4000-8000-00000000d21f"      }    ]  }}

3. Transport Manifest — documentação de transporte

O evento continua obrigatório (regra 12 — Transport Manifest). Para o envio padrão com anexo:

Campo	Obrigatório?	Observações
Número do documento	Sim
Tipo do documento	Sim	Deve ser `MTR` para recicladores no Brasil.
Data de emissão	Sim
Anexos	Sim	Use o label `Transport Manifest`; envie via Upload de Arquivos.

Isenções de manifesto

Tanto para Transport Manifest (MTR) quanto para Recycling Manifest (CDF), forneça o anexo com o label correto ou um atributo de metadados Exemption Justification não vazio. Não fornecer nenhum deles, fornecer ambos ou fornecer um anexo sem o label correspondente ao manifesto causa falha na validação. O caminho de isenção não exige número do documento, tipo do documento ou data de emissão listados para o envio padrão. Ele ainda exige o evento de manifesto e o evento ACTOR do Recycler; o endereço do Recycling Manifest ainda deve coincidir com o endereço do Recycler.

Use as regras existentes do framework para campos, anexos e justificativa de isenção de manifesto como referência dos critérios. A aceitação técnica de uma justificativa não comprova a elegibilidade para isenção: a simples ausência do PDF não é suficiente. Confirme os requisitos de evidência aplicáveis e qualquer decisão específica do caso com as equipes de metodologia e homologação antes de enviar uma isenção. Este guia não concede exceções específicas a participantes. Esses requisitos compartilhados também se aplicam ao BOLD Carbon (CH₄).

O exemplo abaixo mostra o caminho padrão com anexo.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Transport Manifest",  "participantId": "00000000-0000-4000-8000-00000000000a",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Document Type",        "value": "MTR"      },      {        "isPublic": true,        "name": "Document Number",        "value": "DOC-EXAMPLE-0001"      },      {        "format": "DATE",        "isPublic": true,        "name": "Issue Date",        "value": "2025-02-09"      }    ]  },  "attachments": [    {      "fileName": "transport-manifest.pdf",      "isPublic": false,      "label": "Transport Manifest"    }  ]}

4. Weighing — medição de massa

Registre medições de peso (regra 15 — Weighing):

Campo	Obrigatório?	Observações
Valor do evento	Sim	Peso líquido em kg, deve ser maior que 0.
Descrição	Sim	Descrição do evento de pesagem.
Peso bruto	Sim	Deve ser maior que 0, em kg.
Tara	Sim	Peso do container vazio em kg (isenções podem ser aplicadas por homologação).
Tipo de container	Sim	Um de: Bag, Bin, Drum, Pail, Street Bin, Waste Box ou Truck.
Quantidade de container	Condicional	Obrigatório quando o tipo de container não é Truck.
Capacidade do container	Condicional	Obrigatório para pesagem com múltiplos containers.
Método de captura	Sim	Um de: Digital, Photo (Scale + Cargo), Manual ou Transport Manifest.
Tipo de balança	Sim	Deve corresponder a um tipo de balança aprovado.
Ticket de pesagem	Condicional	Quando exigido pela homologação do reciclador.
Placa do veículo	Condicional	Obrigatório quando o tipo de container é Truck.

Suporta processos de pesagem em uma ou duas etapas.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000a",  "name": "Weighing",  "participantId": "00000000-0000-4000-8000-00000000000a",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Weighing captured at waste generator site"      },      {        "isPublic": true,        "name": "Weighing Capture Method",        "value": "Digital"      },      {        "isPublic": true,        "name": "Scale Type",        "value": "Floor Scale"      },      {        "isPublic": true,        "name": "Container Type",        "value": "Drum"      },      {        "isPublic": true,        "name": "Container Quantity",        "value": 1      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Container Capacity",        "value": 100      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Gross Weight",        "value": 1211.925      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Tare",        "value": 10      },      {        "sensitive": true,        "isPublic": true,        "name": "Vehicle License Plate",        "value": "ABC1D23"      }    ]  }}

5. Drop-off — entrega na instalação de reciclagem

Deve incluir (regra 16 — Drop-off At Recycling Facility):

Campo	Obrigatório?	Observações
Operador de recepção	Sim	Identificação do operador na instalação.
Endereço	Sim	Deve corresponder ao endereço homologado do reciclador.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Drop-off",  "participantId": "00000000-0000-4000-8000-00000000000d",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste deposited in Windrow number 1"      },      {        "isPublic": true,        "name": "Receiving Operator Identifier",        "value": "00000000-0000-4000-8000-00000000000c"      }    ]  }}

6. Sorting — triagem de massa

Deve incluir (regra 17 — Mass Sorting):

Campo	Obrigatório?	Observações
Descrição	Sim	Descrição do evento de triagem.
Peso bruto	Sim	Peso total antes das deduções.
Peso deduzido	Sim	Peso de contaminantes/material não-alvo.
Fator de triagem	Sim	Calculado a partir do peso bruto e deduzido.
Valor do evento	Sim	Deve ser corretamente calculado a partir dos dados de triagem.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000c",  "name": "Sorting",  "participantId": "00000000-0000-4000-8000-00000000000c",  "value": 1189.906,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Sorting factor determined by a third-party audit"      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Gross Weight",        "value": 1201.925      },      {        "format": "KILOGRAM",        "isPublic": true,        "name": "Deducted Weight",        "value": 12.019      }    ]  }}

7. Recycled — conclusão do tratamento biológico

O evento Recycled marca o fim do ciclo de tratamento biológico. O timestamp é validado contra o evento Drop-off (regra 18 — Composting Cycle Timeframe):

O tempo entre Drop-off e Recycled deve ser de 60–180 dias.

{  "externalCreatedAt": "2026-02-22T10:35:12.000Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Recycled",  "participantId": "00000000-0000-4000-8000-00000000000d",  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Composting process completed. The recycling completion date is recorded by a conservative estimate determined and verified by a third-party audit for the recycler"      }    ]  }}

8. Recycling Manifest — documentação de reciclagem

O evento continua obrigatório (regra 19 — Recycling Manifest). Para o envio padrão com anexo:

Campo	Obrigatório?	Observações
Número do documento	Sim
Tipo do documento	Sim	Deve ser `CDF` para recicladores no Brasil.
Data de emissão	Sim
Anexos	Sim	Use o label `Recycling Manifest`.

Para a alternativa com Exemption Justification, veja Isenções de manifesto. O exemplo abaixo mostra o caminho padrão com anexo.

{  "externalCreatedAt": "2025-12-05T11:02:47Z",  "isPublic": true,  "addressId": "00000000-0000-4000-9000-00000000000d",  "name": "Recycling Manifest",  "participantId": "00000000-0000-4000-8000-00000000000d",  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Document Type",        "value": "CDF"      },      {        "isPublic": true,        "name": "Document Number",        "value": "DOC-EXAMPLE-0002"      },      {        "format": "DATE",        "isPublic": true,        "name": "Issue Date",        "value": "2025-03-10"      }    ]  },  "attachments": [    {      "fileName": "recycling-manifest.pdf",      "isPublic": false,      "label": "Recycling Manifest"    }  ]}

Mapeamento de eventos e regras

CUSTOM event names

Event Name	Purpose	Validated by
PICK_UP	Waste collection from generator site	—
TRANSPORT_MANIFEST	Transport documentation attachment	—
WEIGHING	Weight capture at a calibrated scale	—
DROP_OFF	Delivery to the recycling/processing facility	—
SORTING	Waste sorting with contamination deduction	—
RECYCLED	Confirms composting or recycling completion	—
RECYCLING_MANIFEST	Final recycling documentation attachment	—

ACTOR label vocabulary

Label	Description	Validated by
WASTE_GENERATOR	Source of the waste material	—
HAULER	Transports waste from origin to facility	—
RECYCLER	Operates the recycling or composting facility	—
PROCESSOR	Processes sorted material	—

Validações adicionais

Regra	O que verifica
1	Não existe MassID duplicado com a mesma combinação de drop-off + pick-up + reciclador + gerador de resíduos + placa.
2	MassID não está vinculado a um RecycledID ou ordem de crédito.
3	O evento Recycled ocorreu em ou após 1 de janeiro do ano anterior.
6	A classificação local de resíduos corresponde a um código Ibama válido (recicladores no Brasil).
7	Endereços de eventos dos participantes são validados contra endereços homologados usando limiares de distância escalonados (≤2 km: verificação GPS, 2–30 km: revisão de similaridade de endereço, >30 km: falha).

Pós-validação

Quando todas as 19 regras passam, a plataforma:

Emite um certificado RecycledID vinculado ao MassID e o publica no Carrot Registry.
Minta os tokens de crédito C-BIOW (Tokenized Recycling Credits) quando o certificado é registrado no registry público de créditos, na mesma transação — veja Criação de Registros no Registry.
As recompensas dos participantes da cadeia de suprimentos são calculadas e registradas on-chain depois, quando um crédito daquele certificado é vendido.

Problemas comuns

Incompatibilidade de geolocalização — Endereços de eventos dos participantes são validados contra endereços homologados usando limiares de distância escalonados. Verifique a precisão do GPS.
Prazo do tratamento biológico — A janela entre Drop-off e Recycled deve ser de 60–180 dias. Documentos fora desse intervalo falham na regra 18.
Homologações ausentes — O Integrador, o Processador e o Reciclador devem ter documento de homologação registrado, e a do Processador e do Reciclador precisa estar válida e não expirada no momento em que a metodologia roda, não no momento em que o evento foi submetido. A regra 4 não verifica a homologação do Transportador nem do Gerador de Resíduos.
MassIDs duplicados — A verificação de unicidade (regra 1) impede submissões duplicadas. Use deduplicationId para retentativas, não reenvios.
Códigos Ibama — Para recicladores no Brasil, a classificação local de resíduos deve corresponder a um código Ibama válido. Valide antes da submissão.

Catálogo de regras · Referência da aplicação · Fluxo base de integração