# Integração IAGO × eTCE — Criação de Peças/Minutas

## 1. Objetivo

Este documento descreve a integração utilizada pelo **IAGO** para criação automática de peças no **eTCE-GO / TCE-Docs**, incluindo:

- endpoint utilizado; - ambientes disponíveis; - autenticação; - usuário de serviço; - contrato da requisição; - regras para inclusão e substituição de documentos; - validações de negócio; - retornos HTTP; - mensagens de validação; - regras específicas da primeira versão da integração.

A finalidade do endpoint é permitir que uma peça produzida com apoio de Inteligência Artificial seja criada no TCE-Docs e vinculada ao último andamento do processo no setor informado.

> **Importante:** a peça criada pelo IAGO deve ser considerada uma **minuta sujeita à revisão de um servidor**. O uso do usuário de serviço `BOTMINUTA` permite identificar a origem automatizada do documento.

—

## 2. Repositório da aplicação

Código-fonte do backend do eTCE:

<[[https://gitsource.tce.go.gov.br/GER-TI/tce.etce.backend|https://gitsource.tce.go.gov.br/GER-TI/tce.etce.backend]]>

—

## 3. Ambientes

### Homologação

Swagger:

<[[https://api-etce.tce.gti.br/swagger/index.html|https://api-etce.tce.gti.br/swagger/index.html]]>

Endpoint:

```http POST https://api-etce.tce.gti.br/api/v1/Documento/iago ```

### Produção

Swagger:

<[[https://api-etce.tce.go.gov.br/swagger/index.html|https://api-etce.tce.go.gov.br/swagger/index.html]]>

Endpoint:

```http POST https://api-etce.tce.go.gov.br/api/v1/Documento/iago ```

—

## 4. Endpoint

```http POST /api/v1/Documento/iago ```

### Descrição

Cria o documento gerado pelo IAGO no **TCE-Docs** e vincula o documento ao **último andamento do processo**, considerando o processo, o setor informado e o usuário autenticado.

O endpoint centraliza as validações necessárias para a criação da peça. Não existe uma etapa separada de pré-validação.

—

## 5. Autenticação

A integração utiliza autenticação via **[[:pres:gerti:manuais:openid|OpenID]] Connect / Keycloak**, com obtenção prévia de um token Bearer.

### 5.1. Produção

```bash curl –location 'https://auth.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' 

  - -header 'Content-Type: application/x-www-form-urlencoded' 
  - -data-urlencode 'client_id=iago-web' 
  - -data-urlencode 'username=BOTMINUTA' 
  - -data-urlencode 'password=<SENHA>' 
  - -data-urlencode 'grant_type=password'

```

### 5.2. Homologação

```bash curl –location 'https://auth-hom.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' 

  - -header 'Content-Type: application/x-www-form-urlencoded' 
  - -data-urlencode 'client_id=iago-web' 
  - -data-urlencode 'username=botminuta' 
  - -data-urlencode 'password=<SENHA>' 
  - -data-urlencode 'grant_type=password'

```

O token retornado deve ser enviado ao endpoint:

```http Authorization: Bearer <TOKEN> Content-Type: application/json ```

### Retornos relacionados à autenticação

|HTTP|Situação|
|—|—|
|`401 Unauthorized`|Requisição realizada sem autenticação/token válido.|
|`403 Forbidden`|Usuário autenticado, porém sem autorização para utilização do endpoint.|

—

## 6. Usuário de serviço

O usuário recomendado para criação das peças geradas pelo IAGO é:

```text BOTMINUTA ```

O uso desse usuário permite identificar que o documento foi produzido por meio da integração com Inteligência Artificial e que deve passar por revisão de um servidor antes da continuidade do fluxo.

### 6.1. Regra de lotação

Uma das principais regras da integração é:

> **O usuário autenticado precisa estar vinculado ao setor informado na requisição.**

Além disso, o processo precisa estar no setor informado para que o documento possa ser efetivamente criado e vinculado ao andamento correspondente.

Atualmente existem vinculações do usuário de serviço aos seguintes setores:

|Setor|Descrição|Usuário/vinculação|
|—|—|—|
|`DI-TI`|Diretoria de Tecnologia da Informação|`BOTMINUTA`|
|`GPCCR`|Gabinete do Procurador de Contas Carlos Gustavo Silva Rodrigues|`BOTMINUTA_GPCCR`|

> Caso a funcionalidade seja disponibilizada para novos setores, será necessário incluir o usuário de serviço no setor correspondente antes de utilizar o endpoint.

—

## 7. Contrato da requisição

### Request Body

```json {
<code>

"setorGeralId": 26,
"conversaId": 0,
"codigoProcesso": 202400047002057,
"tipoDocumento": "DP",
"corpoDocumento": "<p>Conteúdo da minuta...</p>",
"ementa": "Ementa opcional da peça"

</code>

} ```

### Campos

|Campo|Obrigatório|Descrição|
|—|—:|—|
|`setorGeralId`|Sim|Identificador do setor no qual o processo deverá estar e ao qual o usuário autenticado deverá estar vinculado.|
|`codigoProcesso`|Sim|Código do processo onde a peça será criada.|
|`tipoDocumento`|Sim|Indicador do tipo de documento. Na primeira versão da integração deve ser utilizado `DP`, correspondente a **Parecer**.|
|`corpoDocumento`|Sim|Conteúdo da peça em HTML.|
|`conversaId`|Não|Identificador da conversa do IAGO, utilizado para rastreabilidade quando informado. O valor `0` é aceito e é tratado como não informado.|
|`ementa`|Não|Ementa que será associada ao documento. Quando informada, será utilizada na criação da peça; quando omitida, a API utiliza a ementa cadastrada na autuação do processo.|

### Observações sobre o contrato

- Recomenda-se enviar `tipoDocumento` como `DP`. - O contrato deve trabalhar com **um processo por requisição**. - Recomenda-se utilizar os tipos definidos no contrato/Swagger. - `corpoDocumento` deve possuir conteúdo HTML válido e conteúdo efetivo; tags vazias não são aceitas.

—

## 8. Regra da ementa

O campo `ementa` é **opcional**.

### Quando `ementa` é informada

A ementa do documento será gerada utilizando o conteúdo enviado na própria requisição:

```json {
<code>

"ementa": "Análise da prestação de contas..."

</code>

} ```

### Quando `ementa` não é informada

A API busca a ementa cadastrada no processo, proveniente do cadastro da **autuação**.

Se nenhuma ementa estiver disponível para ser utilizada, a criação não poderá prosseguir.

Retorno:

```json {

<code>
"title": "Processo sem ementa.",
"detail": "O documento não pode ser criado pois a EMENTA do PROCESSO deve ser cadastrada, entre em contato com Serviço de PROTOCOLO.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

> Se uma `ementa` válida for enviada diretamente na requisição, ela será utilizada. Caso contrário, será utilizada a ementa cadastrada na autuação.

—

## 9. Tipo de documento permitido

Na primeira versão da integração foi implementada a criação de **Parecer**.

O valor esperado é:

```json {

<code>
"tipoDocumento": "DP"

</code>

} ```

`DP` corresponde ao tipo documental **Parecer**.

Não devem ser enviados outros tipos documentais enquanto não forem explicitamente habilitados para a integração.

### Tipo não permitido para integração com o IAGO

```json {

<code>
"title": "Tipo de documento não permitido.",
"detail": "Tipo de documento não permitido para integração com o Iago.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

### Tipo inexistente ou indisponível para o setor

Também pode ocorrer validação relacionada ao cadastro ou habilitação do tipo documental para o setor informado:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "Não existe o tipo de documento com o indicador DP informado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

—

## 10. Fluxo da operação

De forma simplificada, o endpoint executa o seguinte fluxo:

1. recebe a requisição; 2. valida autenticação; 3. valida autorização para utilização da API; 4. valida os campos da requisição; 5. valida a vinculação do usuário ao setor; 6. valida a existência do processo; 7. valida as condições do processo e do andamento; 8. valida o tipo documental; 9. valida regras de segurança do processo; 10. valida a existência e o estado de documentos anteriores; 11. cria uma nova peça ou substitui uma peça anterior quando permitido; 12. cria/atualiza o documento no TCE-Docs; 13. vincula o documento ao último andamento do processo; 14. atualiza os dados relacionados ao documento no andamento; 15. retorna os dados da operação.

—

## 11. Regras de negócio

### RN01 — Processo existente

O processo informado precisa existir.

Caso contrário, a operação é interrompida.

```json {

<code>
"title": "Parâmetro inválido",
"detail": "Processo informado não existe.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

—

### RN02 — Usuário vinculado ao setor

O usuário autenticado precisa estar vinculado ao `setorGeralId` informado.

```json {

<code>
"title": "Objeto informado está inválido.",
"detail": "{\r\n   \"Validacoes\" : [ \r\n      {\r\n         \"SetorInvalido\" :  \"O usuário autenticado não está vinculado ao setor informado.\"\r\n      }\r\n   ] \r\n}\r\n",
"typeDetail": "application/json",
"status": "Validation",
"type": "Validation",
"instance": null,
"code": "422"

</code>

} ```

Essa regra é válida tanto para processos comuns quanto reservados.

—

### RN03 — Processo no setor informado

O processo deve estar no setor informado na requisição, permitindo que a peça seja vinculada ao andamento correto.

Não é permitido utilizar a integração para incluir uma peça em processo pertencente a setor para o qual o usuário de serviço não esteja devidamente vinculado.

—

### RN04 — Processos sigilosos

Não é permitida a criação de documentos por este endpoint em processos classificados como **sigilosos**, mesmo que o usuário possua acesso ao processo.

```json {

<code>
"title": "Processo Sigiloso.",
"detail": "Não é permitida a criação de documentos no processo (2013100280472), pois ele possui caráter sigiloso.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

O número do processo apresentado na mensagem varia conforme o processo informado.

—

### RN05 — Processos reservados

A criação é permitida em processo reservado desde que o usuário de serviço esteja vinculado ao mesmo setor do processo e as demais regras de negócio sejam atendidas.

Caso o usuário não esteja vinculado ao setor informado, a requisição é rejeitada com `422`.

—

### RN06 — Ementa

A ementa utilizada no documento segue a seguinte prioridade:

1. `ementa` informada no body da requisição; 2. ementa cadastrada na autuação do processo.

Caso não exista uma ementa válida disponível, a criação é interrompida.

—

### RN07 — Responsável pelo setor

Deve existir responsável cadastrado para o setor do processo.

Caso não exista responsável cadastrado, a criação da minuta será interrompida.

—

### RN08 — Documento assinado ou aguardando assinatura

Não é permitida a substituição quando o processo já possui documento assinado ou aguardando assinatura.

```json {

<code>
"title": "Documento Assinado/Aguardando assinatura.",
"detail": "O processo atual já possui um documento assinado ou aguardando assinatura e não pode ser alterado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

—

### RN09 — Documento aberto para edição no Word

Não é permitida a substituição automática quando o documento está aberto para edição.

```json {

<code>
"title": "Substituição automática não permitida.",
"detail": "O documento já se encontra aberto para edição no Word. A substituição automática não é permitida.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

—

### RN10 — Substituição de documento criado pelo IAGO

Um documento criado anteriormente pelo IAGO pode ser automaticamente substituído **somente quando não tiver sofrido alteração por usuário**.

Nesse cenário, o endpoint retorna sucesso e:

```json {

<code>
"acaoExecutada": "Substituicao"

</code>

} ```

—

### RN11 — Documento criado pelo IAGO e alterado por usuário

Se um documento criado pelo IAGO tiver sido posteriormente alterado por um usuário, a substituição automática não é permitida.

```json {

<code>
"title": "Substituição automática não permitida.",
"detail": "O documento existente foi criado pelo IAGO e possui alterações realizadas por um usuário. A substituição automática não é permitida.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

—

### RN12 — Documento criado por usuário

Documentos originalmente criados por usuário não podem ser substituídos automaticamente pela integração.

```json {

<code>
"title": "Substituição automática não permitida.",
"detail": "O documento existente foi criado por um usuário. A substituição automática não é permitida.",
"typeDetail": "text/plain",
"status": "Error",
"type": "Conflict",
"instance": null,
"code": "409"

</code>

} ```

—

### RN13 — Corpo do documento obrigatório

`corpoDocumento` é obrigatório e precisa conter conteúdo válido.

Não são aceitos:

- valor `null`; - string vazia; - conteúdo contendo somente espaços; - HTML sem conteúdo útil; - conteúdo em formato HTML considerado inválido pela API.

Para valor vazio ou `null`:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "O corpo do documento deve ser informado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

Para HTML inválido ou contendo somente tags vazias:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "O corpo do documento informado está em um formato inválido.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

—

### RN14 — Um processo por requisição

O endpoint deve ser utilizado para inclusão de documento em **um processo por vez**.

Não deve ser enviada uma lista de processos no campo `codigoProcesso`.

—

### RN15 — Atualização do andamento

Após a criação do documento, o endpoint atualiza o andamento do processo, incluindo os dados utilizados para referenciar o documento gerado no TCE-Docs.

Entre os dados relacionados ao documento estão:

```text ID_DOCUMENT_N TIPO_DOCUMENT_A ```

—

## 12. Campos obrigatórios e mensagens de validação

### `setorGeralId`

Quando não informado:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "O setor geral do usuário deve ser informado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

### `codigoProcesso`

Quando não informado:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "O código do processo deve ser informado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

### `corpoDocumento`

Quando vazio ou `null`:

```json {

<code>
"title": "Parâmetro inválido",
"detail": "O corpo do documento deve ser informado.",
"typeDetail": "text/plain",
"status": "Error",
"type": "BadRequest",
"instance": null,
"code": "400"

</code>

} ```

### `conversaId`

O campo não é obrigatório.

São permitidos:

- atributo não informado; - `conversaId = 0`.

—

## 13. Exemplo de requisição

```bash curl –location 'https://api-etce.tce.gti.br/api/v1/Documento/iago' 

  - -header 'Authorization: Bearer <TOKEN>' 
  - -header 'Content-Type: application/json' 
  - -data '{

"setorGeralId": 26,

<code>
  "conversaId": 0,
  "codigoProcesso": 202400047002057,
  "tipoDocumento": "DP",
  "corpoDocumento": "<p>Conteúdo da minuta gerada pelo IAGO.</p>",
  "ementa": "Ementa da peça gerada pelo IAGO"
}'

</code>

```

> No ambiente de produção, substituir a URL de homologação pela URL correspondente de produção.

—

## 14. Retorno de sucesso

### Criação de novo documento

```json {

<code>
"documentoId": 6255658,
"codigoProcesso": 201800047000443,
"tipoDocumento": "Parecer",
"dataHora": "2026-07-17T11:29:34.724411-03:00",
"nomeUsuario": "BOTMINUTA",
"acaoExecutada": "CriacaoNova"

</code>

} ```

### Substituição permitida

```json {

<code>
"documentoId": 6255660,
"codigoProcesso": 201800047000443,
"tipoDocumento": "Parecer",
"dataHora": "2026-07-17T11:41:00.2380878-03:00",
"nomeUsuario": "BOTMINUTA",
"acaoExecutada": "Substituicao"

</code>

} ```

### Campos do retorno

|Campo|Descrição|
|—|—|
|`documentoId`|Identificador do documento criado/atualizado no TCE-Docs.|
|`codigoProcesso`|Processo relacionado à operação.|
|`tipoDocumento`|Descrição do tipo documental criado.|
|`dataHora`|Data e hora da operação.|
|`nomeUsuario`|Usuário responsável pela criação via integração.|
|`acaoExecutada`|Informa se houve `[[:pres:gerti:manuais:criacaonova|CriacaoNova]]` ou `Substituicao`.|

—

## 15. Códigos HTTP

|HTTP|Situação|
|—|—|
|`200 OK`|Documento criado ou substituído com sucesso.|
|`400 Bad Request`|Campos ou parâmetros inválidos, processo inexistente, conteúdo obrigatório ausente, tipo cadastral inexistente etc.|
|`401 Unauthorized`|Ausência de autenticação válida.|
|`403 Forbidden`|Usuário autenticado sem autorização para utilizar o endpoint.|
|`409 Conflict`|Regra de negócio impede a criação ou substituição.|
|`422 Unprocessable Entity`|Falha de validação ou vínculo, como usuário não vinculado ao setor informado.|
|`500 Internal Server Error`|Erro interno da aplicação.|

—

## 16. Resumo das principais validações

|Validação|Resultado|
|—|—|
|Usuário sem autenticação|`401`|
|Usuário sem permissão|`403`|
|`setorGeralId` ausente|`400`|
|Usuário não vinculado ao setor|`422`|
|`codigoProcesso` ausente|`400`|
|Processo inexistente|`400`|
|Processo sigiloso|`409`|
|Processo reservado no mesmo setor|Permitido, se as demais regras forem atendidas|
|Processo reservado fora do setor|`422`|
|Processo sem ementa disponível|`409`|
|Tipo diferente do permitido para integração|`409`|
|Documento assinado/aguardando assinatura|`409`|
|Documento em edição no Word|`409`|
|Documento IAGO sem alteração humana|Substituição permitida|
|Documento IAGO alterado por usuário|`409`|
|Documento criado por usuário|`409`|
|`corpoDocumento` vazio ou `null`|`400`|
|HTML inválido/tags vazias|`400`|
|`conversaId` ausente|Permitido|
|`conversaId = 0`|Permitido|

—

## 17. Considerações para expansão da funcionalidade

Para habilitar a criação automática de peças em novos setores, deve-se verificar no mínimo:

1. lotação/vinculação do usuário de serviço no novo setor; 2. permissão do usuário para utilização do endpoint; 3. disponibilidade do tipo documental para o setor; 4. existência de responsável cadastrado para o setor; 5. regras específicas do tipo documental; 6. necessidade de habilitar novos indicadores além de `DP`; 7. adequação das regras de segurança e substituição; 8. validação em ambiente de homologação antes da liberação em produção.

Enquanto não houver ampliação formal da integração, deve-se considerar a primeira versão restrita à criação de **Parecer (`DP`)**.

—

## 18. Recomendações para consumo pelo IAGO

Antes de enviar a requisição:

- obter o token utilizando o usuário de serviço; - utilizar o setor em que o processo efetivamente se encontra; - garantir que o usuário esteja vinculado ao setor; - utilizar `tipoDocumento = "DP"`; - enviar HTML válido e não vazio em `corpoDocumento`; - enviar `ementa` quando o IAGO possuir uma ementa específica para a peça; - utilizar `conversaId` quando houver necessidade de rastreabilidade da interação; - tratar `409` e `422` como respostas funcionais de regra de negócio/validação; - não realizar substituição forçada quando a API indicar alteração humana, assinatura ou edição do documento.

—