pres:gerti:manuais:integracaoiagoxetce

Diferenças

Aqui você vê as diferenças entre duas revisões dessa página.

Link para esta página de comparações

Próxima revisão		 Revisão anterior
pres:gerti:manuais:integracaoiagoxetce [24/09/2026 14:39] – criada rmpirespres:gerti:manuais:integracaoiagoxetce [24/09/2026 17:18] (atual) – [Campos] rmpires
Linha 1: Linha 1:
-# Integração IAGO × eTCE — Criação de Peças/Minutas+====== Integração IAGO × eTCE — Criação de Peças/Minutas ======
  
-## 1. Objetivo+===== 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:+Este documento descreve a integração utilizada pelo **IAGO** para criação automática de peças no **eTCE-GO**, incluindo:
  
-- endpoint utilizado;\\ +  * endpoint utilizado; 
-- ambientes disponíveis;\\ +  * ambientes disponíveis; 
-- autenticação;\\ +  * autenticação; 
-- usuário de serviço;\\ +  * usuário de serviço; 
-- contrato da requisição;\\ +  * contrato da requisição; 
-- regras para inclusão e substituição de documentos;\\ +  * regras para inclusão e substituição de documentos; 
-- validações de negócio;\\ +  * validações de negócio; 
-- retornos HTTP;\\ +  * retornos HTTP; 
-- mensagens de validação;\\ +  * mensagens de validação; 
-- regras específicas da primeira versão da integraçã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.+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.+> **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+===== 2. Repositório da aplicação =====
  
 Código-fonte do backend do eTCE: 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|Repositório tce.etce.backend]]
  
----+----
  
-## 3. Ambientes+===== 3. Ambientes =====
  
-### Homologação+==== Homologação ====
  
 Swagger: Swagger:
  
-<https://api-etce.tce.gti.br/swagger/index.html>+[[https://api-etce.tce.gti.br/swagger/index.html|Swagger eTCE - Homologação]]
  
 Endpoint: Endpoint:
  
-```http +<code> 
-POST https://api-etce.tce.gti.br/api/v1/Documento/iago\\ +POST https://api-etce.tce.gti.br/api/v1/Documento/iago 
-```+</code>
  
-### Produção+==== Produção ====
  
 Swagger: Swagger:
  
-<https://api-etce.tce.go.gov.br/swagger/index.html>+[[https://api-etce.tce.go.gov.br/swagger/index.html|Swagger eTCE - Produção]]
  
 Endpoint: Endpoint:
  
-```http\\ +<code> 
-POST https://api-etce.tce.go.gov.br/api/v1/Documento/iago\\ +POST https://api-etce.tce.go.gov.br/api/v1/Documento/iago 
-```+</code>
  
----+----
  
-## 4. Endpoint+===== 4. Endpoint =====
  
-```http\\ +<code> 
-POST /api/v1/Documento/iago\\ +POST /api/v1/Documento/iago 
-```+</code>
  
-### Descrição+==== 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.+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. Não existe uma etapa separada de pré-validação.+O endpoint centraliza as validações necessárias para a criação da peça.
  
----+----
  
-## 5. Autenticação+===== 5. Autenticação =====
  
 A integração utiliza autenticação via **OpenID Connect / Keycloak**, com obtenção prévia de um token Bearer. A integração utiliza autenticação via **OpenID Connect / Keycloak**, com obtenção prévia de um token Bearer.
  
-### 5.1. Produção+==== 5.1. Produção ====
  
-```bash\\ +<code bash> 
-curl --location 'https://auth.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' \\\ +curl --location 'https://auth.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' \ 
---header 'Content-Type: application/x-www-form-urlencoded' \\\ +  --header 'Content-Type: application/x-www-form-urlencoded' \ 
---data-urlencode 'client_id=iago-web' \\\ +  --data-urlencode 'client_id=iago-web' \ 
---data-urlencode 'username=BOTMINUTA' \\\ +  --data-urlencode 'username=BOTMINUTA' \ 
---data-urlencode 'password=<SENHA>' \\\ +  --data-urlencode 'password=<SENHA>' \ 
---data-urlencode 'grant_type=password'\\ +  --data-urlencode 'grant_type=password' 
-```+</code>
  
