> For the complete documentation index, see [llms.txt](https://docs.helena.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helena.app/duvidas-e-novidades/novidades-de-produto/maio-de-2026/29-05-2026-api-crm-de-vendas.md).

# 29/05/2026 - API CRM de Vendas

### 🔗 Evolução na API para suportar novos recursos do CRM

A API do CRM foi atualizada para suportar o novo ciclo de vida de Ganho e Perda nos cards. As mudanças incluem novos filtros, campos de resposta e um endpoint dedicado para motivos de perda, tudo de forma retrocompatível, já que todos os novos parâmetros são opcionais.

***

#### ✅ **O que foi adicionado?**

### **1. Novo endpoint GET /v2/panel — Filtro e campo type**

• Foi criada uma **versão V2** do endpoint de listagem de painéis para suportar os novos recursos.\
• Novo parâmetro de query opcional **type** para filtrar painéis pelo tipo. Valores aceitos: SALES e MANAGEMENT.\
• O campo **type** é retornado no objeto de cada painel na resposta, indicando se ele é do tipo Vendas (SALES) ou Gestão (MANAGEMENT).

> ⚠️ O endpoint GET /v1/panel **não foi alterado** e continua funcionando normalmente. Vale lembrar que a V1 retorna apenas painéis do tipo Gestão (MANAGEMENT). Para acessar painéis do tipo Vendas, utilize a V2.

<figure><img src="/files/kzoFyT5jLq74u1sIr0w5" alt=""><figcaption></figcaption></figure>

### **2. Novo endpoint GET /v2/cards — Filtro por situação, campo status e motivo de perda**

• Foi criada uma **versão V2** do endpoint de listagem de cards para suportar os novos recursos.\
• Novo parâmetro de query opcional **statuses** para filtrar cards por situação. Valores aceitos: OPEN, WON, LOST e ARCHIVED. É possível informar múltiplos valores simultaneamente.\
• O campo **status** é retornado no objeto de cada card na resposta, refletindo o estado atual da negociação.\
• O parâmetro **includeDetails** passa a aceitar o novo valor LostReason. Quando informado, a resposta de cada card com status LOST incluirá o objeto **lostReason**, contendo o id e o name do motivo registrado. Se LostReason não for enviado, o objeto lostReason ainda aparece na resposta, porém com os campos id e name retornando como null.

> **OPEN** → card em andamento, sem marcação de ganho/perda e sem arquivamento.

<figure><img src="/files/oFwNjMy09CUJwH0JNTFT" alt=""><figcaption></figcaption></figure>

### **3. Novo endpoint GET /v1/panels/{panelId}/lost-reasons**

• Endpoint dedicado para listar os **motivos de perda** cadastrados em um painel específico do tipo Vendas (SALES).\
• Retorna a lista de motivos disponíveis com id e name de cada item.

<figure><img src="/files/2Q7tDZ1gWSGfsTgVMZk1" alt=""><figcaption></figcaption></figure>

### **4. Endpoint PUT /v3/panel/card/{id} — Atualização de status e remoção do parâmetro archived**

• Foi criada uma **versão V3** do endpoint de atualização de card para consolidar o gerenciamento de estado.\
• O array **fields** passa a aceitar o valor "status", permitindo atualizar a situação do card via requisição PUT.\
• Novo parâmetro opcional **status** no corpo da requisição. Valores aceitos: OPEN, WON, LOST e ARCHIVED. Apenas um valor pode ser enviado por vez.\
• O campo **status** com o valor atualizado passa a ser retornado no objeto de resposta.\
• O parâmetro **archived** foi removido do corpo da requisição, da resposta e dos valores aceitos no array fields, pois foi substituído pelo novo campo status.

> ⚠️ O parâmetro archived foi removido **apenas na V3**. Se você utiliza esse parâmetro e deseja migrar para a V3, atualize para o novo campo status com o valor ARCHIVED. Caso permaneça na V2, nenhuma alteração é necessária.

> ℹ️ A marcação de status WON (Ganho) ou LOST (Perda) é exclusiva para cards de **painéis do tipo Vendas** (SALES). Tentativas de aplicar esses status em cards de painéis do tipo Gestão (MANAGEMENT) não são suportadas.

<figure><img src="/files/Bs06JTQJ7nSEojuJ5j8q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/LNMNdXaTggeCNqegte9n" alt=""><figcaption></figcaption></figure>

### **5. Endpoint PUT /v3/panel/card/{id} — Bloqueio de movimentação de etapa para cards finalizados**

• Cards com status WON (Ganho) ou LOST (Perda) não podem ter sua etapa (stepId) alterada enquanto estiverem nesse estado.\
• Tentativas de mover a etapa de um card finalizado resultarão em erro, com mensagem indicando que o card não pode ser movido. Para reabrir o card, atualize o status para OPEN antes de alterar a etapa.

> ℹ️ Esta validação se aplica às versões V2 e V3 do endpoint de atualização de card.