Cards (Oportunidades e Leads)

Os Cards representam os itens de trabalho que fluem pelo pipeline do seu Board, como oportunidades de venda, chamados de atendimento ou tarefas.

---

Endpoints Canônicos

1. Listar Cards de um Board

Retorna todos os cards pertencentes a um quadro específico. Suporta filtros complexos, ordenação e paginação.

• Método: GET
• Caminho: /boards/{boardId}/cards
• Exemplo com paginação e relações:

  curl -G "https://api.perpetuus.com.br/api/boards/BOARD_ID/cards" \
    -H "Authorization: Bearer SEU_TOKEN" \
    -H "x-tenant-id: acme" \
    --data-urlencode "pagination[pageSize]=25" \
    --data-urlencode "populate[0]=assignees" \
    --data-urlencode "populate[1]=tags"

---

2. Criar Card no Board

Cria um card na fase inicial do Board (Phase 0). Qualquer campo dinâmico obrigatório configurado para a primeira fase do quadro deve ser enviado no objeto fields.

• Método: POST
• Caminho: /boards/{boardId}/cards
• Payload de Exemplo:

  {
    "data": {
      "title": "Lead ACME Corp",
      "description": "Originado via integração API",
      "fields": {
        "email": "contato@acme.com",
        "phone": "+5511999999999",
        "tamanho_empresa": "100-500"
      },
      "tags": ["prioritario"],
      "dueDate": "2026-12-31T18:00:00Z"
    }
  }

---

3. Atualizar Card e Mover de Fase

Atualiza metadados, campos dinâmicos customizados ou move o card de estágio no pipeline utilizando a propriedade currentPhase.

• Método: PUT
• Caminho: /boards/{boardId}/cards/{id}
• Payload para atualizar dados e mover de fase:

  {
    "data": {
      "title": "ACME Corp - Negociação Avançada",
      "value": 150000.00,
      "currentPhase": "phase_doc_id_negociacao",
      "fields": {
        "data_proposta": "2026-07-10",
        "status_proposta": "Apresentada"
      }
    }
  }

---

4. Excluir Card

Remove definitivamente um card do quadro. Esta ação é irreversível.

• Método: DELETE
• Caminho: /boards/{boardId}/cards/{id}