-### 5.2. Homologação+==== 5.2. Homologação ====
  
-```bash\\ +<code bash> 
-curl --location 'https://auth-hom.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' \\\ +curl --location 'https://auth-hom.tce.go.gov.br/realms/tce-go/protocol/openid-connect/token' \ 
---header 'Content-Type: application/x-www-form-urlencoded' \\\ +  --header 'Content-Type: application/x-www-form-urlencoded' \ 
---data-urlencode 'client_id=iago-web' \\\ +  --data-urlencode 'client_id=iago-web' \ 
---data-urlencode 'username=botminuta' \\\ +  --data-urlencode 'username=botminuta' \ 
---data-urlencode 'password=<SENHA>' \\\ +  --data-urlencode 'password=<SENHA>' \ 
---data-urlencode 'grant_type=password'\\ +  --data-urlencode 'grant_type=password' 
-```+</code>
  
 O token retornado deve ser enviado ao endpoint: O token retornado deve ser enviado ao endpoint:
  
-```http\\ +<code> 
-Authorization: Bearer <TOKEN>\\ +Authorization: Bearer <TOKEN> 
-Content-Type: application/json\\ +Content-Type: application/json 
-```+</code>
  
-### Retornos relacionados à autenticação+==== Retornos relacionados à autenticação ====
  
-| HTTP | Situação |\\ +^ HTTP ^ Situação ^ 
-|---|---|\\ +| ''401 Unauthorized'' | Requisição realizada sem autenticação/token válido. | 
-| `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. |
-| `403 Forbidden` | Usuário autenticado, porém sem autorização para utilização do endpoint. |+
  
----+----
  
-## 6. Usuário de serviço+===== 6. Usuário de serviço =====
  
 O usuário recomendado para criação das peças geradas pelo IAGO é: O usuário recomendado para criação das peças geradas pelo IAGO é:
  
-```text\\ +<code> 
-BOTMINUTA\\ +BOTMINUTA 
-```+</code>
  
 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. 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+==== 6.1. Regra de lotação ====
  
 Uma das principais regras da integração é: Uma das principais regras da integração é:
Linha 134: Linha 134:
 Atualmente existem vinculações do usuário de serviço aos seguintes setores: Atualmente existem vinculações do usuário de serviço aos seguintes setores:
  
-| Setor | Descrição | Usuário/vinculação | +^ Setor ^ Descrição ^ Usuário/vinculação ^ 
-|---|---|---|\\ +| ''DI-TI'' | Diretoria de Tecnologia da Informação | ''BOTMINUTA'' | 
-| `DI-TI` | Diretoria de Tecnologia da Informação | `BOTMINUTA` |\\ +| ''GPCCR'' | Gabinete do Procurador de Contas Carlos Gustavo Silva Rodrigues | ''BOTMINUTA_GPCCR'' |
-| `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.+> **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+===== 7. Contrato da requisição =====
  
-### Request Body+==== Request Body ====
  
-```json +<code json> 
-{\\ +{ 
-"setorGeralId": 26,\\ +  "setorGeralId": 26, 
-"conversaId": 0,\\ +  "codigoProcesso": 202400047002057, 
-"codigoProcesso": 202400047002057,\\ +  "tipoDocumento": "DP", 
-"tipoDocumento": "DP",\\ +  "corpoDocumento": "<p>Conteúdo da minuta...</p>", 
-"corpoDocumento": "<p>Conteúdo da minuta...</p>",\\ +  "ementa": "Ementa opcional da peça" 
-"ementa": "Ementa opcional da peça"\\ +} 
-}\\ +</code>
-```+
  
-### Campos+==== Campos ====
  
-| Campo | Obrigatório | Descrição |\\ +^ 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. | 
-| `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. | 
-| `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**. | 
-| `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. | 
-| `corpoDocumento` | Sim | Conteúdo da peça em HTML. |\\ +| ''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. |
-| `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+==== Observações sobre o contrato ====
  
-- Recomenda-se enviar `tipoDocumento` como `DP`.\\ +  * Deve ser utilizado ''tipoDocumento = "DP"''. 
-- O contrato deve trabalhar com **um processo por requisição**.\\ +  * O contrato deve trabalhar com **um processo por requisição**. 
-- Recomenda-se utilizar os tipos definidos no contrato/Swagger.\\ +  * 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.+  * ''corpoDocumento'' deve possuir conteúdo HTML válido e conteúdo efetivo. 
 +  * Tags HTML vazias não são aceitas.
  
