CRM

O CRM do Festero acompanha cada interessado como uma oportunidade de venda, que anda por etapas do funil até virar venda ganha ou perdida. Estas rotas devolvem as oportunidades e as etapas, para você levar o funil a um BI, a um painel ou a outro sistema.

Escopo exigido: crm:read. Sem ele, as rotas respondem scope_missing.

Testar na referência interativa

Listar oportunidades

GET /v1/crm/opportunities

Lista as oportunidades da empresa, da alteração mais antiga para a mais recente, com paginação por cursor. Oportunidades mescladas em outra não aparecem.

Parâmetro	Tipo	Descrição
status	texto	Filtra pela situação: open, won, lost, duplicate ou notclient. Outro valor responde 400.
stageId	GUID	Só as oportunidades desta etapa do funil. Pegue os ids em GET /v1/crm/pipeline-stages.
updatedSince	data e hora ISO 8601	Só as oportunidades alteradas a partir deste instante.
limit	inteiro	Tamanho da página, de 1 a 100 (padrão 25).
cursor	texto	O nextCursor da página anterior.

curl "https://platform.festero.com.br/v1/crm/opportunities?status=open&limit=2" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "8d3f6b1e-52a4-4c7e-9a18-0b6c2f4d7e31",
      "title": "Aniversário de 15 anos da Marina",
      "status": "open",
      "stage": { "id": "c41e9a77-6d02-4b58-8f3a-91d5e7b20a64", "name": "Proposta enviada" },
      "client": { "id": "2a7b5c90-31de-4f68-b4a2-6e0d8c19f533", "name": "Marina Albuquerque" },
      "quoteId": "f09c3d12-7a5b-4e84-a6c1-3b8e5d2f9a70",
      "eventId": null,
      "estimatedValue": { "amount": 18500.00, "currency": "BRL" },
      "expectedEventDate": "2027-02-13",
      "eventTypeName": "Aniversário de 15 anos",
      "estimatedGuests": 120,
      "source": "vitrine",
      "closeReason": null,
      "closedAt": null,
      "lastContactAt": "2026-10-19T16:20:00-03:00",
      "nextFollowUpAt": "2026-10-23T10:00:00-03:00",
      "createdAt": "2026-10-12T09:41:17-03:00",
      "updatedAt": "2026-10-19T16:20:05-03:00"
    }
  ],
  "nextCursor": "eyJ0IjozOTU0..."
}

A resposta foi abreviada: com limit=2, data traria dois itens.

Buscar uma oportunidade

GET /v1/crm/opportunities/{id}

Devolve uma oportunidade pelo identificador, com os mesmos campos da lista. Responde 404 (not_found) se ela não existe, foi mesclada em outra ou é de outra empresa. A resposta traz ETag: veja Paginação e datas.

Parâmetro	Onde	Descrição
id	caminho	Identificador da oportunidade (GUID).

curl https://platform.festero.com.br/v1/crm/opportunities/8d3f6b1e-52a4-4c7e-9a18-0b6c2f4d7e31 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Listar as etapas do funil

GET /v1/crm/pipeline-stages

Lista todas as etapas do funil, na ordem do quadro do CRM no Festero. Não tem parâmetros. A resposta usa o mesmo formato das listas, com todas as etapas em data e nextCursor sempre null.

curl https://platform.festero.com.br/v1/crm/pipeline-stages \
  -H "Authorization: Bearer $ACCESS_TOKEN"

{
  "data": [
    {
      "id": "6b0d2f84-1c93-4e57-a8d6-3f7a9c5e1b20",
      "name": "Novo contato",
      "color": "#6366F1",
      "displayOrder": 1,
      "isDefault": true,
      "isClosedWon": false,
      "isClosedLost": false,
      "isVisitStage": false
    },
    {
      "id": "c41e9a77-6d02-4b58-8f3a-91d5e7b20a64",
      "name": "Proposta enviada",
      "color": "#F59E0B",
      "displayOrder": 3,
      "isDefault": false,
      "isClosedWon": false,
      "isClosedLost": false,
      "isVisitStage": false
    },
    {
      "id": "a95e3c17-8b24-4d60-b1f7-0e6d2a4c8f93",
      "name": "Fechado",
      "color": "#10B981",
      "displayOrder": 5,
      "isDefault": false,
      "isClosedWon": true,
      "isClosedLost": false,
      "isVisitStage": false
    }
  ],
  "nextCursor": null
}

Campos da oportunidade

Campo	Tipo	Descrição
id	GUID	Identificador da oportunidade.
title	texto	Título. Trechos que parecem telefone, e-mail ou documento aparecem como [oculto].
status	texto	open, won, lost, duplicate ou notclient.
stage	{ id, name }	Etapa atual no funil.
client	{ id, name } ou null	Cliente vinculado.
quoteId	GUID ou null	Orçamento vinculado (Orçamentos).
eventId	GUID ou null	Evento vinculado (Eventos).
estimatedValue	dinheiro ou null	Valor estimado da venda.
expectedEventDate	data ou null	Data do evento pedida pelo cliente. Na tela do Festero, "Data do evento".
eventTypeName	texto ou null	Nome do tipo de evento pretendido.
estimatedGuests	inteiro ou null	Número estimado de convidados.
source	texto ou null	Origem da oportunidade (canal de captação), em minúsculas.
closeReason	texto ou null	Código do motivo do fechamento.
closedAt	instante ou null	Quando foi encerrada.
lastContactAt	instante ou null	Último contato.
nextFollowUpAt	instante ou null	Próximo retorno agendado.
createdAt	instante	Criação.
updatedAt	instante ou null	Última alteração.

Campos da etapa

Campo	Tipo	Descrição
id	GUID	Identificador da etapa.
name	texto	Nome da etapa.
color	texto	Cor da etapa no quadro, em hexadecimal.
displayOrder	inteiro	Posição da etapa no funil.
isDefault	booleano	Indica a etapa padrão do funil.
isClosedWon	booleano	A etapa significa venda ganha.
isClosedLost	booleano	A etapa significa venda perdida.
isVisitStage	booleano	Etapa para onde vai a oportunidade quando uma visita é marcada.

Campos que pedem atenção

• Sem dados de contato. Telefone, e-mail e endereço do lead não existem na API, nem anotações, descrições livres ou o motivo de perda em texto: closeReason traz só o código.
• As etapas são da sua empresa. Cada empresa monta o próprio funil; por isso a rota de etapas existe. Use isClosedWon e isClosedLost para saber se uma oportunidade foi ganha ou perdida em vez de comparar nomes de etapa.
• status e etapa andam juntos, mas são coisas diferentes. status diz a situação (open, won, lost, duplicate, notclient); stage diz onde ela está no funil.
• source não é uma lista fechada. Trate-o como texto. O valor depende de por onde a oportunidade entrou (por exemplo, vitrine).
• Tempo real: os avisos opportunity.created e opportunity.stage_changed dispensam consultar o funil de tempos em tempos.

Erros possíveis

Código	HTTP	Quando
validation_failed	400	status inválido, limit fora de 1 a 100 ou cursor inválido.
scope_missing	403	A credencial não tem crm:read.
not_found	404	Oportunidade inexistente, mesclada ou de outra empresa.

Testar na referência interativa