Guia de Migração (Sunset Flat Routes)

Como atualizar suas integrações das rotas legadas flat para as rotas canônicas baseadas em Boards no Perpetuus.

Como parte da padronização e da otimização de segurança de multi-tenancy na Perpetuus API, todas as rotas de CRUD direto sem escopo de Board (rotas flat) foram descontinuadas ou removidas.

Por que migrar?

Segurança de Dados: As rotas aninhadas (ex: /boards/{boardId}/cards) garantem que o usuário e a API validem as permissões de acesso ao processo (Board) antes de ler ou escrever dados.
Campos Dinâmicos e Validação: O motor de validação de campos dinâmicos (fields) depende das definições de fase que pertencem a um Board. Rotas flat não suportam essa inteligência nativamente.
Desempenho: Consultas aninhadas reduzem o overhead de carregamento de registros órfãos ou de múltiplos boards simultaneamente.

Tabela de Substituição de Endpoints

Se você possui integrações antigas, substitua as chamadas conforme a convenção abaixo:

Método	Endpoint Legado (Flat)	Novo Endpoint Canônico (Nested)
GET	`/api/cards`	`GET /api/boards/{boardId}/cards`
POST	`/api/cards`	`POST /api/boards/{boardId}/cards`
GET	`/api/cards/{id}`	`GET /api/boards/{boardId}/cards/{id}`
PUT	`/api/cards/{id}`	`PUT /api/boards/{boardId}/cards/{id}`
DELETE	`/api/cards/{id}`	`DELETE /api/boards/{boardId}/cards/{id}`
GET	`/api/phases`	`GET /api/boards/{boardId}/phases`
GET	`/api/fields`	`GET /api/boards/{boardId}/fields`
GET	`/api/tags`	`GET /api/boards/{boardId}/tags`

Descobrindo o boardId: O parâmetro {boardId} exigido na URL corresponde ao documentId (string) do quadro. Você pode descobri-lo listando seus quadros via GET /api/boards ou copiando diretamente da URL do aplicativo web (ex: app.perpetuus.com.br/boards/BOARD_ID).

Exemplo de Transição de Código (Criar Card)

Antes (Legado)

// POST /api/cards
const res = await fetch('https://api.perpetuus.com.br/api/cards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      title: 'Oportunidade Legada',
      board: 'board_document_id_123' // Enviava o board no corpo
    }
  })
});

Agora (Canônico e Seguro)

// POST /api/boards/board_document_id_123/cards
const res = await fetch('https://api.perpetuus.com.br/api/boards/board_document_id_123/cards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer TOKEN',
    'x-tenant-id': 'minha-empresa', // Header tenant obrigatório
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: {
      fields: {
        name: 'Oportunidade Nova (Inbound)' // Campos no objeto fields
      }
    }
  })
});