Documents: Overview of Methods

A document is a file that the document generator has built from a .docx template and the data of a CRM object. The finished document is retained in Bitrix24 in three formats: the source DOCX, a PDF, and a preview image.

A document is always linked to a specific CRM object — a deal, lead, contact, company, invoice, estimate, or SPA element. The link is defined by the entityTypeId and entityId pair.

For example, you can generate a document for deal No. 1042 from an invoice template and enable a public link for it to send to the client.

Quick navigation: all methods and events

User documentation: Documents in CRM: Create and send to customers

How to Create a DocumentHow to Create a Document

1. Obtain the templateId — the identifier of a template from the Document Templates section.
2. Determine the entityTypeId and entityId of the CRM object for which the document is needed.
3. Create the document using the crm.documentgenerator.document.add method. If the file is already prepared outside Bitrix24, upload it using the crm.documentgenerator.document.upload method.
4. Take the document id and the links to the files from the response.

To insert your own values into the document, pass them in the values parameter of the crm.documentgenerator.document.add method. The list of keys allowed for a specific document is returned by crm.documentgenerator.document.getfields.

How to Share a DocumentHow to Share a Document

By default, the document is available only to employees who have permissions for the CRM object. The crm.documentgenerator.document.enablepublicurl method enables a public link — the document opens through it without authorization in Bitrix24. The same method disables the link again.

Important ConsiderationsImportant Considerations

• The pdfUrl and imageUrl links may not be available immediately after creating or updating the document, as the conversion is performed asynchronously. If you need the links right away, repeat the request using the crm.documentgenerator.document.get method after 30-40 seconds.
• Permissions are checked per action: reading and listing require view permission for documents, crm.documentgenerator.document.add requires create permission, and modifying and deleting require modify permission. Access to the document itself is checked additionally.
• The crm.documentgenerator.document.* methods work with CRM documents. If the document is not linked to a CRM object, use the methods of the Document Generator section.

Relationships with Other ObjectsRelationships with Other Objects

Document Templates. To create a document from a template, pass the templateId to the crm.documentgenerator.document.add method. Obtain the templateId from the response of crm.documentgenerator.template.add or retrieve it from the list using the crm.documentgenerator.template.list method.

CRM Entities. To create or upload a document, pass the entityTypeId and entityId. The values of entityTypeId for standard objects are provided in the table CRM Object Types. For SPAs, the entityTypeId can be obtained using the crm.type.list method. The identifier of the required object, entityId, can be obtained using the universal crm.item.list method.

Numbering. When creating a document, the number is usually generated based on the numbering system associated with the template. If you are creating a new numbering system, obtain the id from the response of crm.documentgenerator.numerator.add. If you are using an existing one, retrieve the id using the crm.documentgenerator.numerator.list method.

Files. In the crm.documentgenerator.document.upload method, the file content is passed in Base64. The upload format is described in the article How to Upload Files.

Overview of Methods and EventsOverview of Methods and Events

Scope: crm

Who can execute the method: depends on the method