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

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.

Código-fonte do backend do eTCE:

Repositório tce.etce.backend

Swagger:

Swagger eTCE - Homologação

Endpoint:

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

Swagger:

Swagger eTCE - Produção

Endpoint:

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

POST /api/v1/Documento/iago

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.

A integração utiliza autenticação via OpenID Connect / Keycloak, com obtenção prévia de um token Bearer.

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'

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:

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

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

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.

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:

Importante: 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.

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

• Deve ser utilizado tipoDocumento = “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 HTML vazias não são aceitas.

O campo ementa é opcional.

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

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

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

A prioridade para definição da ementa é:

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

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

Retorno:

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

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

O valor esperado é:

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

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

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

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

De forma simplificada, o endpoint executa o seguinte fluxo:

1. Recebe a requisição.
2. Valida a autenticação.
3. Valida a 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 as 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 ou 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.

O processo informado precisa existir.

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

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

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

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

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.

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.

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

A criação é permitida em processo reservado desde que:

• o usuário de serviço esteja vinculado ao mesmo setor do processo;
• o processo esteja no setor informado;
• 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.

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.

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

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

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

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

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

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

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:

{
  "acaoExecutada": "Substituicao"
}

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

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

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

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

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:

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

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

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.

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:

ID_DOCUMENT_N
TIPO_DOCUMENT_A

Quando não informado:

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

Quando não informado:

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

Quando vazio ou null:

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

O campo não é obrigatório.

São permitidos:

• atributo não informado;
• conversaId = 0.

curl --location 'https://api-etce.tce.gti.br/api/v1/Documento/iago' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --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"
  }'

Para produção utilizar:

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

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

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

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

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.