Para agentes de IA: markdown desta página — /docs-content-en/entities/person-types.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Payer types

A list of payer types for an online store. The type ID is passed in the personTypeId field of an order or order property.

Types with the codes CRM_CONTACT and CRM_COMPANY are protected from deletion. Include name whenever you update a type, even if you are only changing other fields.

Bitrix24 API: sale.persontype.* Scope: sale

Create a payer type

POST /v1/person-types

Adds a payer type to the online store list for use in orders and order properties.

Pass fields at the root of the JSON object, without a fields wrapper.

Request body fields

Field Type Required Description
Fieldname Typestring Requiredyes DescriptionPayer type name
Fieldcode Typestring | null Requiredno DescriptionUnique code. Must differ from the code of any other type
Fieldsort Typenumber Requiredno DescriptionSort order
Fieldactive Typeboolean Requiredno DescriptionWhether the type is active
FieldxmlId Typestring | null Requiredno DescriptionExternal ID

For the full field list, see GET /v1/person-types/fields.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Documentation payer type",
  "code": "DOCS_PERSON_397F55D8FB1D",
  "xmlId": "DOCS_PERSON_397F55D8FB1D",
  "sort": 900,
  "active": false
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/person-types" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Documentation payer type",
  "code": "DOCS_PERSON_397F55D8FB1D",
  "xmlId": "DOCS_PERSON_397F55D8FB1D",
  "sort": 900,
  "active": false
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Documentation payer type',
    code: 'DOCS_PERSON_397F55D8FB1D',
    xmlId: 'DOCS_PERSON_397F55D8FB1D',
    sort: 900,
    active: false,
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/person-types', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Documentation payer type',
    code: 'DOCS_PERSON_397F55D8FB1D',
    xmlId: 'DOCS_PERSON_397F55D8FB1D',
    sort: 900,
    active: false,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success. The HTTP status is 201
Fielddata Typeobject DescriptionCreated payer type
Fielddata.id Typenumber DescriptionRO. Payer type ID
Fielddata.name Typestring DescriptionName
Fielddata.code Typestring | null DescriptionUnique code
Fielddata.sort Typenumber DescriptionSort order
Fielddata.active Typeboolean DescriptionWhether the type is active
Fielddata.xmlId Typestring | null DescriptionExternal ID

Response example

JSON 
{
  "success": true,
  "data": {
    "active": false,
    "code": "DOCS_PERSON_397F55D8FB1D",
    "id": 21,
    "name": "Documentation payer type",
    "sort": 900,
    "xmlId": "DOCS_PERSON_397F55D8FB1D"
  }
}

Error response example

422 — the code is already used by another payer type:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "person type code exists",
    "b24Code": "200750000005"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe name field is missing or empty
HTTP400 CodeREADONLY_FIELD DescriptionA read-only field was provided: id or lid
HTTP400 CodeINVALID_PARAMS DescriptionA scalar field received an object or array, such as an object in active
HTTP422 CodeBITRIX_ERROR DescriptionThe code is already in use. Message: person type code exists, b24Code: 200750000005
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected creation for another reason. The reason is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key owner lacks permission to modify payer types in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Error codes.

See also