Visão Geral das Integrações

Integrações conectam sua plataforma ao Ecossistema Carrot para que Integradores possam enviar dados de rastreabilidade da cadeia de suprimentos por meio da Carrot API. Cada documento representa um registro de rastreabilidade do mundo real — como um MassID rastreando um lote de resíduos pela cadeia de suprimentos — construído como uma linha do tempo imutável de eventos verificada pelo processo de Mensuração, Relato e Verificação digital (dMRV).

Esta seção cobre o fluxo prático de integração, guias de implementação e dados de referência compartilhados necessários antes que as regras específicas da metodologia sejam aplicadas.

Conceitos-chave

Antes de mergulhar na API, três ideias fundamentam toda integração:

• Documentos e eventos — Um documento é o registro raiz de um fluxo de rastreabilidade (ex.: um MassID rastreando um lote de resíduos). Todas as mudanças de estado são representadas por eventos adicionados à linha do tempo do documento — não há endpoints de atualização ou exclusão.

• Imutabilidade — A plataforma usa um modelo baseado em eventos (event-sourced): cada submissão é adicionada ao histórico, e o estado atual é derivado do log de eventos. Se você precisar corrigir um erro, cancele o documento com um evento CANCEL e crie um novo. Essa imutabilidade sustenta a confiança no mercado de créditos ambientais.

• Idempotência — Use deduplicationId em toda chamada de criação e evento para que retentativas não produzam duplicatas. Isso, combinado com timestamps externalCreatedAt ordenados, torna as integrações resilientes a falhas transitórias.

Para a explicação completa, veja Conceitos Fundamentais.

Modelo de integração

Em alto nível, toda integração segue o mesmo fluxo base:

1. Autenticar com credenciais de cliente OAuth 2.0.
2. Criar um documento (POST /documents).
3. Adicionar eventos à linha do tempo (POST /documents/{documentId}/events), ou enviar múltiplos eventos de uma vez (POST /documents/events).
4. Fazer upload de arquivos opcionais por meio de URLs de anexo pré-assinadas.
5. Consultar e validar o estado final (GET /documents/{id}).

Veja a Referência da API para detalhes dos contratos de cada endpoint.

Pré-requisitos

• clientId e clientSecret emitidos pela Carrot.
• Uma estratégia estável de identificadores para externalId e deduplicationId.
• Ordenação de timestamps de eventos do seu sistema de origem.
• Controles de retentativas e rate-limiting no seu cliente.

Integração (onboarding)

Para integrar com o Ecossistema Carrot, sua plataforma passa pela homologação: você envia informações da empresa e endereço e assina um acordo. Uma vez que o processo começa, a Carrot emite credenciais de teste para que você possa desenvolver e validar sua integração com dados de teste. Após a homologação ser concluída, a Carrot emite credenciais de produção para dados reais. Veja Ambientes para o comportamento de teste vs produção e o checklist de go-live.

Como esta seção está organizada

• Primeiros Passos: primeiro fluxo ponta a ponta, conceitos fundamentais e configuração de ambiente.
• Guias: padrões de implementação orientados a tarefas.
• Referência: restrições compartilhadas de eventos e dados.
• Integração por Metodologia: eventos, atributos e regras de validação específicos de cada metodologia.

Migrando de uma integração anterior

Se você está atualizando de uma integração mais antiga ou de uma versão diferente da API, observe estes requisitos atuais:

• Categoria do documento — Use MassID (não Mass).
• Unidade de medida — Use kg (minúsculo) para massa.
• Chaves de metadados — Use Title Case (ex.: Vehicle License Plate, Issue Date). Veja Formatos de Dados.
• Eventos ACTOR — Use o campo label para identificar os papéis dos participantes (Waste Generator, Recycler, Processor, Hauler, Integrator). Não envie campos descontinuados como actor-type.
• Nomes de eventos — Use os nomes de eventos específicos exigidos pela metodologia (ex.: Pick-up, Transport Manifest, Weighing, Drop-off, Sorting, Recycled, Recycling Manifest). O evento OPEN não é utilizado; não o envie.

Para a sequência completa de eventos e requisitos de campos, veja os guias de integração por metodologia.