Documentos — Visão Geral
Documentos — Visão geral
.docx com os dados de um card e de seus clientes vinculados. Um template define a estrutura do documento e os campos dinâmicos que serão substituídos pelos dados do processo no momento da geração. Opcionalmente, uma fase pode ter uma configuração de geração automática, que dispara a criação do documento sem intervenção manual conforme o card avança pelo flow.Os endpoints deste domínio vivem em duas superfícies distintas: os endpoints sob /v1/cards/...e/v1/flows/.../auto-document-configfazem parte da API principal do AgFlow; já os endpoints/templates...(sem o prefixo/v1) pertencem ao serviço de geração de documentos, responsável pelo ciclo de vida do template propriamente dito (criação, campos, regras, ativação e arquivo).
Endpoints deste domínio
| Método | Caminho | Descrição |
|---|---|---|
GET | /v1/cards/{cardId}/templates | Lista os templates disponíveis para o card |
GET | /v1/cards/templates/{templateId} | Consulta um template por identificador |
GET | /v1/cards/{cardId}/templates/{templateId}/fields | Consulta a estrutura de campos para gerar o documento |
POST | /v1/cards/{cardId}/templates/{templateId}/generate | Gera o documento a partir do template e dos dados do card |
GET | /v1/flows/{flowId}/phases/{phaseId}/auto-document-config | Consulta a configuração de geração automática da fase |
POST | /v1/flows/{flowId}/phases/{phaseId}/auto-document-config | Cria a configuração de geração automática da fase |
PUT | /v1/flows/{flowId}/phases/{phaseId}/auto-document-config | Atualiza a configuração de geração automática da fase |
DELETE | /v1/flows/{flowId}/phases/{phaseId}/auto-document-config/{autoDocumentConfigId} | Remove a configuração de geração automática da fase |
POST | /templates | Cria um template de documento (etapa 1) |
PUT | /templates/{id}/fields | Define os campos do template (etapa 2) |
PUT | /templates/{id}/activate | Ativa o template (etapa final) |
PUT | /templates/{id}/fields/rules | Configura regras condicionais dos campos |
GET | /templates | Lista os templates cadastrados |
POST | /templates/{id}/file | Envia um novo arquivo para um template |
DELETE | /templates/{id} | Remove um template |
A criação de um template é um processo em etapas
1.
POST /templates): registra nome, processador, escopo e descrição, e retorna uma URL assinada e temporária para o envio do arquivo .docx.2.
.docx na URL assinada retornada na etapa anterior.3.
PUT /templates/{id}/fields): os campos enviados na etapa 1 não são persistidos como configuração definitiva — esta chamada é sempre necessária para que os campos realmente passem a valer.4.
PUT /templates/{id}/fields/rules) — opcional, usada para exibir, ocultar ou tornar campos obrigatórios/opcionais com base no valor de outros campos.5.
PUT /templates/{id}/activate): etapa final, obrigatória para que o template fique disponível para geração de documentos. Também precisa ser repetida sempre que os campos ou as regras condicionais forem alterados depois da ativação inicial, já que ambas as operações desativam o template como efeito colateral.Formato de origem dos campos (path e reference)
path fixo start-form e reference igual ao identificador do campo.path no formato phase-field.<identificador-da-fase> e reference no formato <identificador-da-fase>:<identificador-do-campo>.path fixo opinion-field e reference igual ao identificador do campo.path fixo (por exemplo basic-data.name ou credit-engine.score), sem reference.path não reconhecido pela API não gera erro — o campo correspondente simplesmente fica vazio no documento gerado. Por isso, vale a pena validar o resultado gerando um documento real após qualquer mudança na estrutura de campos.Comportamentos importantes
section) que não foi declarada na criação do template, a definição de campos falha com erro informando que a seção não foi encontrada.key, title, type, path, reference, required, options, section, uiComponent, children, rules) — propriedades como active, editable, category, index, id, createdAt, updatedAt e sectionKey são rejeitadas.POST .../generate), os campos de clients[] e generalSections[] nunca incluem a propriedade id — usam a chave (key) declarada no template, prefixada pelo grupo pai quando aplicável (por exemplo fiadores.nome).Modificado em 2026-07-28 20:38:32