----+----
  
-## 8. Regra da ementa+===== 8. Regra da ementa =====
  
-O campo `ementa` é **opcional**.+O campo ''ementa'' é **opcional**.
  
-### Quando `ementa` é informada+==== Quando a ementa é informada ====
  
 A ementa do documento será gerada utilizando o conteúdo enviado na própria requisição: A ementa do documento será gerada utilizando o conteúdo enviado na própria requisição:
  
-```json\\ +<code json> 
-{\\ +{ 
-"ementa": "Análise da prestação de contas..."\\ +  "ementa": "Análise da prestação de contas..." 
-}\\ +} 
-```+</code>
  
-### Quando `ementa` não é informada+===== 8. Regra da ementa =====
  
-A API busca a ementa cadastrada no processo, proveniente do cadastro da **autuação**.+O campo ''ementa'' da requisição é **opcional**.
  
-Se nenhuma ementa estiver disponível para ser utilizada, a criação não poderá prosseguir.+Durante o processamento, a API também considera a ementa cadastrada na autuação do processo.
  
-Retorno:+A definição da ementa do documento ocorre da seguinte forma:
  
-```json\\ +  * 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.
-"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.+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:
  
-## 9. Tipo de documento permitido+<code 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" 
 +} 
 +</code> 
 + 
 +^ 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**. Na primeira versão da integração foi implementada a criação de **Parecer**.
Linha 222: Linha 227:
 O valor esperado é: O valor esperado é:
  
-```json +<code json> 
-{\\ +{ 
-"tipoDocumento": "DP"\\ +  "tipoDocumento": "DP" 
-}\\ +} 
-```+</code>
  
-`DP` corresponde ao tipo documental **Parecer**.+''DP'' corresponde ao tipo documental **Parecer**.
  
 Não devem ser enviados outros tipos documentais enquanto não forem explicitamente habilitados para a integração. 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+==== Tipo não permitido para integração com o IAGO ====
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Tipo de documento não permitido.",\\ +  "title": "Tipo de documento não permitido.", 
-"detail": "Tipo de documento não permitido para integração com o Iago.",\\ +  "detail": "Tipo de documento não permitido para integração com o Iago.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
-### Tipo inexistente ou indisponível para o setor+==== 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: Também pode ocorrer validação relacionada ao cadastro ou habilitação do tipo documental para o setor informado:
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "Não existe o tipo de documento com o indicador DP informado.",\\ +  "detail": "Não existe o tipo de documento com o indicador DP informado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
----+----
  
-## 10. Fluxo da operação+===== 10. Fluxo da operação =====
  
 De forma simplificada, o endpoint executa o seguinte fluxo: De forma simplificada, o endpoint executa o seguinte fluxo:
  
-1. recebe a requisição;\\ +  - Recebe a requisição. 
-2. valida autenticação;\\ +  - Valida a autenticação. 
-3. valida autorização para utilização da API;\\ +  - Valida a autorização para utilização da API. 
-4. valida os campos da requisição;\\ +  - Valida os campos da requisição. 
-5. valida a vinculação do usuário ao setor;\\ +  - Valida a vinculação do usuário ao setor. 
-6. valida a existência do processo;\\ +  - Valida a existência do processo. 
-7. valida as condições do processo e do andamento;\\ +  - Valida as condições do processo e do andamento. 
-8. valida o tipo documental;\\ +  - Valida o tipo documental. 
-9. valida regras de segurança do processo;\\ +  - Valida as regras de segurança do processo. 
-10. valida a existência e o estado de documentos anteriores;\\ +  - Valida a existência e o estado de documentos anteriores. 
-11. cria uma nova peça ou substitui uma peça anterior quando permitido;\\ +  - Cria uma nova peça ou substitui uma peça anterior quando permitido. 
-12. cria/atualiza o documento no TCE-Docs;\\ +  - Cria ou atualiza o documento no TCE-Docs. 
-13. vincula o documento ao último andamento do processo;\\ +  - Vincula o documento ao último andamento do processo. 
-14. atualiza os dados relacionados ao documento no andamento;\\ +  - Atualiza os dados relacionados ao documento no andamento. 
-15. retorna os dados da operação.+  - Retorna os dados da operação.
  
----+----
  
-## 11. Regras de negócio+===== 11. Regras de negócio =====
  
-### RN01 — Processo existente+==== RN01 — Processo existente ====
  
 O processo informado precisa existir. O processo informado precisa existir.
Linha 294: Linha 299:
 Caso contrário, a operação é interrompida. Caso contrário, a operação é interrompida.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "Processo informado não existe.",\\ +  "detail": "Processo informado não existe.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN02 — Usuário vinculado ao setor+==== RN02 — Usuário vinculado ao setor ====
  
-O usuário autenticado precisa estar vinculado ao `setorGeralId` informado.+O usuário autenticado precisa estar vinculado ao ''setorGeralId'' informado.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Objeto informado está inválido.",\\ +  "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",\\ +  "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",\\ +  "typeDetail": "application/json", 
-"status": "Validation",\\ +  "status": "Validation", 
-"type": "Validation",\\ +  "type": "Validation", 
-"instance": null,\\ +  "instance": null, 
-"code": "422"\\ +  "code": "422" 
-}\\ +} 
-```+</code>
  
 Essa regra é válida tanto para processos comuns quanto reservados. Essa regra é válida tanto para processos comuns quanto reservados.
  
