# Changelog da API Construflow

[Receba atualizações técnicas relevantes por e-mail.](https://materiais.construflow.com.br/avisos-de-atualizacoes-do-mcp-api)

Este histórico registra mudanças no **contrato da API** que podem exigir ação de quem integra. Ele não registra revisões editoriais da documentação. A entrada mais recente vem primeiro.

## 20/10/2026

- Quando o e-mail de um usuário muda para um endereço que já era de outro usuário, os dois se unem: o que o outro criou passa a ter o `id` e o `guid` do usuário que trocou o e-mail, e os apontamentos e comentários voltam na sincronização incremental; o outro continua existindo, sem projetos.
  **Ação recomendada:** se a sua base guarda quem criou cada apontamento e comentário, atualize o autor com o que a sincronização incremental trouxer. Sem isso, esses registros continuam apontando para o usuário antigo.

## 15/10/2026

- A mutation `createProjectIssueFileUploadSignedUrl` deixou de ser aceita.
  **Ação recomendada:** use `createProjectIssueFileUploadSignedUrls`, que atende de um a 50 arquivos por chamada ([§12](/#imagens-em-três-passos)).

## 13/10/2026

- O e-mail de um usuário pode mudar, e o endereço antigo pode passar a outro usuário; o `id` e o `guid` continuam os mesmos. Na troca, todos os acessos OAuth do usuário são encerrados, como na troca de senha; a Chave de Acesso continua valendo.
  **Ação recomendada:** use o `id` ou o `guid` como chave do usuário na sua base, nunca o e-mail; se a renovação do token for recusada, conecte de novo.

## 05/10/2026

- `createIssue` e `createIssues` passaram a gravar **"Não definida"** (id `0`) em `category` e em `creationPhase` quando o campo é omitido ou vem `null`, em qualquer projeto — inclusive no que restringe categorias ou fases, onde a omissão era recusada com `CATEGORY_MUST_BE_ACTIVE` / `PHASE_MUST_BE_ACTIVE`. Em `updateIssue` e `updateIssues`, `null` nesses campos grava "Não definida" em vez de esvaziá-los. Os apontamentos que estavam sem categoria ou sem fase de criação passaram a "Não definida", deixaram de falhar em `categoryName` e `creationPhaseName` e voltam uma vez na sincronização incremental, como alterados ([§12](/#criar-apontamento)).
  **Ação recomendada:** Se a sua integração trata `category` ou `creationPhase` nulos como "sem classificação", trate também o id `0`.

## 03/10/2026

- As respostas a chamadas que usam um item obsoleto do contrato passaram a trazer os cabeçalhos `Deprecation`, `Sunset` (quando há data-limite), `Link` com `rel="deprecation"` — um por item, apontando para a entrada deste changelog que explica a mudança — e `Warning` com o código 299 e uma frase sobre o que usar no lugar ([§5](/#avisos-de-obsolescência)). A chamada continua funcionando igual.
  **Ação recomendada:** Registre esses cabeçalhos na sua integração e trate a presença deles como alerta para migrar antes da data-limite.
- A mutation `createProjectIssueFileUploadSignedUrl`, obsoleta desde 17/09/2026, **deixa de ser aceita em 15/10/2026**.
  **Ação recomendada:** Use `createProjectIssueFileUploadSignedUrls`, que atende de um a 50 arquivos por chamada ([§12](/#imagens-em-três-passos)).

## 27/09/2026

- A API passou a aceitar tokens OAuth 2.0 (`Authorization: Bearer`): um script se conecta à conta de uma pessoa por um código, sem Chave de Acesso, e um app age em nome de cada pessoa que o usa. O access token vale 15 minutos e é renovado pelo refresh token, que muda a cada renovação ([§3](/#autenticação-oauth)).
- A Chave de Acesso (HTTP Basic) está obsoleta e **deixa de ser aceita em 15/10/2026**.
  **Ação recomendada:** Migre a integração para OAuth antes de 15/10/2026 ([§3](/#autenticação-oauth)). Renove o refresh token num processo só e grave o novo antes de usar o access token: um refresh já trocado, se reapresentado, revoga o acesso inteiro ([§3](/#validade-e-renovação)).

## 21/09/2026

- O envio de arquivo por `multipart` (campos `Upload`) passou a ter teto: **10 MB por arquivo** e **500 arquivos por chamada**. Acima disso a chamada inteira é recusada com `413` e `UPLOAD_FILE_SIZE_EXCEEDED` ou `UPLOAD_FILE_COUNT_EXCEEDED`; corpo `multipart` ilegível é recusado com `400` e `UPLOAD_REQUEST_INVALID` ([§6](/#a-tabela-de-limites)).
  **Ação recomendada:** Prefira a URL assinada para enviar imagens ([§12](/#imagens-em-três-passos)). Se usa `multipart`, mantenha cada arquivo abaixo de 10 MB e trate essas recusas como definitivas: repetir a mesma chamada produz a mesma recusa.

## 19/09/2026

- O volume total por identidade (`user-envelope`) passou de 160 / 10 s e 420 / 60 s para **40 / 10 s e 80 / 60 s**. A forma da recusa não mudou.
  **Ação recomendada:** Ajuste o limitador da integração para ~1 requisição por segundo e troque leitura item a item por listagem paginada e lotes por `filter.ids`. Trate `429` respeitando o `Retry-After`.

## 18/09/2026

- Os limites por tipo de operação (`user-read`, `user-write`, `user-upload-url`) deixaram de existir. O volume passou a ser contado **só** pelo total por identidade (`user-envelope`), cujos tetos não mudaram, e toda recusa `429` passou a vir com corpo plano.
  **Ação recomendada:** Nenhuma ação obrigatória: os tetos só ficaram mais folgados. Se o seu cliente detecta recusa por taxa lendo `errors[0].extensions`, passe a tratá-la pelo status `429` e pelos cabeçalhos ([§6](/#o-envelope-de-recusa-por-taxa)).

## 17/09/2026

- A mutation `createProjectIssueFileUploadSignedUrls` passou a emitir as URLs assinadas de até 50 arquivos em uma chamada.
  **Ação recomendada:** Prefira a mutation plural, inclusive para um único arquivo. A versão singular continua disponível, mas está obsoleta.