Payload types

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.

PayloadTime

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

The two operating* counters are optional, and their absence is the normal state on a self-hosted portal rather than an edge case: the portal adds them only when the operating limiter is active, which on-premise reads the rest module option load_limiter_active — default N, and nothing in the product ever sets it. The SDK skips its operating-time bookkeeping in that case and does not invent a 0, which would be indistinguishable from a real "nothing consumed yet".

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
}

time is optional here, and coupled to SuccessPayload below: AjaxResult.getData() returns a SuccessPayload where the IResult contract expects a Payload, so this union member has to stay assignable from it.

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
}

BatchPayload / BatchPayloadResult

The whole HTTP body of a batch request: results, errors, totals, next-offsets and per-call timing, 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
}

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
}

result is always here, because a body with no result key is wrapped — the whole body becomes result rather than being dropped. time cannot be filled in the same way, so it is optional: guard before reading a field off it.

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>

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.