Dành cho AI agent: markdown của trang này — /docs-content-en/sign-b2e/send-document.md chỉ mục tài liệu — /llms.txt
Hiện tại, các bài viết trong tài liệu chỉ có bằng tiếng Anh.
Send a file for signature
POST /v1/sign-b2e/documents/send
Creates a document from a single file and sends it to employees for signature. The key owner needs permission to create documents. Sending has legal consequences.
Scopes: sign.b2e, crm.
Request body fields
| Parameter | Type | Required | Description |
|---|---|---|---|
Parameterfields |
Typeobject | Requiredyes | DescriptionFields object. Bitrix24 validates unknown fields and field values. |
Parameterfields.company |
Typeobject | null | Requiredyes | DescriptionYour own company: crmId or uuid. |
Parameterfields.company.crmId |
Typenumber | string | boolean | null | Requiredno | DescriptionYour own company ID from the list of companies. |
Parameterfields.company.uuid |
Typestring | null | Requiredno | DescriptionHCM Link company UUID; requires humanresources.hcmlink. |
Parameterfields.members |
Typearray | null | Requiredyes | DescriptionMembers: at least one signer and one representative. Bitrix24 checks the composition and roles. |
Parameterfields.members[].userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.members[].employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.members[].employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.members[].role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterfields.responsible |
Typeobject | null | Requiredyes | DescriptionResponsible person; the default role is assignee. |
Parameterfields.responsible.userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.responsible.employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.responsible.employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.responsible.role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterfields.companyProviderUid |
Typenumber | string | boolean | null | Requiredyes | DescriptionProvider UID from the list of company providers. This is not the numeric external provider ID. |
Parameterfields.files |
Typearray | null | Requiredyes | DescriptionArray of exactly one file. PDF, DOCX, DOC, RTF, ODT, JPG, JPEG and PNG are allowed; Bitrix24 checks the file. |
Parameterfields.files[].fileName |
Typenumber | string | boolean | null | Requiredno | DescriptionFile name with extension. |
Parameterfields.files[].fileType |
Typenumber | string | boolean | null | Requiredno | DescriptionMIME type matching the extension. |
Parameterfields.files[].fileContent |
Typenumber | string | boolean | null | Requiredno | DescriptionFile bytes in Base64. |
Parameterfields.regionDocumentType |
Typenumber | string | boolean | null | Requiredno | DescriptionRegional document type. Whether it is allowed depends on the license region. |
Parameterfields.externalSettings |
Typeobject | null | Requiredyes | DescriptionExternal system settings; null is allowed when sending from a template. |
Parameterfields.externalSettings.externalId |
Typenumber | string | boolean | null | Requiredyes | DescriptionDocument ID in the external system, up to 255 characters. |
Parameterfields.externalSettings.externalDateCreate |
Typenumber | string | boolean | null | Requiredyes | DescriptionCreation date in the external system in ISO 8601. Sending from a template requires the ATOM format with a numeric time zone offset. |
Parameterfields.language |
Typenumber | string | boolean | null | Requiredno | DescriptionLanguage of state names, en by default; an unknown language is replaced with en. Inside fields it is accepted but does not affect the document. |
Parameterfields.message |
Typenumber | string | boolean | null | Requiredno | DescriptionInvitation text for the employee. Bitrix24 checks the limits. |
Parameterfields.signers |
Typearray | null | Requiredno | DescriptionAccepted but not used to define members; use members instead. |
Parameterfields.signers[].userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.signers[].employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.signers[].employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.signers[].role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterfields.representatives |
Typearray | null | Requiredno | DescriptionAccepted but not used to define members; use members instead. |
Parameterfields.representatives[].userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.representatives[].employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.representatives[].employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.representatives[].role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterfields.reviewer |
Typeobject | null | Requiredno | DescriptionAccepted but not used to define members; use members instead. |
Parameterfields.reviewer.userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.reviewer.employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.reviewer.employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.reviewer.role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterfields.editor |
Typeobject | null | Requiredno | DescriptionAccepted but not used to define members; use members instead. |
Parameterfields.editor.userId |
Typenumber | string | boolean | null | Requiredno | DescriptionUser ID from the list of users. |
Parameterfields.editor.employeeId |
Typenumber | string | boolean | null | Requiredno | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Parameterfields.editor.employeeCode |
Typenumber | string | boolean | null | Requiredno | DescriptionHCM Link employee code; null for a regular user. |
Parameterfields.editor.role |
Typenumber | string | boolean | null | Requiredno | DescriptionRole: signer, assignee, reviewer or editor. |
Parameterlanguage |
Typestring | Requiredno | DescriptionLanguage of state names, en by default; an unknown language is replaced with en. Inside fields it is accepted but does not affect the document. |
Examples
curl — personal key
curl -X POST 'https://vibecode.bitrix24.com/v1/sign-b2e/documents/send' \
-H 'X-Api-Key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"fields": {"company": {"crmId": 7}, "companyProviderUid": "DUMMY_PROVIDER_UID", "members": [{"userId": 7, "role": "signer"}, {"userId": 8, "role": "assignee"}], "responsible": {"userId": 8, "role": "assignee"}, "files": [{"fileName": "VIBE-PROBE.pdf", "fileType": "application/pdf", "fileContent": "BASE64_FILE_BYTES"}], "externalSettings": {"externalId": "VIBE-PROBE-document-001", "externalDateCreate": "2026-11-13T12:00:00+00:00"}}}'
curl — OAuth application
curl -X POST 'https://vibecode.bitrix24.com/v1/sign-b2e/documents/send' \
-H 'X-Api-Key: YOUR_APP_KEY' \
-H 'Authorization: Bearer USER_SESSION_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"fields": {"company": {"crmId": 7}, "companyProviderUid": "DUMMY_PROVIDER_UID", "members": [{"userId": 7, "role": "signer"}, {"userId": 8, "role": "assignee"}], "responsible": {"userId": 8, "role": "assignee"}, "files": [{"fileName": "VIBE-PROBE.pdf", "fileType": "application/pdf", "fileContent": "BASE64_FILE_BYTES"}], "externalSettings": {"externalId": "VIBE-PROBE-document-001", "externalDateCreate": "2026-11-13T12:00:00+00:00"}}}'
JavaScript — personal key
const response = await fetch('https://vibecode.bitrix24.com/v1/sign-b2e/documents/send', {
"method": "POST",
"headers": {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({"fields": {"company": {"crmId": 7}, "companyProviderUid": "DUMMY_PROVIDER_UID", "members": [{"userId": 7, "role": "signer"}, {"userId": 8, "role": "assignee"}], "responsible": {"userId": 8, "role": "assignee"}, "files": [{"fileName": "VIBE-PROBE.pdf", "fileType": "application/pdf", "fileContent": "BASE64_FILE_BYTES"}], "externalSettings": {"externalId": "VIBE-PROBE-document-001", "externalDateCreate": "2026-11-13T12:00:00+00:00"}}})
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.error?.message);
console.log(result.data);
JavaScript — OAuth application
const response = await fetch('https://vibecode.bitrix24.com/v1/sign-b2e/documents/send', {
"method": "POST",
"headers": {
"X-Api-Key": "YOUR_APP_KEY",
"Authorization": "Bearer USER_SESSION_TOKEN",
"Content-Type": "application/json"
},
body: JSON.stringify({"fields": {"company": {"crmId": 7}, "companyProviderUid": "DUMMY_PROVIDER_UID", "members": [{"userId": 7, "role": "signer"}, {"userId": 8, "role": "assignee"}], "responsible": {"userId": 8, "role": "assignee"}, "files": [{"fileName": "VIBE-PROBE.pdf", "fileType": "application/pdf", "fileContent": "BASE64_FILE_BYTES"}], "externalSettings": {"externalId": "VIBE-PROBE-document-001", "externalDateCreate": "2026-11-13T12:00:00+00:00"}}})
});
const result = await response.json();
if (!response.ok || !result.success) throw new Error(result.error?.message);
console.log(result.data);
Response fields
| Field | Type | Description |
|---|---|---|
Fieldsuccess |
Typeboolean | DescriptionWhether the request succeeded. |
Fielddata |
Typeobject | DescriptionOperation data. |
Fielddata.uid |
Typestring | null | DescriptionDocument UID. |
Fielddata.state |
Typeobject | null | DescriptionObject state. |
Fielddata.state.code |
Typestring | null | DescriptionMachine-readable code. |
Fielddata.state.name |
Typestring | null | DescriptionLocalized signing state name. |
Fielddata.members |
Typearray | DescriptionDocument members. |
Fielddata.members[].uid |
Typestring | null | DescriptionSigning member UID. |
Fielddata.members[].role |
Typestring | null | DescriptionMember role. |
Fielddata.members[].state |
Typeobject | null | DescriptionObject state. |
Fielddata.members[].state.code |
Typestring | null | DescriptionMachine-readable code. |
Fielddata.members[].state.name |
Typestring | null | DescriptionLocalized signing state name. |
Fielddata.members[].user |
Typeobject | null | DescriptionThe member's user. |
Fielddata.members[].party |
Typeinteger | null | DescriptionThe member's signing party number. |
Fielddata.members[].user.employeeCode |
Typestring | null | DescriptionHCM Link employee code; null for a regular user. |
Fielddata.members[].user.employeeId |
Typeinteger | null | DescriptionNumeric HCM Link employee ID; null for a regular user. |
Fielddata.members[].user.userId |
Typeinteger | null | DescriptionUser ID. |
Fieldmeta.redacted |
Typearray | DescriptionPresent when credentials are hidden; contains the paths of the replaced values. |
Response example
Shape of a successful response; the data depends on the Bitrix24 account and the request.
{
"success": true,
"data": {
"uid": "DUMMY_DOCUMENT_UID",
"state": {
"code": "ready",
"name": "Ready"
},
"members": []
}
}
Error response example
403 — the key lacks a required scope:
{
"success": false,
"error": {
"code": "SCOPE_DENIED",
"message": "This endpoint requires 'sign.b2e' scope"
}
}
Errors
| HTTP | Code | Reason |
|---|---|---|
| HTTP400 | CodeINVALID_PARAMS |
ReasonInvalid request shape: types, required fields or an unknown query string parameter. |
| HTTP401 | CodeTOKEN_MISSING |
ReasonNo credentials for the Bitrix24 connection. |
| HTTP403 | CodeSCOPE_DENIED |
ReasonOne of the required scopes is not granted. |
| HTTP422 | CodeBITRIX_ERROR |
ReasonBitrix24 rejected the operation; the code is in error.b24Code, the text in error.message. |
| HTTP403 | CodeWRITE_BLOCKED_READONLY_KEY |
ReasonThe key is read-only. |
Known specifics
The signers, representatives, reviewer and editor fields are parsed by the DTO, but the send operation does not use them. HCM Link is checked only for company.uuid, members and responsible; the legacy fields do not select HCM employees and require no additional scope. Specify participants through members with the required role.
Bitrix24 checks user permissions, HR e-signature availability, business rules, page sizes and field contents. Values are passed through without local correction. Bitrix24 checks the fields marked as required; a missing business field results in a Bitrix24 rejection. Scalar fields accept numeric, boolean and null values; Bitrix24 converts them by its own rules. Response text is JSON-encoded; credential-bearing links are hidden.
The operation is not retried automatically. If the outcome is unknown, check the state in the Bitrix24 account first; resending can create another document.
The request body is limited to 40 MiB including Base64. The preliminary admission check for a large body can return 413 or 429. Participants are taken only from members; signers, representatives, reviewer and editor are not used for this.