Essa é uma revisão anterior do documento!

---

# 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>

—

## 3. Ambientes

### Homologação

Swagger:

<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>

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 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'

1. -header 'Content-Type: application/x-www-form-urlencoded'
2. -data-urlencode 'client_id=iago-web'
3. -data-urlencode 'username=BOTMINUTA'
4. -data-urlencode 'password=<SENHA>'
5. -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'

1. -header 'Content-Type: application/x-www-form-urlencoded'
2. -data-urlencode 'client_id=iago-web'
3. -data-urlencode 'username=botminuta'
4. -data-urlencode 'password=<SENHA>'
5. -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

—

## 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:

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 {

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

} ```

### Campos

### 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 {

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

} ```

### 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 {

"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"

} ```

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 {

"tipoDocumento": "DP"

} ```

`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 {

"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"

} ```

### 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 {

"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"

} ```

—

## 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 {

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

} ```

—

### RN02 — Usuário vinculado ao setor

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

```json {

"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"

} ```

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 {

"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"

} ```

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 {

"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"

} ```

—

### 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 {

"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"

} ```

—

### 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 {

"acaoExecutada": "Substituicao"

} ```

—

### 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 {

"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"

} ```

—

### RN12 — Documento criado por usuário

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

```json {

"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"

} ```

—

### 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 {

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

} ```

Para HTML inválido ou contendo somente tags vazias:

```json {

"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"

} ```

—

### 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 {

"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"

} ```

### `codigoProcesso`

Quando não informado:

```json {

"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"

} ```

### `corpoDocumento`

Quando vazio ou `null`:

```json {

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

} ```

### `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'

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

“setorGeralId”: 26,

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

```

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 {

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

} ```

### Substituição permitida

```json {

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

} ```

### Campos do retorno

—

## 15. Códigos HTTP

—

## 16. Resumo das principais validações

—

## 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.

—