Início Rápido

Começando agora? Comece explorando um MassID de referência completo no Carrot Explorer — depois volte para aprender como construir um.

Este guia apresenta o fluxo base da Carrot API — da autenticação à recuperação de documentos — para que você possa verificar sua integração de ponta a ponta.

Trilha de aprendizado do integrador

1) Solicitar um token de acesso

Use OAuth 2.0 client credentials:

curl --request POST \
  --url https://auth.api.carrot.eco/oauth2/token \
  --header 'Authorization: Basic <base64(clientId:clientSecret)>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=api.carrot.eco/main-scope'

Detalhes do endpoint: Autenticação.

2) Criar um documento

Crie o registro base de rastreabilidade:

POST /documents
Authorization: Bearer <access_token>

Detalhes do endpoint: Documentos.

3) Adicionar um evento

Adicione um evento na linha do tempo para representar uma ação de negócio:

POST /documents/{documentId}/events
Authorization: Bearer <access_token>

Detalhes do endpoint: Eventos.

Para operações em volume, use o endpoint de lote (POST /documents/events) para enviar múltiplos eventos em uma única requisição. Veja Eventos — Eventos em lote.

4) Recuperar e validar o estado

Busque o documento completo e verifique a consistência da linha do tempo:

GET /documents/{id}
Authorization: Bearer <access_token>

Detalhes do endpoint: Documentos.

5) Adicionar proteções para produção

• Use deduplicationId em requisições de criação/evento que podem ser retentadas.
• Aplique ordenação de timestamps nos eventos.
• Adicione rate limiting no cliente e estratégias de retentativas com backoff.

Continue com:

• Conceitos Fundamentais — o modelo de documento e a arquitetura orientada a eventos.
• Ambientes — credenciais de teste vs. produção e checklist de go-live.
• Submeter um MassID — passo a passo completo do ciclo de vida.