Documentos

Documentos são o recurso principal na Carrot API. Um documento (comumente um MassID) se torna o contêiner imutável para dados de rastreabilidade, e todas as alterações acontecem através de eventos adicionados.

Criar documento

Header Parameters

Authorization*string

Token de autorização

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

addressId?string

ID do endereço do documento (não use com o campo address)

category*string

Categoria do documento

deduplicationId?string

Identificador que evita a duplicação do documento por integrador

externalCreatedAt*string

Data de criação do documento no sistema

externalId?string

Identificador do documento no sistema

isPublic*boolean

Indica se o documento pode ser visualizada na página pública

isPubliclySearchable*boolean

Indica se o documento pode ser encontrado na página pública

measurementUnit?string

Unidade de medida do documento

Value in"kg" | "kg CO₂e"

parentDocumentId?string

ID do documento pai

participantId?string

ID do participante do documento (não use com o campo participant)

shortTitle?object

Título curto do documento

subtype?string

Subtipo de documento

tags?object

Campo no formato chave-valor para identificação do documento

title?object

Título do documento

type*string

Tipo de documento

address?

Endereço associado ao participante dono do documento (não use com o campo addressId). Caso o endereço não exista na plataforma, será criado um novo endereço. Caso já exista, os dados passados precisam ser iguais aos dados do endereço existente.

participant?

Participante dono do documento (não use com o campo participantId). Caso o participante não exista na plataforma, será criado um novo participante. Caso já exista, os dados passados precisam ser iguais aos dados do participante existente.

Response Body

`application/json`

curl -X POST "https://api.carrot.eco/documents" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "category": "DOCUMENT",    "externalCreatedAt": "2020-01-01T00:00:00.000Z",    "isPublic": true,    "isPubliclySearchable": true,    "type": "ORGANIC"  }'

{
  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5"
}

Empty

Utilize POST /documents para criar um documento com os campos obrigatórios:

category
externalCreatedAt
isPublic
isPubliclySearchable
type
um entre participantId ou participant (obrigatório)
um entre addressId ou address (obrigatório)

Campos opcionais:

deduplicationId para evitar envios duplicados em retentativas.
tags, title, shortTitle e campos de classificação.

Recuperar documento por id

Path Parameters

id*string

Identificador do documento

Header Parameters

Authorization*string

Token de autorização

Response Body

`application/json`

curl -X GET "https://api.carrot.eco/documents/string" \  -H "Authorization: string"

{
  "address": {
    "city": "São Paulo",
    "complement": "Apto. 50",
    "countryCode": "BR",
    "countryState": "São Paulo",
    "latitude": -23.5489,
    "longitude": -46.6388,
    "name": "Edifício Jardins de Monet",
    "neighborhood": "José Bonifácio",
    "number": "500",
    "street": "Rua das Colinas",
    "zipCode": "08575720"
  },
  "author": {
    "countryCode": "BR",
    "name": "João da Fonseca",
    "participantId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
    "taxId": "11111111111",
    "taxIdType": "CPF",
    "type": "COMPANY"
  },
  "category": "DOCUMENT",
  "createdAt": "2020-01-01T00:00:00.000Z",
  "currentValue": 1500,
  "events": [
    {
      "address": {
        "city": "São Paulo",
        "complement": "Apto. 50",
        "countryCode": "BR",
        "countryState": "São Paulo",
        "latitude": -23.5489,
        "longitude": -46.6388,
        "name": "Edifício Jardins de Monet",
        "neighborhood": "José Bonifácio",
        "number": "500",
        "street": "Rua das Colinas",
        "zipCode": "08575720"
      },
      "author": {
        "countryCode": "BR",
        "name": "João da Fonseca",
        "participantId": "28b04f62-8fe2-4332-b854-fe8a922788b5",
        "taxId": "11111111111",
        "taxIdType": "CPF",
        "type": "COMPANY"
      },
      "externalCreatedAt": "2020-01-01T00:00:00.000Z",
      "externalId": "123456",
      "id": "JrSRCUhKOxKyUujM2DkH9",
      "isPublic": true,
      "label": "Waste Generator",
      "metadata": {},
      "name": "Pick-up",
      "participant": {
        "businessName": "Compostagem Corporate LTDA",
        "countryCode": "BR",
        "email": "joaodaf.54@gmail.com",
        "mobileNumber": "+551123456789",
        "name": "João da Fonseca",
        "taxId": "11111111111",
        "taxIdType": "CPF",
        "telephoneNumber": "+551146425858",
        "type": "COMPANY"
      },
      "preserveSensitiveData": true,
      "relatedDocument": {
        "category": "string",
        "documentId": "string",
        "isPublic": true,
        "type": "string"
      },
      "tags": [
        "string"
      ],
      "target": {
        "externalCreatedAt": "2020-01-01T00:00:00.000Z",
        "externalId": "b195f113-3edb-4208-bb0e-632c09732e2f",
        "isPublic": true,
        "isPubliclySearchable": true,
        "subtype": "Wood",
        "type": "ORGANIC",
        "value": 0
      },
      "value": 1000
    }
  ],
  "externalCreatedAt": "2020-01-01T00:00:00.000Z",
  "externalId": "123456",
  "id": "28b04f62-8fe2-4332-b854-fe8a922788b5",
  "isPublic": true,
  "isPubliclySearchable": true,
  "measurementUnit": "kg",
  "parentDocumentId": "6sV74NaFq_hWLt6v5pWd5",
  "participant": {
    "businessName": "Compostagem Corporate LTDA",
    "countryCode": "BR",
    "email": "joaodaf.54@gmail.com",
    "mobileNumber": "+551123456789",
    "name": "João da Fonseca",
    "taxId": "11111111111",
    "taxIdType": "CPF",
    "telephoneNumber": "+551146425858",
    "type": "COMPANY"
  },
  "primaryAddress": {
    "city": "São Paulo",
    "complement": "Apto. 50",
    "countryCode": "BR",
    "countryState": "São Paulo",
    "latitude": -23.5489,
    "longitude": -46.6388,
    "name": "Edifício Jardins de Monet",
    "neighborhood": "José Bonifácio",
    "number": "500",
    "street": "Rua das Colinas",
    "zipCode": "08575720"
  },
  "primaryParticipant": {
    "businessName": "Compostagem Corporate LTDA",
    "countryCode": "BR",
    "email": "joaodaf.54@gmail.com",
    "mobileNumber": "+551123456789",
    "name": "João da Fonseca",
    "taxId": "11111111111",
    "taxIdType": "CPF",
    "telephoneNumber": "+551146425858",
    "type": "COMPANY"
  },
  "shortTitle": "MassID",
  "status": "OPEN",
  "subtype": "Wood",
  "tags": [
    "string"
  ],
  "title": "MassID",
  "type": "ORGANIC"
}

Empty

Utilize GET /documents/{id} para obter o payload completo do documento, incluindo:

status e valor atuais
referências de participante e endereço
linha do tempo completa de eventos
flags de visibilidade pública

Nota de design: imutabilidade

Os dados do documento são apenas por adição (append-only) na prática. Não há endpoint PATCH/PUT para mutação de documento e nem endpoint DELETE. Alterações operacionais são representadas como eventos.

Para um fluxo orientado à produção, consulte Enviando um MassID.

201application/json

400

401

504

200application/json

400

401

504

On this page

`application/json`

`application/json`