Documents — Overview

The documents domain brings together the endpoints used to automatically generate filled-in documents (such as proposals, contracts, and reports) from configurable templates, combining a .docx file with the data of a card and its linked clients. A template defines the document's structure and the dynamic fields that are replaced with the process's data at generation time. Optionally, a phase can have an automatic generation configuration, which triggers document creation without manual intervention as the card advances through the flow.

The endpoints in this domain live on two distinct surfaces: the endpoints under /v1/cards/... and /v1/flows/.../auto-document-config are part of the main AgFlow API; the /templates... endpoints (without the /v1 prefix) belong to the document generation service, responsible for the template's own lifecycle (creation, fields, rules, activation, and file).

Endpoints in this domain

Method	Path	Description
`GET`	`/v1/cards/{cardId}/templates`	Lists the templates available for the card
`GET`	`/v1/cards/templates/{templateId}`	Gets a template by identifier
`GET`	`/v1/cards/{cardId}/templates/{templateId}/fields`	Gets the field structure to generate the document
`POST`	`/v1/cards/{cardId}/templates/{templateId}/generate`	Generates the document from the template and the card's data
`GET`	`/v1/flows/{flowId}/phases/{phaseId}/auto-document-config`	Gets the phase's automatic generation configuration
`POST`	`/v1/flows/{flowId}/phases/{phaseId}/auto-document-config`	Creates the phase's automatic generation configuration
`PUT`	`/v1/flows/{flowId}/phases/{phaseId}/auto-document-config`	Updates the phase's automatic generation configuration
`DELETE`	`/v1/flows/{flowId}/phases/{phaseId}/auto-document-config/{autoDocumentConfigId}`	Deletes the phase's automatic generation configuration
`POST`	`/templates`	Creates a document template (step 1)
`PUT`	`/templates/{id}/fields`	Defines the template's fields (step 2)
`PUT`	`/templates/{id}/activate`	Activates the template (final step)
`PUT`	`/templates/{id}/fields/rules`	Configures the fields' conditional rules
`GET`	`/templates`	Lists the registered templates
`POST`	`/templates/{id}/file`	Uploads a new file for a template
`DELETE`	`/templates/{id}`	Deletes a template

Creating a template is a multi-step process

Creating a template ready for use is not a single call — it is a mandatory sequence:

Create the base template (POST /templates): registers name, processor, scope, and description, and returns a temporary signed URL for uploading the .docx file.

Upload the .docx file to the signed URL returned in the previous step.

Define the fields (PUT /templates/{id}/fields): the fields sent in step 1 are not persisted as the final configuration — this call is always required for the fields to actually take effect.

Configure conditional rules, if needed (PUT /templates/{id}/fields/rules) — optional, used to show, hide, or make fields required/optional based on the value of other fields.

Activate the template (PUT /templates/{id}/activate): final step, required for the template to become available for document generation. It also needs to be repeated whenever the fields or the conditional rules are changed after the initial activation, since both operations deactivate the template as a side effect.

Field origin format (`path` and `reference`)

Each field of a template declares where its value comes from. The format varies according to the data's origin:

Field from the flow's initial form: fixed path of start-form and reference equal to the field's identifier.

Field from a phase: path in the format phase-field.<phase-identifier> and reference in the format <phase-identifier>:<field-identifier>.

Field from the technical opinion: fixed path of opinion-field and reference equal to the field's identifier.

Native fields (client basic data, approvals, credit engine, among others): only a fixed path (for example basic-data.name or credit-engine.score), with no reference.

A path not recognized by the API does not raise an error — the corresponding field simply stays empty in the generated document. Because of this, it's worth validating the result by generating an actual document after any change to the field structure.

Important behaviors

Each phase allows at most one automatic document generation configuration. Creating a new one when one already exists returns an error stating that a configuration already exists for that flow and phase (the message includes the identifier of the existing configuration). To edit an existing configuration, the recommended path is to remove the current one and create a new one — although the direct update call is also available for the case of just repointing the linked template.

Uploading a new file for an existing template does not update it in place — the result is a new template, with a new identifier. The original remains intact (cards that already generated documents from it keep referencing the old identifier), but any automatic document generation configuration, conversation configuration, or trigger that pointed to the old identifier needs to be manually updated.

Defining a template's fields or conditional rules deactivates the template as a side effect — it always needs to be activated again afterward.

If a field references a section (section) that was not declared when the template was created, the field definition call fails with an error stating the section was not found.

The fields payload only accepts a specific set of properties (key, title, type, path, reference, required, options, section, uiComponent, children, rules) — properties such as active, editable, category, index, id, createdAt, updatedAt, and sectionKey are rejected.

A template is always specific to one flow: reusing the identifier of a template created in another flow returns a resource-not-found error.

After a template is created, it may take a few moments before it appears in the listing — indexing is asynchronous. Subsequent calls that depend on the newly created template may fail during that window; we recommend retrying after a few seconds.

Removing a template is irreversible: cards that already generated documents from it end up with a broken download link.

When generating the document (POST .../generate), the fields in clients[] and generalSections[] never include the id property — they use the key (key) declared in the template, prefixed by the parent group when applicable (for example fiadores.nome).

Documents — Overview

Endpoints in this domain#

Creating a template is a multi-step process#

Field origin format (path and reference)#

Important behaviors#

Endpoints in this domain

Creating a template is a multi-step process

Field origin format (`path` and `reference`)

Important behaviors