Schemas

AppId

string

Application ID issued in the Apaczka panel (API settings).

Expires

integer

Unix timestamp until which the request is valid. At most 15 minutes in the future (the Postman collection uses now + 900 s).

Example: 1752994800

Signature

string · pattern: ^[0-9a-f]{64}$

Lowercase-hex HMAC-SHA256 of app_id + ":" + route + ":" + request + ":" + expires keyed with your app_secret, where route is the method path including path parameters and trailing slash (e.g. order_send/, waybill/123456/).

EmptyPayload

This method takes no payload — send an empty JSON object (`{}`).

ResponseEnvelope

Universal response envelope. HTTP status is always 200; `status` carries the real outcome.

status

integer · required

Application-level status — 200 means success, anything else is an error code.

message

string · required

Human-readable error message (empty on success).

Method-specific result. null on failure.

PointsPayload

country_code

string

ISO 3166-1 alpha-2 country code.

Example: PL

subtype

string

Optional point subtype filter.

OrdersListPayload

page

integer · min: 1

limit

integer

TurnInPayload

order_ids

integer[] · required

Orders to include in the collective turn-in document.

PickupPayload

date

string · date · required

Pickup date (check availability via pickup_hours first).

Example: 2026-07-21

hour_from

string · required

hour_to

string · required

BatchPickupPayload

order_ids

integer[] · required

Orders to pick up — same sender address and service required.

date

string · date · required

hour_from

string · required

hour_to

string · required

PickupHoursPayload

postal_code

string · required

service_id

integer · required

Service ID from the service structure dictionary.

Example: 65

remove_index

boolean

Default: false

OrderPayload

Payload shared by order valuation and order creation. For international shipments with customs clearance additional fields apply.

object · required

Address

name

string · required

line1

string · required

postal_code

string · required

city

string · required

country_code

string · required

ISO 3166-1 alpha-2 country code.

Example: PL

line2

string

state_code

string

Region/state code — required for some countries (e.g. US).

Example: NY

is_residential

boolean

Default: false

contact_person

string

email

string · email

phone

string

Parcel

dimension1

integer · required

Length in cm.

Example: 10

dimension2

integer · required

Width in cm.

Example: 10

dimension3

integer · required

Height in cm.

Example: 10

weight

number · required

Weight in kg.

Example: 1

is_nstd

integer

Non-standard parcel flag (0/1).

Default: 0

object[]

Customs item declaration (international shipments).

PushTrackingNotification

Body of the push-tracking webhook POSTed to `push_tracking_url` (or to the WebAPI app's default tracking webhook URL) on every status change. Not an endpoint you call — your server receives it. Verify `signature` before processing: HMAC-SHA256 over `{app_id}::{json}:`, where `{json}` is `response` encoded with `JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_LINE_TERMINATORS`, keyed with the `app_secret` of the WebAPI app that created the order. Respond with HTTP 200 — otherwise the notification is redelivered.

signature

string · required

Hex-encoded HMAC-SHA256 signature of response.

object · required

ResponseEnvelope

Universal response envelope. HTTP status is always 200; `status` carries the real outcome.

status

integer · required

Application-level status — 200 means success, anything else is an error code.

message

string · required

Human-readable error message (empty on success).

Method-specific result. null on failure.

Address

name

string · required

line1

string · required

postal_code

string · required

city

string · required

country_code

string · required

ISO 3166-1 alpha-2 country code.

Example: PL

line2

string

state_code

string

Region/state code — required for some countries (e.g. US).

Example: NY

is_residential

boolean

Default: false

contact_person

string

email

string · email

phone

string

Parcel

dimension1

integer · required

Length in cm.

Example: 10

dimension2

integer · required

Width in cm.

Example: 10

dimension3

integer · required

Height in cm.

Example: 10

weight

number · required

Weight in kg.

Example: 1

is_nstd

integer

Non-standard parcel flag (0/1).

Default: 0

object[]

Customs item declaration (international shipments).

PushTrackingNotification

signature

string · required

Hex-encoded HMAC-SHA256 signature of response.

object · required