API v1.0.0 · somente consulta

API do FlowDesk

Consulta dos tickets de atendimento e de grupo do WhatsApp.

API somente de consulta: outro sistema da sua empresa (NOC, BI, ERP...) lê os tickets do FlowDesk. Ela não envia mensagens nem muda nada.

Chave de API: quem é cliente do FlowDesk cria a chave em Integrações › API do FlowDesk. Cada chave só enxerga a própria empresa e só o que os escopos dela permitem. Guarde a chave no servidor do seu sistema, nunca em página ou aplicativo que o usuário final abre.

Limite: 120 pedidos por minuto por chave (cabeçalhos X-RateLimit-Limit e X-RateLimit-Remaining; ao passar, erro 429 com Retry-After).

Datas em ISO 8601 (UTC na resposta). Mensagens: até 1000 por ticket, da abertura ao encerramento; as notas internas da equipe não saem pela API.

Endereço base

https://www.flowdeskk.com/api/v1

Especificação OpenAPI 3.1

/api/v1/openapi.json

Importe no Postman, no Insomnia ou num gerador de código.

Chave de API

Entre no FlowDesk e vá em Integrações › API do FlowDesk.
Clique em Nova chave, dê um nome (ex.: "Sistema do NOC") e escolha o que ela pode consultar.
Copie a chave na hora: ela começa com fdk_ e só aparece uma vez.
Envie em todo pedido no cabeçalho Authorization: Bearer fdk_... (ou X-Api-Key).

Tickets de atendimento

Um ticket por atendimento de cliente (do início ao encerramento). Escopo tickets.ler.

Tickets de grupo

Um ticket por assunto num grupo do WhatsApp ligado no FlowDesk. Escopo tickets_grupo.ler.

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1"

Limites e erros

Código	Quando
`200`	Deu certo.
`400`	Filtro inválido (a mensagem diz qual).
`401`	Chave ausente, errada ou revogada.
`403`	A chave não tem o escopo da rota.
`404`	Ticket não existe nesta empresa.
`429`	Mais de 120 pedidos por minuto na chave. Espere os segundos do cabeçalho `Retry-After`.

Todo erro vem como { "error": true, "statusCode": 401, "message": "..." }, com a explicação em português no campo message.

Sincronizar sem baixar tudo

Guarde a data da última consulta e peça só o que mudou desde então com atualizado_desde e ordem=antigos, página por página. Na próxima rodada, use a maior atualizado_em que recebeu.

