====== 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**, 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 eTCE 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|Repositório tce.etce.backend]] ---- ===== 3. Ambientes ===== ==== Homologação ==== Swagger: [[https://api-etce.tce.gti.br/swagger/index.html|Swagger eTCE - Homologação]] Endpoint: POST https://api-etce.tce.gti.br/api/v1/Documento/iago ==== Produção ==== Swagger: [[https://api-etce.tce.go.gov.br/swagger/index.html|Swagger eTCE - Produção]] Endpoint: POST https://api-etce.tce.go.gov.br/api/v1/Documento/iago ---- ===== 4. Endpoint ===== POST /api/v1/Documento/iago ==== Descrição ==== Cria o documento gerado pelo IAGO no **eTCE** 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. ---- ===== 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 ==== 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=' \ --data-urlencode 'grant_type=password' ==== 5.2. Homologação ==== 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=' \ --data-urlencode 'grant_type=password' O token retornado deve ser enviado ao endpoint: Authorization: Bearer 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 é: 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'' | > **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. ---- ===== 7. Contrato da requisição ===== ==== Request Body ==== { "setorGeralId": 26, "codigoProcesso": 202400047002057, "tipoDocumento": "DP", "corpoDocumento": "

Conteúdo da minuta...

", "ementa": "Ementa opcional da peça" } ==== 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 simples. | | ''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 ==== * 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. ---- ===== 8. Regra da ementa ===== O campo ''ementa'' é **opcional**. ==== Quando a ementa é informada ==== A ementa do documento será gerada utilizando o conteúdo enviado na própria requisição: { "ementa": "Análise da prestação de contas..." } ===== 8. Regra da ementa ===== O campo ''ementa'' da requisição é **opcional**. Durante o processamento, a API também considera a ementa cadastrada na autuação do processo. A definição da ementa do documento ocorre da seguinte forma: * quando o campo ''ementa'' é informado na requisição, esse conteúdo será utilizado na peça; * quando o campo ''ementa'' não é informado, será utilizada a ementa cadastrada na autuação. Para que a criação do documento seja concluída, o processo deve possuir ementa cadastrada na autuação. Caso essa informação não esteja preenchida, a API retorna: { "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" } ^ Campo ''ementa'' no endpoint ^ Ementa utilizada no documento ^ | Informado | Conteúdo enviado na requisição | | Não informado | 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 é: { "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 ==== { "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: { "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: - Recebe a requisição. - Valida a autenticação. - Valida a autorização para utilização da API. - Valida os campos da requisição. - Valida a vinculação do usuário ao setor. - Valida a existência do processo. - Valida as condições do processo e do andamento. - Valida o tipo documental. - Valida as regras de segurança do processo. - Valida a existência e o estado de documentos anteriores. - Cria uma nova peça ou substitui uma peça anterior quando permitido. - Cria ou atualiza o documento no TCE-Docs. - Vincula o documento ao último andamento do processo. - Atualiza os dados relacionados ao documento no andamento. - 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. { "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. { "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. { "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; * 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''. ---- ==== RN06 — Ementa ==== A ementa utilizada no documento segue a seguinte prioridade: - ''ementa'' informada no body da requisição; - 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. { "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. { "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: { "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. { "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. { "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'': { "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" } ---- ==== 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: ID_DOCUMENT_N TIPO_DOCUMENT_A ---- ===== 12. Campos obrigatórios e mensagens de validação ===== ==== setorGeralId ==== 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" } ==== codigoProcesso ==== 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" } ==== corpoDocumento ==== 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" } ==== conversaId ==== O campo não é obrigatório. São permitidos: * atributo não informado; * ''conversaId = 0''. ---- ===== 13. Exemplo de requisição ===== ==== Homologação ==== curl --location 'https://api-etce.tce.gti.br/api/v1/Documento/iago' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "setorGeralId": 26, "conversaId": 0, "codigoProcesso": 202400047002057, "tipoDocumento": "DP", "corpoDocumento": "

Conteúdo da minuta gerada pelo IAGO.

", "ementa": "Ementa da peça gerada pelo IAGO" }' Para produção utilizar: https://api-etce.tce.go.gov.br/api/v1/Documento/iago ---- ===== 14. Retorno de sucesso ===== ==== Criação de novo documento ==== { "documentoId": 6255658, "codigoProcesso": 201800047000443, "tipoDocumento": "Parecer", "dataHora": "2026-07-17T11:29:34.724411-03:00", "nomeUsuario": "BOTMINUTA", "acaoExecutada": "CriacaoNova" } ==== Substituição permitida ==== { "documentoId": 6255660, "codigoProcesso": 201800047000443, "tipoDocumento": "Parecer", "dataHora": "2026-07-17T11:41:00.2380878-03:00", "nomeUsuario": "BOTMINUTA", "acaoExecutada": "Substituicao" } ==== 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 ''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: - lotação/vinculação do usuário de serviço no novo setor; - permissão do usuário para utilização do endpoint; - disponibilidade do tipo documental para o setor; - existência de responsável cadastrado para o setor; - regras específicas do tipo documental; - necessidade de habilitar novos indicadores além de ''DP''; - adequação das regras de segurança e substituição; - 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. ----