----+----
  
-### RN03 — Processo no setor informado+==== 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. O processo deve estar no setor informado na requisição, permitindo que a peça seja vinculada ao andamento correto.
Linha 334: Linha 339:
 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 é 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+==== 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. 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 json> 
-{\\ +{ 
-"title": "Processo Sigiloso.",\\ +  "title": "Processo Sigiloso.", 
-"detail": "Não é permitida a criação de documentos no processo (2013100280472), pois ele possui caráter sigiloso.",\\ +  "detail": "Não é permitida a criação de documentos no processo (2013100280472), pois ele possui caráter sigiloso.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
 O número do processo apresentado na mensagem varia conforme o processo informado. O número do processo apresentado na mensagem varia conforme o processo informado.
  
----+----
  
-### RN05 — Processos reservados+==== 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.+A criação é permitida em processo reservado desde que:
  
-Caso o usuário não esteja vinculado ao setor informado, a requisição é rejeitada com `422`.+  * 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+---- 
 + 
 +==== RN06 — Ementa ====
  
 A ementa utilizada no documento segue a seguinte prioridade: A ementa utilizada no documento segue a seguinte prioridade:
  
-1. `ementa` informada no body da requisição;\\ +  - ''ementa'' informada no body da requisição; 
-2. ementa cadastrada na autuação do processo.+  - ementa cadastrada na autuação do processo.
  
 Caso não exista uma ementa válida disponível, a criação é interrompida. Caso não exista uma ementa válida disponível, a criação é interrompida.
  
----+----
  
-### RN07 — Responsável pelo setor+==== RN07 — Responsável pelo setor ====
  
 Deve existir responsável cadastrado para o setor do processo. Deve existir responsável cadastrado para o setor do processo.
Linha 381: Linha 390:
 Caso não exista responsável cadastrado, a criação da minuta será interrompida. Caso não exista responsável cadastrado, a criação da minuta será interrompida.
  
----+----
  
-### RN08 — Documento assinado ou aguardando assinatura+==== RN08 — Documento assinado ou aguardando assinatura ====
  
 Não é permitida a substituição quando o processo já possui documento assinado ou aguardando assinatura. Não é permitida a substituição quando o processo já possui documento assinado ou aguardando assinatura.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Documento Assinado/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.",\\ +  "detail": "O processo atual já possui um documento assinado ou aguardando assinatura e não pode ser alterado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN09 — Documento aberto para edição no Word+==== RN09 — Documento aberto para edição no Word ====
  
 Não é permitida a substituição automática quando o documento está aberto para edição. Não é permitida a substituição automática quando o documento está aberto para edição.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Substituição automática não permitida.",\\ +  "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.",\\ +  "detail": "O documento já se encontra aberto para edição no Word. A substituição automática não é permitida.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN10 — Substituição de documento criado pelo IAGO+==== 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**. Um documento criado anteriormente pelo IAGO pode ser automaticamente substituído **somente quando não tiver sofrido alteração por usuário**.
Linha 425: Linha 434:
 Nesse cenário, o endpoint retorna sucesso e: Nesse cenário, o endpoint retorna sucesso e:
  
-```json\\ +<code json> 
-{\\ +{ 
-"acaoExecutada": "Substituicao"\\ +  "acaoExecutada": "Substituicao" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN11 — Documento criado pelo IAGO e alterado por usuário+==== 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. Se um documento criado pelo IAGO tiver sido posteriormente alterado por um usuário, a substituição automática não é permitida.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "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.",\\ +  "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",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN12 — Documento criado por usuário+==== RN12 — Documento criado por usuário ====
  
 Documentos originalmente criados por usuário não podem ser substituídos automaticamente pela integração. Documentos originalmente criados por usuário não podem ser substituídos automaticamente pela integração.
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Substituição automática não permitida.",\\ +  "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.",\\ +  "detail": "O documento existente foi criado por um usuário. A substituição automática não é permitida.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "Conflict",\\ +  "type": "Conflict", 
-"instance": null,\\ +  "instance": null, 
-"code": "409"\\ +  "code": "409" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN13 — Corpo do documento obrigatório+==== RN13 — Corpo do documento obrigatório ====
  
-`corpoDocumento` é obrigatório e precisa conter conteúdo válido.+''corpoDocumento'' é obrigatório e precisa conter conteúdo válido.
  
 Não são aceitos: Não são aceitos:
  
-- valor `null`;\\ +  * valor ''null''; 
-- string vazia;\\ +  * string vazia; 
-- conteúdo contendo somente espaços;\\ +  * conteúdo contendo somente espaços; 
-- HTML sem conteúdo útil;\\ +  * HTML sem conteúdo útil; 
-- conteúdo em formato HTML considerado inválido pela API.+  * conteúdo em formato HTML considerado inválido pela API.
  
-Para valor vazio ou `null`:+Para valor vazio ou ''null'':
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "O corpo do documento deve ser informado.",\\ +  "detail": "O corpo do documento deve ser informado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
 Para HTML inválido ou contendo somente tags vazias: Para HTML inválido ou contendo somente tags vazias:
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "O corpo do documento informado está em um formato inválido.",\\ +  "detail": "O corpo do documento informado está em um formato inválido.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
----+----
  
-### RN14 — Um processo por requisição+==== RN14 — Um processo por requisição ====
  
 O endpoint deve ser utilizado para inclusão de documento em **um processo por vez**. 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`.+Não deve ser enviada uma lista de processos no campo ''codigoProcesso''.
  
----+----
  
-### RN15 — Atualização do andamento+==== 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. 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.
Linha 525: Linha 534:
 Entre os dados relacionados ao documento estão: Entre os dados relacionados ao documento estão:
  
-```text\\ +<code> 
-ID_DOCUMENT_N\\ +ID_DOCUMENT_N 
-TIPO_DOCUMENT_A\\ +TIPO_DOCUMENT_A 
-```+</code>
  
----+----
  
-## 12. Campos obrigatórios e mensagens de validação+===== 12. Campos obrigatórios e mensagens de validação =====
  
-### `setorGeralId`+==== setorGeralId ====
  
 Quando não informado: Quando não informado:
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "O setor geral do usuário deve ser informado.",\\ +  "detail": "O setor geral do usuário deve ser informado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
-### `codigoProcesso`+==== codigoProcesso ====
  
 Quando não informado: Quando não informado:
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "O código do processo deve ser informado.",\\ +  "detail": "O código do processo deve ser informado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
-### `corpoDocumento`+==== corpoDocumento ====
  
-Quando vazio ou `null`:+Quando vazio ou ''null'':
  
-```json\\ +<code json> 
-{\\ +{ 
-"title": "Parâmetro inválido",\\ +  "title": "Parâmetro inválido", 
-"detail": "O corpo do documento deve ser informado.",\\ +  "detail": "O corpo do documento deve ser informado.", 
-"typeDetail": "text/plain",\\ +  "typeDetail": "text/plain", 
-"status": "Error",\\ +  "status": "Error", 
-"type": "BadRequest",\\ +  "type": "BadRequest", 
-"instance": null,\\ +  "instance": null, 
-"code": "400"\\ +  "code": "400" 
-}\\ +} 
-```+</code>
  
-### `conversaId`+==== conversaId ====
  
 O campo não é obrigatório. O campo não é obrigatório.
Linha 588: Linha 597:
 São permitidos: São permitidos:
  
-- atributo não informado;\\ +  * atributo não informado; 
-- `conversaId = 0`.+  * ''conversaId = 0''.
  
----+----
  
-## 13. Exemplo de requisição+===== 13. Exemplo de requisição =====
  
-```bash\\ +==== Homologação ====
-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"\\ +
-}'\\ +
-```+
  
-> No ambiente de produção, substituir a URL de homologação pela URL correspondente de produção.+<code 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, 
 +    "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>
  
----+Para produção utilizar:
  
-## 14. Retorno de sucesso+<code> 
 +https://api-etce.tce.go.gov.br/api/v1/Documento/iago 
 +</code>
  
-### Criação de novo documento+----
  
-```json +===== 14. Retorno de sucesso =====
-{\\ +
-"documentoId": 6255658,\\ +
-"codigoProcesso": 201800047000443,\\ +
-"tipoDocumento": "Parecer",\\ +
-"dataHora": "2026-07-17T11:29:34.724411-03:00",\\ +
-"nomeUsuario": "BOTMINUTA",\\ +
-"acaoExecutada": "CriacaoNova"\\ +
-}\\ +
-```+
  
-### Substituição permitida+==== Criação de novo documento ====
  
-```json\\ +<code json> 
-{\\ +{ 
-"documentoId": 6255660,\\ +  "documentoId": 6255658, 
-"codigoProcesso": 201800047000443,\\ +  "codigoProcesso": 201800047000443, 
-"tipoDocumento": "Parecer",\\ +  "tipoDocumento": "Parecer", 
-"dataHora": "2026-07-17T11:41:00.2380878-03:00",\\ +  "dataHora": "2026-07-17T11:29:34.724411-03:00", 
-"nomeUsuario": "BOTMINUTA",\\ +  "nomeUsuario": "BOTMINUTA", 
-"acaoExecutada": "Substituicao"\\ +  "acaoExecutada": "CriacaoNova" 
-}\\ +} 
-```+</code>
  
-### Campos do retorno+==== Substituição permitida ====
  
-| Campo | Descrição |\\ +<code json> 
-|---|---|\\ +{ 
-| `documentoId` | Identificador do documento criado/atualizado no TCE-Docs. |\\ +  "documentoId": 6255660, 
-| `codigoProcesso` | Processo relacionado à operação. |\\ +  "codigoProcesso": 201800047000443, 
-| `tipoDocumento` | Descrição do tipo documental criado. |\\ +  "tipoDocumento": "Parecer", 
-| `dataHora` | Data e hora da operação. |\\ +  "dataHora": "2026-07-17T11:41:00.2380878-03:00", 
-| `nomeUsuario` | Usuário responsável pela criação via integração. |\\ +  "nomeUsuario": "BOTMINUTA", 
-| `acaoExecutada` | Informa se houve `CriacaoNova` ou `Substituicao`. |+  "acaoExecutada": "Substituicao" 
 +} 
 +</code>
  
----+==== Campos do retorno ====
  
-## 15. Códigos HTTP+^ 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''. |
  
-| 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. |+
  
----+===== 15. Códigos HTTP =====
  
-## 16. Resumo das principais validações+^ 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. |
  
-| 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 |+
  
----+===== 16. Resumo das principais validações =====
  
-## 17. Considerações para expansão da funcionalidade+^ 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 |
  
-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;\\ +===== 17. Considerações para expansão da funcionalidade =====
-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`)**.+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.
  
-## 18. Recomendações para consumo pelo IAGO+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;\\ +===== 18. Recomendações para consumo pelo IAGO =====
-- 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.+
  
----+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.
  
 +----
  • pres/gerti/manuais/integracaoiagoxetce.1790260788.txt.gz
  • Última modificação: 24/09/2026 14:39
  • por rmpires
  • Atualmente bloqueada por: rmpires