> ## Documentation Index > Fetch the complete documentation index at: https://docs.connectadesk.com/llms.txt > Use this file to discover all available pages before exploring further. # Buscar cards do painel > Busca paginada dos cards de um painel, com filtros. O detalhe do painel (`GET /crm/boards/{boardId}`) devolve as etapas com os cards dentro delas e serve para montar o quadro. Para procurar cards, use este endpoint. Todos os filtros são opcionais e podem ser combinados. ## OpenAPI ````yaml /api-reference/openapi.yaml get /crm/boards/{boardId}/cards openapi: 3.0.3 info: title: Connecta DESK API pública version: 1.0.0 description: > API pública do Connecta DESK, disponível em `/api/v1`. O acesso é feito com um token gerado no módulo de tokens. Cada token tem permissões por **módulo × método**, e toda leitura de lista é paginada. ## Autenticação ``` Authorization: Bearer sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 ``` O token pertence a uma **empresa**, e não a um usuário. A empresa usada é sempre a do token, então enviar `companyId` no corpo não tem efeito. Token ausente, inválido, revogado ou expirado recebe a mesma resposta `401`. ## Ordem de verificação 1. **token** → `401` 2. **empresa ativa** → `403` 3. **API habilitada no plano** → `403 ERR_API_NOT_ENABLED` (não se aplica a on-premise) 4. **rate limit da empresa** → `429` 5. **permissão do token** → `403 ERR_API_FORBIDDEN_SCOPE` ## Ids de usuário Todo id de usuário na API é o id do usuário **nesta empresa**, o mesmo que `GET /users` devolve. Vale para o que a API responde (`user.id`, `assignedTo.id`, `userCreated.id`) e para o que ela aceita (`userId`, `userIds`, `assignedToUserId` e o `{id}` das rotas de usuário). A mesma pessoa pode trabalhar em várias empresas, com nome e perfil diferentes em cada uma, e tem um id diferente em cada empresa. Um id que não pertence a esta empresa responde `404`, com a mesma mensagem de um id inexistente. ## Paginação Todo `GET` de lista é paginado. O `meta` traz apenas `page`, `perPage` e `hasMore`, sem o total de registros. Para percorrer tudo, avance `page` enquanto `hasMore` for `true`. ## Idempotência Opcional em `POST`/`PUT`, pelo header `Idempotency-Key`. Se você repetir a chamada com a mesma chave e o mesmo corpo, recebe a resposta já gravada (com `Idempotent-Replay: true`). Com a mesma chave e um corpo diferente, a resposta é `409`. servers: - url: https://api.connectadesk.com/api/v1 description: Produção security: - apiToken: [] tags: - name: contacts description: Cadastro de contatos, campos extras e origem de marketing. - name: tickets x-displayName: Conversas description: Abertura, transferência, encerramento e qualificação de conversas. - name: messages description: Envio assíncrono e leitura de mensagens. - name: tags description: Tags e vínculo com atendimentos. - name: queues description: Filas de atendimento e seus atendentes. - name: wrapups description: Tipos de qualificação. - name: users description: Atendentes e administradores. - name: schedules description: Mensagens programadas. - name: quick-messages description: Respostas rápidas. - name: campaigns description: Disparos em massa. - name: crm description: Painéis, etapas, cards e indicadores. - name: channels description: Canais (somente leitura). - name: reports description: Relatórios e dashboards. - name: products description: Catálogo de produtos, categorias e desempenho nas vendas. - name: custom-fields description: >- Campos personalizados de contato e de card, e variáveis globais da empresa. - name: profiles description: Perfis de permissões da empresa (somente leitura). - name: webchat description: >- Webchat nativo pelo seu sistema: abrir sessão de um visitante, enviar e ler mensagens. O token precisa do escopo `webchat` (GET e POST). paths: /crm/boards/{boardId}/cards: parameters: - name: boardId in: path required: true schema: type: integer example: 7 get: tags: - crm summary: Buscar cards do painel description: > Busca paginada dos cards de um painel, com filtros. O detalhe do painel (`GET /crm/boards/{boardId}`) devolve as etapas com os cards dentro delas e serve para montar o quadro. Para procurar cards, use este endpoint. Todos os filtros são opcionais e podem ser combinados. parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/perPage' - name: search in: query description: >- Busca no nome e na descrição do card, sem diferenciar maiúsculas de minúsculas. schema: type: string example: pós - name: crmBoardListId in: query description: Só os cards desta etapa do painel. schema: type: integer example: 31 - name: assignedToUserId in: query description: Só os cards sob a responsabilidade deste usuário. schema: type: integer example: 3 - name: crmOriginId in: query description: Só os cards desta origem. schema: type: integer example: 5 - name: crmBusinessId in: query description: Só os cards vinculados a este negócio. schema: type: integer example: 9 - name: crmBoardCardStatusId in: query description: >- Só os cards com este status. Os status são configurados em cada etapa. schema: type: integer example: 2 - name: contactId in: query description: Só os cards vinculados a este contato. schema: type: integer example: 1042 - name: won in: query description: >- `true` traz só os cards ganhos e `false`, só os não ganhos. Sem o parâmetro, vêm os dois. schema: type: boolean - name: creationSource in: query description: Filtra pelo meio usado para criar o card. schema: type: string enum: - api - user - bot - automation description: | Quem criou o registro: | valor | significado | | --- | --- | | `api` | Esta API. | | `user` | Uma pessoa, pelo painel. | | `bot` | Um chatbot. | | `automation` | Uma automação do Flow. | - name: createdFrom in: query description: >- Só os cards criados a partir desta data. O dia começa no fuso da sua empresa. schema: type: string format: date-time example: '2026-09-01' - name: createdTo in: query description: >- Só os cards criados até esta data. O dia termina às 23:59:59 no fuso da sua empresa. schema: type: string format: date-time example: '2026-09-30' - name: dueFrom in: query description: >- Só os cards com prazo a partir desta data. O dia começa no fuso da sua empresa. schema: type: string format: date-time example: '2026-09-01' - name: dueTo in: query description: >- Só os cards com prazo até esta data. O dia termina às 23:59:59 no fuso da sua empresa. schema: type: string format: date-time example: '2026-09-30' - name: orderBy in: query description: >- Campo usado para ordenar a lista. Um valor desconhecido é trocado pelo padrão. schema: type: string enum: - createdAt - updatedAt - due - position - name description: | Campo usado para ordenar: | valor | significado | | --- | --- | | `createdAt` | Data de criação. | | `updatedAt` | Data da última alteração. | | `due` | Prazo do card. | | `position` | Posição dentro da etapa, como no quadro. | | `name` | Nome do card. | default: createdAt - name: order description: 'Direção da ordenação: `asc` crescente, `desc` decrescente.' in: query schema: type: string enum: - asc - desc description: | Direção da ordenação: | valor | significado | | --- | --- | | `asc` | Crescente. | | `desc` | Decrescente. | default: desc responses: '200': description: OK content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/CrmCard' meta: $ref: '#/components/schemas/PageMeta' '400': description: >- Erro `ERR_API_VALIDATION`, quando a data, o `creationSource` ou o `boardId` é inválido. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: O painel não existe ou pertence a outra empresa. content: application/json: schema: $ref: '#/components/schemas/Error' '429': $ref: '#/components/responses/TooManyRequests' components: parameters: page: name: page in: query description: Número da página, começando em 1. Um valor inválido é tratado como 1. schema: type: integer minimum: 1 default: 1 example: 1 perPage: name: perPage in: query description: >- Quantidade de itens por página. O máximo depende do ambiente (padrão 100). schema: type: integer minimum: 1 maximum: 100 default: 20 example: 50 schemas: CrmCard: type: object description: >- Card de um painel do CRM. A resposta traz apenas os campos listados aqui. properties: id: type: integer name: type: string description: Nome exibido. description: type: string nullable: true description: Descrição do card. won: type: boolean description: Card marcado como ganho. wonDate: type: string format: date-time nullable: true statusReason: type: string nullable: true description: Motivo registrado no ganho ou na perda. example: Fechou o plano anual. boardId: type: integer description: Painel do CRM a que o card pertence. example: 7 list: type: object nullable: true description: Etapa em que o card está. properties: id: type: integer name: type: string description: Nome exibido. status: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. color: type: string nullable: true description: Cor em hexadecimal, com `#`. example: '#6941C6' business: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. origin: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. assignedTo: type: object nullable: true description: Responsável pelo card. O nome é o que a pessoa usa nesta empresa. properties: id: type: integer name: type: string description: Nome exibido. contacts: type: array description: >- Contatos vinculados ao card, com os dados completos, incluindo tags, campos personalizados e todos os campos de marketing. Você não precisa chamar `GET /contacts/{id}` para cada um. items: $ref: '#/components/schemas/Contact' products: type: array items: type: object properties: id: type: integer productId: type: integer nullable: true example: 55 name: type: string description: Nome exibido. sku: type: string nullable: true example: CAM-PRETA-M quantity: type: number description: Quantidade do produto. example: 2 unitPrice: type: number description: Preço unitário cobrado. example: 149.9 totalPrice: type: number description: >- Valor total do item, calculado pelo servidor como `quantity` × `unitPrice`. example: 299.8 productsTotal: type: number description: Soma dos valores de todos os produtos do card. customFields: type: array description: >- Campos personalizados de CRM (`application: card`) preenchidos neste card. Sempre vem na resposta, como lista vazia quando o card não tem nenhum. items: $ref: '#/components/schemas/CustomFieldValue' creationSource: type: string nullable: true enum: - api - user - bot - automation description: | Origem da criação do card: | valor | significado | | --- | --- | | `api` | Esta API. | | `user` | Uma pessoa, pelo painel. | | `bot` | Um chatbot. | | `automation` | Uma automação do Flow. | due: type: string format: date-time nullable: true example: '2026-09-15T12:00:00.000Z' createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 4471 name: 'Pedido #88213' description: Cliente pediu retorno na segunda de manhã. won: false wonDate: null statusReason: null boardId: 7 list: id: 31 name: Aguardando envio status: id: 2 name: Em negociação color: '#F59E0B' business: id: 9 name: Varejo origin: id: 5 name: Instagram assignedTo: id: 3 name: Gabriel Goulart contacts: - id: 1042 name: Marina Alves number: '5511999999999' email: marina@exemplo.com.br code: CLI-8842 cpfCnpj: '12345678909' origin: Site profilePicUrl: https://cdn.exemplo.com.br/avatar/1042.jpg isGroup: false instagramUsername: marina.alves sourceUrl: https://loja.exemplo.com.br/promo sourceId: '23851234567890123' headline: Coleção de inverno utmSource: instagram utmMedium: cpc utmCampaign: inverno-2026 utmId: '6543210987' tags: - id: 3 name: Cliente VIP color: '#6941C6' customFields: - key: plano value: Ouro customFieldId: 91 name: Plano type: select lastChannel: id: 11 name: Instagram Loja type: instagram createdAt: '2026-07-14T13:22:05.412Z' updatedAt: '2026-08-18T09:41:17.883Z' products: - id: 812 productId: 55 name: Camiseta preta M sku: CAM-PRETA-M quantity: 2 unitPrice: 149.9 totalPrice: 299.8 productsTotal: 299.8 customFields: - key: prioridade value: Alta customFieldId: 77 name: Prioridade type: select creationSource: api due: '2026-09-15T12:00:00.000Z' createdAt: '2026-09-08T14:32:10.000Z' updatedAt: '2026-09-08T16:02:44.000Z' PageMeta: type: object required: - page - perPage - hasMore properties: page: type: integer example: 1 perPage: type: integer example: 20 hasMore: type: boolean description: Indica se há mais registros além desta página. example: true example: page: 1 perPage: 20 hasMore: true Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Código fixo do erro, para você tratar cada caso no seu sistema. example: ERR_API_FORBIDDEN_SCOPE message: type: string details: {} Contact: type: object properties: id: type: integer name: type: string description: Nome exibido. number: type: string numberCountry: type: string nullable: true description: >- País do número, no padrão ISO 3166-1 alfa-2. Deduzido do DDI quando o número é gravado pela API. example: BR email: type: string nullable: true example: marina@exemplo.com.br code: type: string nullable: true cpfCnpj: type: string nullable: true example: '12345678909' origin: type: string nullable: true profilePicUrl: type: string nullable: true example: https://cdn.exemplo.com.br/avatar/1042.jpg isGroup: type: boolean description: O contato é um grupo, e não uma pessoa. instagramUsername: type: string nullable: true example: marina.alves lid: type: string nullable: true example: '178452961234567' sourceUrl: type: string nullable: true example: https://loja.exemplo.com.br/promo sourceId: type: string nullable: true example: '23851234567890123' headline: type: string nullable: true example: Coleção de inverno mediaType: type: string nullable: true example: image mediaUrl: type: string nullable: true example: https://cdn.exemplo.com.br/anuncios/inverno.jpg utmSource: type: string nullable: true example: instagram utmMedium: type: string nullable: true example: cpc utmCampaign: type: string nullable: true example: inverno-2026 utmId: type: string nullable: true example: '6543210987' fbclid: type: string nullable: true example: IwAR0xYzAbC123 gclid: type: string nullable: true ctwaClid: type: string nullable: true tags: type: array items: type: object properties: id: type: integer name: type: string description: Nome exibido. color: type: string description: Cor em hexadecimal, com `#`. example: '#6941C6' customFields: type: array description: >- Campos personalizados de contato preenchidos. Sempre vem na resposta, como lista vazia quando o contato não tem nenhum. items: $ref: '#/components/schemas/CustomFieldValue' lastChannel: type: object nullable: true properties: id: type: integer name: type: string description: Nome exibido. type: type: string createdAt: type: string format: date-time updatedAt: type: string format: date-time example: id: 842 name: Maria Silva number: '5511987654321' numberCountry: BR email: maria.silva@exemplo.com.br code: CLI-00842 cpfCnpj: '12345678909' origin: site profilePicUrl: https://cdn.exemplo.com/avatars/842.jpg isGroup: false instagramUsername: maria.silva lid: null sourceUrl: https://loja.exemplo.com.br/promo sourceId: '23851234567890123' headline: Coleção de inverno mediaType: image mediaUrl: https://cdn.exemplo.com/anuncios/inverno.jpg utmSource: instagram utmMedium: cpc utmCampaign: inverno-2026 utmId: '6543210987' fbclid: IwAR0xYzAbC123 gclid: null ctwaClid: null tags: - id: 3 name: Cliente VIP color: '#6941C6' customFields: - key: plano value: Ouro customFieldId: 91 name: Plano type: select lastChannel: id: 11 name: Instagram Loja type: instagram createdAt: '2026-07-14T13:22:05.412Z' updatedAt: '2026-08-18T09:41:17.883Z' CustomFieldValue: type: object description: >- Valor de um campo personalizado, junto com a definição do campo. Assim você não precisa chamar `GET /custom-fields` para saber qual é o campo 91. properties: key: type: string nullable: true description: >- Identificador fixo do campo. Use-o para indicar o campo ao gravar valores, porque o `name` pode ser renomeado no painel e a integração deixaria de funcionar sem aviso. value: type: string description: Valor preenchido no campo, no formato definido pelo tipo. customFieldId: type: integer description: Id da definição do campo personalizado. example: 91 name: type: string nullable: true description: Nome exibido. type: type: string nullable: true description: Tipo do campo, que define o formato aceito no valor. example: key: plano value: Ouro customFieldId: 91 name: Plano type: select responses: Unauthorized: description: Token ausente, inválido, revogado ou expirado. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_UNAUTHORIZED message: Token de API ausente ou inválido. Forbidden: description: Empresa inativa, API não habilitada no plano ou permissão insuficiente. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_FORBIDDEN_SCOPE message: >- O token não tem permissão para este método neste módulo. A mensagem real nomeia os dois. TooManyRequests: description: A empresa ultrapassou o limite de requisições por minuto. headers: RateLimit-Limit: schema: type: integer description: Limite de requisições por minuto. RateLimit-Remaining: schema: type: integer description: Quantas requisições ainda restam na janela atual. RateLimit-Reset: schema: type: integer description: Segundos até a janela reiniciar. Retry-After: schema: type: integer description: Tempo de espera antes de tentar de novo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: ERR_API_RATE_LIMIT message: Limite de requisições por minuto excedido para esta empresa. securitySchemes: apiToken: type: http scheme: bearer description: Token da API no formato `sk_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.