Docs
IntegrationsReferência da API

Documentos

Criar e recuperar registros de documentos (MassIDs) na Carrot API.

Last updated on

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

POST
/documents

Header Parameters

Authorization*string

Token de autorização

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/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"}

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

Enviar objetos completos participant ou address inline em vez de participantId/addressId está descontinuado e será removido em uma versão futura. Resolva participantes e endereços primeiro e então referencie-os por ID.

Campos opcionais:

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

Recuperar documento por id

GET
/documents/{id}

Path Parameters

id*string

Identificador do documento

Header Parameters

Authorization*string

Token de autorização

Response Body

application/json

curl -X GET "https://example.com/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"}

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.

Autenticação

Fluxo de credenciais de cliente OAuth 2.0 para acesso à Carrot API.

Eventos

Adicionar eventos imutáveis às linhas do tempo de documentos na Carrot API.

On this page

Criar documentoRecuperar documento por idNota de design: imutabilidade