// Busca só os tickets que mudaram desde a última rodada
async function sincronizar(desde) {
  let pagina = 1, maisNovo = desde;
  while (true) {
    const url = new URL('https://www.flowdeskk.com/api/v1/tickets');
    url.search = new URLSearchParams({ atualizado_desde: desde, ordem: 'antigos', por_pagina: '100', pagina: String(pagina) });
    const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.FLOWDESK_API_KEY}` } });
    if (r.status === 429) { await new Promise(ok => setTimeout(ok, Number(r.headers.get('Retry-After') || 5) * 1000)); continue; }
    const { dados, paginacao } = await r.json();
    for (const ticket of dados) {
      await salvarNoMeuSistema(ticket); // a sua função
      if (ticket.atualizado_em > maisNovo) maisNovo = ticket.atualizado_em;
    }
    if (pagina >= paginacao.total_paginas) return maisNovo; // guarde para a próxima rodada
    pagina++;
  }
}

Tickets de atendimento

Um ticket por atendimento de cliente (do início ao encerramento). Escopo tickets.ler.

GET`/api/v1/tickets`

Listar tickets de atendimento — Lista paginada, da atualização mais recente para a mais antiga (ou o contrário com `ordem=antigos`).

Parâmetro	Tipo	Descrição
`status`	aberto \| encerrado	Situação do ticket.
`aberto_desde`	data ISO 8601	Abertos a partir desta data (ISO 8601). Ex.: 2026-11-01T00:00:00-03:00
`aberto_ate`	data ISO 8601	Abertos até esta data (ISO 8601).
`atualizado_desde`	data ISO 8601	Só o que mudou desde esta data. Use para sincronizar de tempos em tempos sem baixar tudo de novo.
`canal_id`	número	Número de WhatsApp (canal) do FlowDesk.
`ordem`	recentes \| antigos	Por data de atualização: recentes (padrão) ou antigos primeiro.
`pagina`	número (padrão 1)	Página (começa em 1).
`por_pagina`	número (padrão 50)	Itens por página.
`telefone`	texto	Telefone do cliente (só os números contam: +55 (86) 99999-0000 = 5586999990000).
`cpf_cnpj`	texto	CPF ou CNPJ do cliente (só os números contam).

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets?status=aberto&por_pagina=20"

Exemplo de resposta 200

{
  "dados": [
    {
      "numero": 1000245,
      "status": "encerrado",
      "cliente": {
        "nome": "Maria Souza",
        "telefone": "5586999990000",
        "cpf_cnpj": "12345678900"
      },
      "canal_id": 19,
      "atendente": "Ana Lima",
      "atendido_pela_ia": false,
      "tag_atual": "ENCERRADO",
      "motivo_encerramento": {
        "id": 4,
        "nome": "Problema resolvido"
      },
      "aberto_em": "2026-11-02T13:05:00.000Z",
      "atualizado_em": "2026-11-02T13:41:00.000Z",
      "encerrado_em": "2026-11-02T13:41:00.000Z",
      "duracao_minutos": 36
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "total_paginas": 1
  }
}

GET`/api/v1/tickets/{numero}`

Consultar um ticket de atendimento

Parâmetro	Tipo	Descrição
`numero`no caminho	número	Número do ticket (o mesmo que aparece no FlowDesk).
`mensagens`	true \| false (padrão false)	true para trazer as mensagens do ticket junto.

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets/1000245"

Exemplo de resposta 200

{
  "dados": {
    "numero": 1000245,
    "status": "encerrado",
    "cliente": {
      "nome": "Maria Souza",
      "telefone": "5586999990000",
      "cpf_cnpj": "12345678900"
    },
    "canal_id": 19,
    "atendente": "Ana Lima",
    "atendido_pela_ia": false,
    "tag_atual": "ENCERRADO",
    "motivo_encerramento": {
      "id": 4,
      "nome": "Problema resolvido"
    },
    "aberto_em": "2026-11-02T13:05:00.000Z",
    "atualizado_em": "2026-11-02T13:41:00.000Z",
    "encerrado_em": "2026-11-02T13:41:00.000Z",
    "duracao_minutos": 36
  }
}

GET`/api/v1/tickets/{numero}/mensagens`

Mensagens de um ticket de atendimento — As mensagens trocadas durante o atendimento, em ordem cronológica.

Parâmetro	Tipo	Descrição
`numero`no caminho	número	Número do ticket (o mesmo que aparece no FlowDesk).

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets/1000245/mensagens"

Exemplo de resposta 200

{
  "numero": 1000245,
  "mensagens": [
    {
      "id": "3EB0A1B2C3D4E5F6",
      "enviada_em": "2026-11-02T13:05:10.000Z",
      "de": "cliente",
      "tipo": "Conversation",
      "texto": "Estou sem internet desde ontem",
      "midia_url": null,
      "arquivo": null
    }
  ],
  "mensagens_truncadas": false
}

Tickets de grupo

Um ticket por assunto num grupo do WhatsApp ligado no FlowDesk. Escopo tickets_grupo.ler.

GET`/api/v1/tickets-grupo`

Listar tickets de grupo — Cada assunto num grupo vira um ticket: abre com a mensagem de um participante e encerra pelo atendente ou sozinho, depois de um tempo sem mensagens.

Parâmetro	Tipo	Descrição
`status`	aberto \| encerrado	Situação do ticket.
`aberto_desde`	data ISO 8601	Abertos a partir desta data (ISO 8601). Ex.: 2026-11-01T00:00:00-03:00
`aberto_ate`	data ISO 8601	Abertos até esta data (ISO 8601).
`atualizado_desde`	data ISO 8601	Só o que mudou desde esta data. Use para sincronizar de tempos em tempos sem baixar tudo de novo.
`canal_id`	número	Número de WhatsApp (canal) do FlowDesk.
`ordem`	recentes \| antigos	Por data de atualização: recentes (padrão) ou antigos primeiro.
`pagina`	número (padrão 1)	Página (começa em 1).
`por_pagina`	número (padrão 50)	Itens por página.
`grupo`	texto	Id do grupo (ex.: 120363225392860006@g.us; só os números contam).

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets-grupo?status=aberto&por_pagina=20"

Exemplo de resposta 200

{
  "dados": [
    {
      "numero": 5000012,
      "status": "aberto",
      "grupo": {
        "nome": "Equipe Técnica",
        "id": "120363225392860006@g.us"
      },
      "canal_id": 19,
      "aberto_por": {
        "nome": "Zé Técnico",
        "telefone": "5586911112222"
      },
      "primeira_mensagem": "Cliente 123 sem sinal na rua das Flores",
      "responsavel": "Ana Lima",
      "aberto_em": "2026-11-02T10:00:00.000Z",
      "primeira_resposta_em": "2026-11-02T10:04:00.000Z",
      "minutos_ate_primeira_resposta": 4,
      "ultima_mensagem_em": "2026-11-02T10:25:00.000Z",
      "atualizado_em": "2026-11-02T10:25:00.000Z",
      "encerrado_em": null,
      "encerrado_por": null,
      "encerrado_por_nome": null,
      "motivo_encerramento": null,
      "nota_encerramento": null,
      "reaberturas": 0,
      "duracao_minutos": null
    }
  ],
  "paginacao": {
    "pagina": 1,
    "por_pagina": 50,
    "total": 1,
    "total_paginas": 1
  }
}

GET`/api/v1/tickets-grupo/{numero}`

Consultar um ticket de grupo

Parâmetro	Tipo	Descrição
`numero`no caminho	número	Número do ticket (o mesmo que aparece no FlowDesk).
`mensagens`	true \| false (padrão false)	true para trazer as mensagens do ticket junto.

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets-grupo/5000012"

Exemplo de resposta 200

{
  "dados": {
    "numero": 5000012,
    "status": "aberto",
    "grupo": {
      "nome": "Equipe Técnica",
      "id": "120363225392860006@g.us"
    },
    "canal_id": 19,
    "aberto_por": {
      "nome": "Zé Técnico",
      "telefone": "5586911112222"
    },
    "primeira_mensagem": "Cliente 123 sem sinal na rua das Flores",
    "responsavel": "Ana Lima",
    "aberto_em": "2026-11-02T10:00:00.000Z",
    "primeira_resposta_em": "2026-11-02T10:04:00.000Z",
    "minutos_ate_primeira_resposta": 4,
    "ultima_mensagem_em": "2026-11-02T10:25:00.000Z",
    "atualizado_em": "2026-11-02T10:25:00.000Z",
    "encerrado_em": null,
    "encerrado_por": null,
    "encerrado_por_nome": null,
    "motivo_encerramento": null,
    "nota_encerramento": null,
    "reaberturas": 0,
    "duracao_minutos": null
  }
}

GET`/api/v1/tickets-grupo/{numero}/mensagens`

Mensagens de um ticket de grupo — As mensagens do assunto, com o participante que escreveu cada uma (`autor`).

Parâmetro	Tipo	Descrição
`numero`no caminho	número	Número do ticket (o mesmo que aparece no FlowDesk).

curl -H "Authorization: Bearer $FLOWDESK_API_KEY" \
  "https://www.flowdeskk.com/api/v1/tickets-grupo/5000012/mensagens"

Exemplo de resposta 200

{
  "numero": 5000012,
  "mensagens": [
    {
      "id": "3EB0A1B2C3D4E5F6",
      "enviada_em": "2026-11-02T13:05:10.000Z",
      "de": "participante",
      "tipo": "Conversation",
      "texto": "Cliente 123 sem sinal na rua das Flores",
      "midia_url": null,
      "arquivo": null,
      "autor": "Zé Técnico"
    }
  ],
  "mensagens_truncadas": false
}

Formatos

Ticket de atendimento

Campo	Tipo	Descrição
`numero`	número	Número do ticket (protocolo do atendimento).
`status`	aberto \| encerrado
`cliente`	{ nome, telefone, cpf_cnpj }
`canal_id`	número \| null	Número de WhatsApp (canal) do atendimento.
`atendente`	texto \| null	Atendente humano atual ou o último. null quando só a IA atendeu.
`atendido_pela_ia`	true \| false
`tag_atual`	texto \| null	Onde o atendimento está ou como terminou (ex.: FILA - Aguardando atendente, ATIVO - Atendimento humano, RESOLVIDO PELA IA).
`motivo_encerramento`	objeto { id, nome } \| null
`aberto_em`	data ISO 8601	Início do atendimento.
`atualizado_em`	data ISO 8601	Última mudança no ticket.
`encerrado_em`	data ISO 8601 \| null	Encerramento (null se ainda aberto).
`duracao_minutos`	número \| null	Da abertura ao encerramento.
`mensagens`	lista	Só com ?mensagens=true.
`mensagens_truncadas`	true \| false	Só com ?mensagens=true.

Ticket de grupo

Campo	Tipo	Descrição
`numero`	número	Número do ticket de grupo (a partir de 5000001).
`status`	aberto \| encerrado
`grupo`	{ nome, id }
`canal_id`	número \| null
`aberto_por`	{ nome, telefone }	Participante que mandou a 1ª mensagem.
`primeira_mensagem`	texto \| null
`responsavel`	texto \| null	Atendente que assumiu o ticket.
`aberto_em`	data ISO 8601	Abertura.
`primeira_resposta_em`	data ISO 8601 \| null	1ª mensagem da empresa depois da abertura.
`minutos_ate_primeira_resposta`	número \| null
`ultima_mensagem_em`	data ISO 8601 \| null	Última mensagem do assunto.
`atualizado_em`	data ISO 8601	Última mudança no ticket.
`encerrado_em`	data ISO 8601 \| null	Encerramento (null se ainda aberto).
`encerrado_por`	atendente \| inatividade \| null	inatividade = encerrou sozinho, sem mensagens pelo tempo configurado no grupo.
`encerrado_por_nome`	texto \| null
`motivo_encerramento`	objeto { id, nome } \| null
`nota_encerramento`	texto \| null	Nota escrita por quem encerrou.
`reaberturas`	número	Vezes que uma mensagem logo depois do encerramento (carência) reabriu este ticket.
`duracao_minutos`	número \| null
`mensagens`	lista	Só com ?mensagens=true.
`mensagens_truncadas`	true \| false	Só com ?mensagens=true.

Mensagem

Campo	Tipo	Descrição
`id`	texto \| null	Id da mensagem no WhatsApp.
`enviada_em`	data ISO 8601	Quando foi enviada.
`de`	cliente \| empresa \| participante	participante = alguém do grupo (tickets de grupo).
`autor`	texto \| null	Só nos tickets de grupo: quem escreveu.
`tipo`	texto	Tipo da mensagem no WhatsApp (Conversation, ImageMessage, AudioMessage, DocumentMessage...).
`texto`	texto \| null	Texto ou legenda (áudios transcritos aparecem aqui).
`midia_url`	texto \| null	Link da imagem, áudio, vídeo ou documento.
`arquivo`	texto \| null	Nome do arquivo (documentos).

API do FlowDesk

Chave de API

Limites e erros

Sincronizar sem baixar tudo

Tickets de atendimento

GET/api/v1/tickets

GET/api/v1/tickets/{numero}

GET/api/v1/tickets/{numero}/mensagens

Tickets de grupo

GET/api/v1/tickets-grupo

GET/api/v1/tickets-grupo/{numero}

GET/api/v1/tickets-grupo/{numero}/mensagens

Formatos

Ticket de atendimento

Ticket de grupo

Mensagem

GET`/api/v1/tickets`

GET`/api/v1/tickets/{numero}`

GET`/api/v1/tickets/{numero}/mensagens`

GET`/api/v1/tickets-grupo`

GET`/api/v1/tickets-grupo/{numero}`

GET`/api/v1/tickets-grupo/{numero}/mensagens`