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

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

Invoices

CRM invoice management: create, retrieve, update, delete, filter. An invoice is a request for payment: it carries the payer, the seller company and the product rows, and its stage shows where the invoice stands in the issue-and-payment cycle.

Bitrix24 API: crm.item.*, entityTypeId equals 31 Scope: crm

Create invoice

POST /v1/invoices

Creates a new invoice in CRM.

Request fields (body)

Field Type Description
Fieldtitle Typestring DescriptionInvoice title. If omitted, Invoice #<id> is used
FieldstageId Typestring DescriptionStage. Format: DT31_{categoryId}:{stage}. Stage list: GET /v1/statuses?filter[entityId]=SMART_INVOICE_STAGE_{categoryId} — categoryId depends on the Bitrix24 account. To find it: GET /v1/invoices?limit=1&select=categoryId or ask your Bitrix24 account administrator
FieldcategoryId Typenumber DescriptionPipeline ID
FieldcontactId Typenumber DescriptionPayer contact ID. Lookup: GET /v1/contacts
FieldcompanyId Typenumber DescriptionPayer company ID. Lookup: GET /v1/companies
FieldmycompanyId Typenumber DescriptionID of your own company (the seller) issuing the invoice. Lookup: GET /v1/companies
Fieldopportunity Typenumber DescriptionInvoice amount
FieldcurrencyId Typestring DescriptionCurrency. List: GET /v1/currencies
FieldassignedById Typenumber DescriptionAssignee. List: GET /v1/users
Fieldbegindate Typedatetime DescriptionInvoice start date
Fieldclosedate Typedatetime DescriptionInvoice payment date
FieldaccountNumber Typestring DescriptionPrintable invoice number
Fieldcomments Typestring DescriptionComment

No fields are required: any single field is enough to create an invoice, and the rest are filled with the Bitrix24 account defaults. An empty body is rejected with 400 EMPTY_CREATE_BODY.

Full list of fields: GET /v1/invoices/fields. User fields (ufCrm_*) are also accepted. Pass invoice fields flat at the JSON root: an object under fields is rejected with 400 NESTED_FIELDS_ENVELOPE before creation.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/invoices \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice for services",
    "stageId": "DT31_5:N",
    "contactId": 42,
    "companyId": 15,
    "opportunity": 1500,
    "currencyId": "USD",
    "assignedById": 1
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/invoices \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice for services",
    "stageId": "DT31_5:N",
    "contactId": 42,
    "companyId": 15,
    "opportunity": 1500,
    "currencyId": "USD",
    "assignedById": 1
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Invoice for services',
    stageId: 'DT31_5:N',
    contactId: 42,
    companyId: 15,
    opportunity: 1500,
    currencyId: 'USD',
    assignedById: 1,
  }),
})

const { success, data } = await res.json()
console.log('Invoice ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/invoices', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: 'Invoice for services',
    stageId: 'DT31_5:N',
    contactId: 42,
    companyId: 15,
    opportunity: 1500,
    currencyId: 'USD',
    assignedById: 1,
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created invoice in full, including the ufCrm_* user fields. For every field see Invoice fields

The invoice card URL in Bitrix24 is built from id:

https://<portal>.bitrix24.com/crm/type/31/details/<id>/

31 — the entityTypeId of the smart invoice in Bitrix24. <portal> — the Bitrix24 portal domain. Access is restricted by the employee's permissions in Bitrix24.

Response example

Key fields are shown. For the full record see Invoice fields.

JSON 
{
  "success": true,
  "data": {
    "id": 129,
    "title": "Invoice for services",
    "stageId": "DT31_5:N",
    "categoryId": 5,
    "contactId": 42,
    "companyId": 15,
    "opportunity": 1500,
    "currencyId": "USD",
    "assignedById": 1,
    "createdBy": 1,
    "createdTime": "2026-08-25T08:13:37.000Z",
    "updatedTime": "2026-08-25T08:13:37.000Z"
  }
}

Error response example

400 — the request body is empty:

JSON 
{
  "success": false,
  "error": {
    "code": "EMPTY_CREATE_BODY",
    "message": "Request body is empty — provide at least one field to create smartInvoice."
  }
}

Errors

HTTP Code Description
HTTP400 CodeEMPTY_CREATE_BODY DescriptionThe request body is empty — at least one field is needed
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe body contains an object under fields instead of root-level fields; the request is rejected before creation
HTTP400 CodeREADONLY_FIELD DescriptionThe body carries a read-only field — id, createdBy, createdTime or any other field marked so in GET /v1/invoices/fields
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the crm scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

See also