YZ ajanları için: bu sayfanın markdown'ı — /docs-content-en/sign-b2e/send-document.md dokümantasyon dizini — /llms.txt

Dokümantasyon makaleleri şu anda İngilizce olarak mevcuttur.

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

Terminal
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

Terminal
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

javascript
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

javascript
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.

JSON
{
  "success": true,
  "data": {
    "uid": "DUMMY_DOCUMENT_UID",
    "state": {
      "code": "ready",
      "name": "Ready"
    },
    "members": []
  }
}

Error response example

403 — the key lacks a required scope:

JSON
{
  "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.

Common API errors.

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.

See also