Conecte suas ferramentas ao Kanban do NextChat.

NextChat

API

Sua ferramenta

SEU KANBAN, NO SEU FLUXO

A API do Kanban permite consultar quadros, criar cartões e atualizar tarefas a partir dos seus próprios scripts, Claude ou outras ferramentas. Você escolhe as permissões e os quadros de cada integração.

Comece sua integração

Como funciona

O NextChat fornece acesso autenticado ao Kanban. Sua ferramenta decide quando consultar os cartões e quais ações executar — como criar uma issue ou acompanhar o desenvolvimento.

Você controla o acesso

• Quadros selecionados. Cada chave acessa somente o que você permitir.
• Permissões por ação. Consulta, criação, edição, movimentação, comentários e checklist.
• Validade e revogação. Escolha um prazo ou Para sempre, com revogação imediata.
• Privacidade preservada. Cartões privados, cartões de números privados e mensagens ficam fora da API.

1. Gere uma chave no NextChat

   Entre como proprietário ou administrador. Abra Configurações → Integrações → Kanban e dê um nome à integração.

2. Escolha o acesso necessário

   Selecione permissões, quadros e validade de 7, 30 ou 90 dias, ou Para sempre. Comece com consulta se ainda estiver experimentando.

3. Copie e guarde a chave

   O segredo aparece uma única vez. Use uma variável de ambiente ou o cofre de segredos da sua ferramenta.

export NEXTCHAT_API_KEY='SUA_CHAVE_API'
export NEXTCHAT_API='https://app.nextchat.nextsistem.dev.br/api/integrations/v1'

curl "$NEXTCHAT_API/me" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Os exemplos usam placeholders. Nunca coloque a chave em prompts públicos, repositórios ou código de navegador.

Envie Authorization: Bearer SUA_CHAVE_API em todas as chamadas HTTPS. Use o domínio do aplicativo; a landing hospeda apenas este guia. Se sua instalação usa um subcaminho, inclua-o antes de /api/integrations/v1.

As chaves são exclusivas desta API. Tokens de login do aplicativo não são aceitos aqui. Com validade Para sempre, a chave não expira automaticamente. Ela continua sujeita à revogação e às permissões do criador. A chave deixa de funcionar ao expirar, ser revogada ou quando seu criador é desativado ou deixa de ser proprietário/administrador.

Cada chave combina ações permitidas e uma lista explícita de quadros. Ela nunca acessa outra empresa ou quadros fora dessa seleção.

Quadros privados ficam fora da API. Em quadros compartilhados, o criador da chave precisa manter acesso ao quadro. Uma permissão de visualizar permite somente leituras, mesmo que a chave tenha escopos de escrita. Remover a pessoa do quadro bloqueia novas chamadas e a repetição de escritas idempotentes.

Cartões privados e cartões ligados a números privados ficam fora da API, inclusive os do criador da chave. As respostas não incluem mensagens, anexos, telefones, dados de contato ou valores monetários. Título, descrição, comentários e checklist são conteúdos da equipe: considere isso ao escolher os quadros.

Esta versão não cria quadros ou etapas, não apaga cartões e não oferece webhook. O cliente controla quando consultar a API e como executar a automação.

Os caminhos abaixo são relativos à base URL. IDs são UUIDs.

1. Descubra o quadro e suas etapas

curl "$NEXTCHAT_API/kanban/boards" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

A resposta é uma lista de quadros com suas etapas em stages. Use id do quadro e da etapa nas próximas chamadas.

2. Crie um cartão

curl -X POST "$NEXTCHAT_API/kanban/boards/ID_DO_QUADRO/cards" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: tarefa-externa-123-criar' \
  -d '{
    "title": "Revisar integração do cliente",
    "description": "Tarefa criada pela nossa ferramenta.",
    "priority": "medium"
  }'

Retorna 201 com o cartão criado, incluindo id e version. Sem stage_id, entra na primeira etapa aberta.

3. Edite com a versão que você consultou

curl -X PATCH "$NEXTCHAT_API/kanban/cards/ID_DO_CARTAO" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"description":"Desenvolvimento iniciado.","version":1}'

4. Mova para outra etapa

curl -X POST "$NEXTCHAT_API/kanban/cards/ID_DO_CARTAO/move" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: tarefa-externa-123-mover-2' \
  -d '{"stage_id":"ID_DA_ETAPA","version":2}'

5. Registre o resultado

curl -X POST "$NEXTCHAT_API/kanban/cards/ID_DO_CARTAO/comments" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: tarefa-externa-123-comentario' \
  -d '{"text":"Issue criada e desenvolvimento concluído."}'

Prioridades: low, medium, high, urgent. Datas usam RFC 3339, como 2026-10-10T18:00:00Z. Para remover o prazo, envie due_at: null. Campos desconhecidos são rejeitados.

Consulte GET /kanban/cards?board_id=ID_DO_QUADRO&limit=30. A resposta contém items e next_cursor. Enquanto o cursor não for nulo, repita os mesmos filtros acrescentando cursor codificado para URL. Limite máximo: 100 cartões por página.

Filtros disponíveis

Idempotência nos POSTs

Todo POST exige Idempotency-Key de 8 a 128 caracteres, único por operação lógica. Reutilize a mesma chave e o mesmo corpo após timeout ou falha de rede. O resultado fica reservado por 7 dias; uma repetição concluída recebe Idempotency-Replayed: true. A mesma chave com caminho ou corpo diferente retorna 409.

Se houver interrupção depois da execução e antes do armazenamento da resposta, a reserva permanece pendente. Nesse caso, o servidor retorna 409 e não executa novamente. Confira o estado do cartão antes de iniciar outra operação com uma chave nova.

Versão em edições e movimentos

PATCH de cartão e POST de movimentação exigem version ou If-Match: "v1". Sem versão: 428. Versão antiga: 409 com code: version_conflict. Consulte o cartão novamente, concilie a alteração e tente com a versão atual; para um novo POST, use uma nova chave de idempotência.

Por chave: 120 leituras e 30 escritas por minuto. Por empresa: 600 leituras e 150 escritas por minuto. Ao receber 429, respeite Retry-After. Use polling moderado com espera progressiva, sem loops contínuos. Corpo máximo: 64 KiB.

{"error":"permissão insuficiente","code":"forbidden"}

Operações ficam registradas na auditoria e no histórico do Kanban com a identificação da integração. A chave secreta não é registrada.