لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/bizproc-templates.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Business process templates

A business process template is a process blueprint bound to a document type: a deal, a lead, a list item, a Drive document. Bitrix24 starts a process from the template when the document is created or changed. An application uploads a ready-made template as a .bpt file, changes its settings, and deletes it.

Bitrix24 API: bizproc.workflow.template.* Scope: bizproc

Upload a template

POST /v1/bizproc-templates

Uploads a business process template from a BPT file and binds it to a document type. Fields are passed flat at the JSON root, without a fields wrapper.

Request fields (body)

Field Type Required Description
FieldtemplateData Typearray Requiredyes DescriptionTemplate file as two elements — the file name and its contents in base64. Example: ["process.bpt", "eNrlWNtO41YUfe..."]
FielddocumentType Typearray Requiredyes DescriptionDocument type [module, object, type]. Values:
["crm", "CCrmDocumentLead", "LEAD"] — leads
["crm", "CCrmDocumentContact", "CONTACT"] — contacts
["crm", "CCrmDocumentCompany", "COMPANY"] — companies
["crm", "CCrmDocumentDeal", "DEAL"] — deals
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Quote", "QUOTE"] — quotes
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\SmartInvoice", "SMART_INVOICE"] — invoices
["crm", "Bitrix\\Crm\\Integration\\BizProc\\Document\\Dynamic", "DYNAMIC_<entityTypeId>"] — smart processes, <entityTypeId> from the entityTypeId field in GET /v1/smart-processes
["lists", "BizprocDocument", "iblock_<id>"] — processes in the Feed
["lists", "Bitrix\\Lists\\BizprocDocumentLists", "iblock_<id>"] — lists in workgroups
["disk", "Bitrix\\Disk\\BizProcDocument", "STORAGE_<id>"] — Drive documents
Fieldname Typestring Requiredyes DescriptionTemplate name. Bitrix24 rejects an empty value
Fielddescription Typestring Requiredno DescriptionTemplate description
FieldautoExecute Typenumber Requiredno DescriptionAutostart condition: 0 — no autostart, 1 — on document creation, 2 — on change, 3 — on creation and change. Defaults to 0

Examples

Only an authorization key can upload templates — both examples send the authorization key and the Authorization: Bearer header. The session token is issued by OAuth authorization, is valid for 24 hours, and cannot be renewed — Passing the key.

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bizproc-templates" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "documentType": ["crm", "CCrmDocumentDeal", "DEAL"],
    "name": "Deal approval",
    "description": "Uploaded from the application",
    "autoExecute": 0,
    "templateData": ["approval.bpt", "eNrlWNtO41YUfe..."]
  }'

JavaScript — OAuth application

javascript 
import { readFile } from 'node:fs/promises'

const file = await readFile('approval.bpt')

const res = await fetch('https://vibecode.bitrix24.com/v1/bizproc-templates', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    documentType: ['crm', 'CCrmDocumentDeal', 'DEAL'],
    name: 'Deal approval',
    description: 'Uploaded from the application',
    autoExecute: 0,
    templateData: ['approval.bpt', file.toString('base64')],
  }),
})

const { success, data } = await res.json()
console.log(`Template identifier: ${data.id}`)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.id Typenumber DescriptionIdentifier of the created template. Used in the update and delete paths

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 1215
  }
}

Error response example

400 — the template file was not passed:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "Body field \"templateData\" is required to create bizprocTemplate."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe templateData field was not passed
HTTP409 CodeBIZPROC_MODULE_NOT_ENABLED DescriptionBusiness Processes are not available on the account: the module is not included in the plan, or it is switched off in account settings. Ask an account administrator to enable Business Processes — until then the method answers the same way for any number of retries
HTTP422 CodeBITRIX_ERROR Descriptionname was not passed — message Empty template name!, the b24Code field contains ERROR_TEMPLATE_VALIDATION_FAILURE
HTTP422 CodeBITRIX_ERROR DescriptiondocumentType was not passed or an unknown type was given — message Incorrect field DOCUMENT_TYPE!, the b24Code field contains ERROR_TEMPLATE_VALIDATION_FAILURE
HTTP422 CodeBITRIX_ERROR DescriptionThe file contents were not recognized as a template. Bitrix24 returns the message text in the account language
HTTP403 CodeOAUTH_REQUIRED DescriptionThe request was sent with an API key. Only an authorization key can upload templates
HTTP401 CodeTOKEN_MISSING DescriptionAuthorization key without the Authorization: Bearer header
HTTP401 CodeWRONG_AUTH_SCHEME DescriptionThe authorization key was sent in the Authorization: Bearer header. The key goes in X-Api-Key, while Authorization: Bearer carries the session token
HTTP401 CodeINVALID_SESSION DescriptionThe session token has expired or is invalid — authorize again
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the bizproc scope

On a Bitrix24-side error the error object gains a b24Code field — the machine-readable reason code.

The full list of common API errors — Errors.

Known specifics

The .bpt file is prepared in Bitrix24. Configure the process in the business process designer and export it to a file — that file is what you pass in templateData. The contents of a .bpt file cannot be assembled through the API, so preparing the file stays a manual step.

The response does not show what was written. Only id is returned, so check the applied values by reading the record through GET /v1/bizproc-templates with a filter by id.

See also