Como obter os contatos de uma coluna do CRM via API

Cada card do CRM pode ter um ou mais contatos vinculados. O endpoint de listagem de cards devolve essa relação aninhada — assim você obtém, numa só chamada, os leads de uma coluna (etapa do funil) com nome, telefone/PSID, e-mail e canal.

Pré-requisitos:

1. Token de integração
2. column_id — veja Como listar boards e colunas do CRM via API

Endpoint

GET /crm/cards/fetch?column_id=<uuid>
Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO

Query params

Sem page e sem limit, a API retorna todos os cards que batem no filtro (útil em colunas pequenas). Em colunas grandes (dezenas/centenas de leads), use paginação.

Exemplo — todos os cards de uma coluna

curl -s "https://api.whatswave.com.br/crm/cards/fetch?column_id=COLUMN_ID" \
  -H "Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO"

Exemplo — com paginação

# Página 1, 50 cards
curl -s "https://api.whatswave.com.br/crm/cards/fetch?column_id=COLUMN_ID&page=1&limit=50" \
  -H "Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO"

# Página 2
curl -s "https://api.whatswave.com.br/crm/cards/fetch?column_id=COLUMN_ID&page=2&limit=50" \
  -H "Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO"

Resposta (formato resumido):

{
  "success": true,
  "message": "Cards listados com sucesso",
  "data": [
    {
      "id": "33333333-3333-3333-3333-333333333333",
      "column_id": "22222222-2222-2222-2222-222222222222",
      "crm_board_id": "11111111-1111-1111-1111-111111111111",
      "instance_number": "5511999999999",
      "title": "Ana Silva",
      "description": "Pediu proposta até sexta.",
      "position": 0,
      "metadata": {},
      "company_id": "44444444-4444-4444-4444-444444444444",
      "enabled": true,
      "created_at": "2026-03-23T12:00:00.000Z",
      "updated_at": "2026-03-23T12:00:00.000Z",
      "contacts": [
        {
          "id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
          "contact_id": "cccccccc-dddd-eeee-ffff-000000000000",
          "contact": {
            "id": "cccccccc-dddd-eeee-ffff-000000000000",
            "name": "Ana Silva",
            "phone_number": "5511999999999",
            "email": "ana@empresa.com",
            "avatar": null,
            "channel": "whatsapp",
            "instagram_username": null,
            "jid": "5511999999999@s.whatsapp.net",
            "tags": [],
            "metadata": {}
          }
        }
      ],
      "comments": []
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 79,
    "total_pages": 2
  }
}

O objeto pagination só aparece quando você envia page e/ou limit.

Como ler os contatos

Para cada card em data:

Em JavaScript:

const { data, pagination } = await res.json()

for (const card of data) {
  const contacts = (card.contacts || []).map((link) => link.contact)
  console.log(card.title, contacts)
}

if (pagination && pagination.page < pagination.total_pages) {
  // buscar page + 1
}

Board inteiro (todas as colunas)

Se quiser todos os cards do board (e não só de uma coluna):

curl -s "https://api.whatswave.com.br/crm/cards/fetch?board_id=BOARD_ID&page=1&limit=100" \
  -H "Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO"

Filtre no seu código por column_id se precisar.

Um card específico

curl -s "https://api.whatswave.com.br/crm/cards/get?card_id=CARD_ID" \
  -H "Authorization: Bearer SEU_TOKEN_DE_INTEGRACAO"

A resposta de um card também inclui contacts[].contact.

Boas práticas

• Prefira sempre column_id quando o objetivo for “leads da etapa X”
• Em colunas grandes, use page + limit e percorra até page === total_pages
• Payloads e query params em snake_case
• Documentação ao vivo: Swagger → tag CRM - Cards

Próximos passos

• Como listar boards e colunas do CRM via API
• Como obter o token de integração
• API REST e GraphQL
• Como o agente cria cards no CRM
• Como automatizar o CRM com workflows