Campanhas

Campanhas organizam ações de marketing do time e podem estar vinculadas a um projeto. Todas as operações usam a chave de API para identificar o time.

GET /campaigns

Lista as campanhas do time autenticado.

Parâmetros de consulta

Quando sort é omitido, a API usa -created_at. Para um campo fora da lista, ela usa created_at e preserva a direção informada: invalido fica ascendente e -invalido, descendente.

Status disponíveis

Para criar, atualizar e filtrar campanhas com o schema atual, use draft, active, paused ou completed. O handler também reconhece scheduled e cancelled, mas o CHECK versionado do banco os rejeita; escritas com esses valores retornam 500 INTERNAL_ERROR.

O banco também admite archived, mas o handler não o aceita em POST ou PUT e ignora status=archived na listagem. Portanto, archived não é um filtro funcional nesta API.

Exemplo

curl "https://app.usecolmeia.com/api/v1/campaigns?status=active&sort=-updated_at" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

Resposta

{
  "success": true,
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Lançamento do serviço de consultoria",
      "description": "Planejamento de divulgação do novo serviço.",
      "status": "active",
      "approval_status": "draft",
      "start_date": "2026-08-01",
      "end_date": "2026-08-31",
      "content_pillars": ["especialização"],
      "target_platforms": ["linkedin"],
      "goals": { "leads_qualificados": 20 },
      "project_id": "22222222-2222-4222-8222-222222222222",
      "project": {
        "id": "22222222-2222-4222-8222-222222222222",
        "name": "Expansão comercial"
      },
      "created_by": null,
      "created_at": "2026-08-01T09:00:00.000Z",
      "updated_at": "2026-08-05T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "pages": 1
  }
}

POST /campaigns

Cria uma campanha. name é removido dos espaços nas extremidades antes de ser salvo.

O handler reconhece scheduled e cancelled, mas o schema atual rejeita esses dois status e o POST retorna 500 INTERNAL_ERROR se forem enviados.

Exemplo

curl -X POST "https://app.usecolmeia.com/api/v1/campaigns" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Lançamento do serviço de consultoria",
    "project_id": "22222222-2222-4222-8222-222222222222"
  }'

Em caso de sucesso, retorna 201 e o objeto de campanha no envelope { "success": true, "data": ... }, com os campos exibidos na resposta de listagem.

GET /campaigns/:id

Busca uma campanha pelo UUID. A resposta de sucesso é o objeto de campanha mapeado, incluindo project com id e name quando o vínculo estiver disponível.

curl "https://app.usecolmeia.com/api/v1/campaigns/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui"

PUT /campaigns/:id

Atualiza parcialmente uma campanha. Envie ao menos um dos campos abaixo; um corpo sem campos aceitos retorna 400 VALIDATION_ERROR.

curl -X PUT "https://app.usecolmeia.com/api/v1/campaigns/11111111-1111-4111-8111-111111111111" \
  -H "Authorization: Bearer ea_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paused" }'

A resposta é 200 com o objeto de campanha mapeado.

O handler também reconhece scheduled e cancelled, mas o schema atual rejeita esses dois status e a atualização retorna 500 INTERNAL_ERROR se forem enviados.

DELETE /campaigns/:id

Temporariamente indisponível para campanhas existentes. O handler tenta cancelar logicamente a campanha ao definir status como cancelled, mas o CHECK versionado do banco rejeita esse valor. Para uma campanha existente, a rota retorna 500 INTERNAL_ERROR e não altera o registro. Para um UUID inexistente no time autenticado, retorna 404 NOT_FOUND.

Erros

Todas as rotas retornam 401 UNAUTHORIZED quando a chave de API não é válida. GET, PUT e DELETE por um UUID inexistente retornam 404 NOT_FOUND. Criação e atualização retornam 400 VALIDATION_ERROR para JSON inválido, campos obrigatórios ausentes, status fora do allowlist do handler ou ausência de campos atualizáveis. O DELETE está temporariamente indisponível e retorna 500 INTERNAL_ERROR para uma campanha existente; o mesmo ocorre quando POST ou PUT recebem scheduled ou cancelled, pois o schema atual rejeita esses valores.