Referência da API

Esta página reúne as convenções compartilhadas pelos endpoints da API v1 autenticados por chave de API. Cada página de recurso detalha os métodos, campos, filtros, ordenações e respostas aplicáveis àquela rota.

Base URL

https://app.usecolmeia.com/api/v1

Nos exemplos, os caminhos são relativos a essa URL. Por exemplo, GET /clients corresponde a GET https://app.usecolmeia.com/api/v1/clients.

Recursos

Autenticação

Envie a chave de API no header Authorization dos endpoints autenticados por chave:

Authorization: Bearer ea_live_sua_chave_aqui
Content-Type: application/json

A chave determina o time da requisição; não envie team_id para selecionar outro time. Consulte Autenticação para criar, rotacionar e proteger suas chaves.

Exceção: GET e POST /webhooks/inbound/:endpointId são públicos e não usam Bearer. Quando o endpoint estiver configurado com segredo, apenas o POST exige X-Webhook-Secret; essas rotas têm formato de resposta próprio. Consulte Webhooks.

Respostas

Sucesso

Nos endpoints autenticados por chave de API, operações que retornam um recurso usam o envelope abaixo:

{
  "success": true,
  "data": {
    "id": "00000000-0000-4000-8000-000000000001"
  }
}

Lista paginada

Nos endpoints autenticados por chave de API, operações de listagem retornam os itens em data e os metadados em pagination:

{
  "success": true,
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "pages": 0
  }
}

Erro

Nos endpoints autenticados por chave de API, erros usam success: false e descrevem o motivo em error:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Campo 'title' é obrigatório"
  }
}

Paginação

As rotas de lista autenticadas por chave de API aceitam os parâmetros abaixo:

Ordenação

Use sort=campo para ordem ascendente e sort=-campo para ordem descendente:

GET /clients?sort=full_name
GET /clients?sort=-created_at

Cada página de recurso informa os campos aceitos para ordenação. Um campo fora do allowlist da rota não deve ser usado como contrato de integração.

Datas e horários

Timestamps usam ISO 8601, por exemplo 2026-08-11T14:30:00Z. Quando um campo exigir uma data civil, envie YYYY-MM-DD, por exemplo 2026-08-11.

Idempotência em oportunidades

Somente POST /deals aceita o header opcional Idempotency-Key. Use uma chave de até 512 caracteres ao criar uma oportunidade:

POST /deals
Idempotency-Key: oportunidade-integracao-001

Reenvie a mesma chave com payload idêntico para reproduzir a criação já registrada, sem criar uma segunda oportunidade. A criação inicial responde 201; um replay responde 200 com o recurso existente. Reutilizar a mesma chave com payload diferente retorna 409 CONFLICT por idempotency_conflict.

Códigos HTTP

Os códigos abaixo aparecem na API v1. Eles não se aplicam a todas as rotas: consulte a página do recurso para saber quais respostas uma operação pode devolver.