v2.0.0

Payload types

The REST response envelope — PayloadTime, GetPayload, ListPayload, BatchPayload, SuccessPayload, and the Payload union, with a note on the v2 vs v3 envelope status.
payloads
auth (error envelopes)

The types in types/payloads.ts model the JSON envelope Bitrix24 wraps around every REST response. Most application code never touches these directly — the actions.v{2,3}.* helpers unwrap them and hand you SuccessPayload via AjaxResult.getData(). They are documented here because they are re-exported from @bitrix24/b24jssdk and describe the raw wire shape.

The Bitrix24 REST API always wraps a successful response in { result, time } — this holds for both restApi:v2 and restApi:v3. The differences below are confined to the list and batch envelopes, whose extra pagination fields are v2-only.

PayloadTime

The timing block attached to every response envelope. Present on both v2 and v3.

type PayloadTime = {
  readonly start: number
  readonly finish: number
  readonly duration: number
  readonly processing: number
  readonly date_start: ISODate
  readonly date_finish: ISODate
  readonly operating_reset_at: number  // timestamp when part of the method limit is released
  readonly operating: number           // execution time counted against the method limit
}

GetPayload

The envelope for a single-item read — the common { result, time } shape.

type GetPayload<P> = {
  readonly result: P
  readonly time: PayloadTime
}

ListPayload

The envelope for a v2 list method. total and next are the v2 offset-pagination fields.

type ListPayload<P> = {
  readonly result: P[]
  readonly total: number
  readonly next?: number
  readonly time: PayloadTime
}
total and next are v2-only. restApi:v3 uses cursor-based paging and has no direct counterpart for them in the same envelope. In source, ListPayload still carries a @todo ! add api3 marker — the v3 list envelope variant is not yet modelled as a distinct type. You should not need it: actions.v{2,3}.callList / fetchList walk pages internally, so consumers read the aggregated result, not next / total.

BatchPayload / BatchPayloadResult

The envelope for a batch request. Results, errors, totals, next-offsets, and per-call timing are keyed either by the caller's command keys or positionally.

type BatchPayloadResult<C> = {
  readonly result:
    | { readonly [P in keyof C]?: C[P] }
    | ReadonlyArray<C[keyof C]>
  readonly result_error:
    | { readonly [P in keyof C]?: string }
    | readonly string[]
  readonly result_total:
    | { readonly [P in keyof C]?: number }
    | readonly number[]
  readonly result_next:
    | { readonly [P in keyof C]?: number }
    | readonly number[]
  readonly result_time:
    | { readonly [P in keyof C]?: PayloadTime }
    | readonly PayloadTime[]
}

type BatchPayload<C> = {
  readonly result: BatchPayloadResult<C>
  readonly time: PayloadTime
}
BatchPayloadResult describes the v2 batch envelope and carries a @todo ! add api3 marker in source; the v3 batch variant is not yet modelled here. Prefer actions.v{2,3}.batch / batchByChunk, which parse this envelope for you.

SuccessPayload

The public shape of a successful response, as returned by AjaxResult.getData(). This is the type most consumers actually see.

type SuccessPayload<P> = {
  readonly result: P
  readonly time: PayloadTime
}

SuccessPayload is intentionally the common { result, time } shape — identical for v2 and v3. The v2-only list fields (next, total) are deliberately excluded: they have no restApi:v3 counterpart, and the SDK's callList / fetchList helpers handle pagination internally, so consumers never read them off the envelope.

Payload

The full discriminated envelope a raw response can be — either an error description (v2 or v3) or one of the success envelopes above.

type Payload<P> =
  | TypeDescriptionErrorV3   // v3 error envelope
  | TypeDescriptionError     // v2 error envelope
  | GetPayload<P>
  | ListPayload<P>
  | BatchPayload<P>
Payload carries a @todo ! add api3 tail / add / update and etc marker in source: the v3-specific success variants (tail paging, add/update responses) are still being filled in. The error arms already model both versions — TypeDescriptionError (v2) and TypeDescriptionErrorV3 (v3), both defined in types/auth.ts.

Related

  • IResult / AjaxResult — AjaxResult.getData() returns SuccessPayload<T> on success.
  • AjaxResult — decodes the raw Payload envelope, including the error arms.
  • Common types — ISODate and the scalar aliases used inside these envelopes.