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).
Todos os participantes (Gerador de Resíduos, Transportador, Processador, Reciclador) possuem documentos de homologação válidos.

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. Cada um deve ter um documento de homologação válido (regra 4 — Participant Accreditations & Verifications).

Participante	Obrigatório?	Condições
Integrador	Sim	Deve ter homologação válida com datas válidas.
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).

Cada evento ACTOR deve incluir os dados de homologação e endereço do participante (usados pela regra 7 — Geolocation Precision, que valida endereços de eventos contra endereços homologados usando limiares de distância escalonados).

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

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": false,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "label": "Waste Generator",  "name": "ACTOR",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  }}

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": "2024-12-05T11:02:47Z",  "isPublic": false,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Pick-up",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Waste picked up by hauler Acme Example Hauler at Acme Example Waste Generator"      },      {        "isPublic": true,        "name": "Local Waste Classification ID",        "value": "04 02 20"      },      {        "isPublic": true,        "name": "Local Waste Classification Description",        "value": "Lodos do tratamento local de efluentes não abrangidas em 04 02 19"      },      {        "sensitive": true,        "isPublic": false,        "name": "Vehicle License Plate",        "value": "ABC1D23"      },      {        "isPublic": true,        "name": "Vehicle Type",        "value": "Truck"      },      {        "isPublic": false,        "name": "Driver Identifier",        "value": "00000000-0000-4000-8000-00000000d21f"      }    ]  }}

3. Transport Manifest — documentação de transporte

Deve incluir (regra 12 — Transport Manifest):

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	Upload via Upload de Arquivos.

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Transport Manifest",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-02-10"      }    ]  },  "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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Weighing",  "participant": {    "id": "00000000-0000-4000-8000-00000000000a",    "countryCode": "BR",    "email": "wastegen@example.com",    "mobileNumber": "+5511000000001",    "name": "Acme Example Waste Generator",    "taxId": "11222333000181",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "value": 1201.925,  "metadata": {    "attributes": [      {        "isPublic": true,        "name": "Description",        "value": "Weighing captured at waste generator site"      },      {        "isPublic": true,        "name": "Weigh Capture Method",        "value": "Average Weight by Volume"      },      {        "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      }    ]  }}

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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Drop-off",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Sorting",  "participant": {    "id": "00000000-0000-4000-8000-00000000000c",    "countryCode": "BR",    "email": "processor@example.com",    "mobileNumber": "+5511000000003",    "name": "Acme Example Processor",    "taxId": "11222333000343",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2025-02-22T10:35:12.000Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Recycled",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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

Deve incluir (regra 19 — Recycling Manifest):

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	Condicional	Obrigatório a menos que justificativa de isenção fornecida.
Justificativa de isenção	Condicional	Quando anexos não estão disponíveis.

{  "externalCreatedAt": "2024-12-05T11:02:47Z",  "isPublic": true,  "address": {    "city": "São Paulo",    "countryCode": "BR",    "countryState": "SP",    "latitude": -23.5613,    "longitude": -46.6563,    "name": "Sede",    "neighborhood": "Centro",    "number": "1000",    "street": "Avenida Exemplo",    "zipCode": "01001000"  },  "name": "Recycling Manifest",  "participant": {    "id": "00000000-0000-4000-8000-00000000000d",    "countryCode": "BR",    "email": "recycler@example.com",    "mobileNumber": "+5511000000004",    "name": "Acme Example Recycler",    "taxId": "11222333000424",    "taxIdType": "CNPJ",    "type": "COMPANY"  },  "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": "2024-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.
Executa regras de RecycledID (distribuição de recompensas para participantes da cadeia de suprimentos).
Gera tokens de crédito C-BIOW (Créditos de Reciclagem Tokenizados) após a liquidação da ordem de crédito.

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 — Todos os participantes devem ter documentos de homologação válidos e não expirados no momento da submissão do evento.
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