Convenções e Padrões de Dados

A Perpetuus API utiliza padrões consistentes em todos os seus módulos para garantir clareza nas integrações. Esta página detalha as principais convenções arquiteturais do sistema.

Identificadores Únicos (documentId)

Em conformidade com a arquitetura moderna de nosso motor de persistência, todos os registros acessíveis pela API expõem e utilizam identificadores únicos de string conhecidos como documentId (ex: qt1a2b3c, pr9x8y7z).

Convenções de Parâmetros nas URLs

Nos endpoints que exigem parâmetros de caminho (path parameters), você encontrará principalmente as seguintes variáveis:

• :boardId / :boardDocumentId: O documentId do quadro. Ex: /boards/{boardId}/cards.
• :id: Usado no CRUD básico de recursos individuais. Ex: /contacts/{id} ou /boards/{id}.
• :cardId / :membershipId: Parâmetros específicos em relacionamentos ou sub-recursos. Ex: /teams/{id}/members/{membershipId}.

Envelopes de Resposta

A API responde utilizando dois formatos principais de estrutura de dados:

1. Envelope Padrão (Tipo Strapi)

Utilizado pela maioria dos endpoints de listagem de dados e CRUD. Segue a estrutura com chaves data (que pode ser um objeto ou uma lista de objetos) e meta.

{
  "data": [
    {
      "documentId": "card_9x8y7z",
      "title": "Proposta Comercial ACME",
      "createdAt": "2026-07-09T18:00:00Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 25,
      "pageCount": 1,
      "total": 1
    }
  }
}

2. Envelope Analítico (Tipo Report)

Utilizado exclusivamente em endpoints de agregação e métricas de inteligência comercial, como o GET /boards/{boardId}/report. Estes payloads retornam dados prontos para análise sem chaves internas de paginação.

{
  "boardId": "board_xyz",
  "summary": {
    "totalCards": 120,
    "wonValue": 450000.00
  },
  "phases": [
    {
      "documentId": "phase_abc",
      "name": "Proposta Enviada",
      "cardsCount": 15
    }
  ],
  "period": {
    "from": "2026-07-01",
    "to": "2026-07-09"
  }
}

Associações de Tags em Cards

Ao criar ou atualizar cards via API (POST ou PUT), o campo tags é flexível: você pode enviar tanto o documentId da tag quanto o slug cadastrado no board.

{
  "data": {
    "title": "Novo Card",
    "tags": ["prioritario", "tag_doc_id_123"]
  }
}

• Se o slug de tag fornecido não existir previamente no board, a API retornará status 400 Bad Request com a lista de tags válidas.
• Na leitura de dados (GET), a associação de tags sempre retornará objetos estruturados contendo documentId, name e slug.