Skip to Content
FastracDocs

Requests and responses

Hosts, headers, the response envelope, errors, pagination, IDs and units used by every endpoint.

Product
APIShipping Engine API
Section
Core concepts
Reading time
7 min read

In short

  • JSON over HTTPS. Every success is wrapped as { statusCode, message, data }; your payload is in data.
  • Errors are { statusCode, message, error }. message is a list when several fields fail validation.
  • Money is whole Rupiah, weight is grams, size is centimetres, and times without an offset are WIB.

Base URLs

EnvironmentAPI host
Sandboxhttps://sandbox-api.fastrac.example
Productionhttps://api.fastrac.example

Paths start directly after the host, for example https://api.fastrac.example/b2b/orders. There is no version prefix in the path. Always use https://. See Use the sandbox.

Headers

HeaderWhenValue
AuthorizationEvery authenticated callBearer <access_token>. See Authentication.
Content-TypeCalls with a bodyapplication/json
AcceptOptionalapplication/json

Request bodies can be up to 1 MB.

Success responses

Every successful response has the same envelope:

InboundResponse
{
  "statusCode": 200,
  "message": "Shipments retrieved.",
  "data": { "...": "..." }
}
FieldMeaning
statusCodeThe HTTP status, repeated in the body.
messageA short, human-readable result, for example Request successful. or Resource created successfully. Don't parse it.
dataThe result: an object, a list, or nothing for actions such as cancellations.

A list endpoint that finds nothing still returns 200, with an empty list. Region endpoints then say Request successful. data not found.

Errors

Errors have their own shape, without data:

InboundError
{
  "statusCode": 422,
  "message": "Insufficient balance.",
  "error": "InsufficientBalanceException"
}
FieldMeaning
statusCodeThe HTTP status.
messageWhat went wrong, as a string, or a list of strings for validation errors. Log it.
errorA short error name, such as Bad Request or InsufficientBalanceException.
codePresent on a few errors that you may want to handle in code, such as PICKUP_SCHEDULE_EXPIRED, PICKUP_SCHEDULE_NOT_QUOTED and SHIPPING_RATE_EXPIRED.

Validation errors

When the body or query fails validation, you get 400 and message is a list, one entry per problem. Each entry starts with the path of the field:

InboundError
{
  "statusCode": 400,
  "message": [
    "packages.0.weight must not be greater than 100000",
    "destinations.0.subdistrictId must be a number string"
  ],
  "error": "Bad Request"
}

Handle message as either a string or a list.

Unknown fields are dropped

Fields the endpoint doesn't know are silently removed before your request is processed. You get no error. A typo such as "insurence": true is therefore ignored, and you may get a different error about the field you meant, or a result you didn't expect. Check field names against the API reference.

Status codes

StatusMeaningRetry?
200Success.—
201Created, for example a rate or an order.—
400The request is invalid, or the action isn't possible. Read message.No. Fix the request.
401Missing, invalid or expired token.Once, with a new token.
403Your key's role lacks a permission, or the resource isn't yours.No.
404Not found, for example an unknown shipment or no courier for a route.No.
422Valid request, but not allowed now: for example a wrong state or a bad date range.No, until the cause is fixed.
500Unexpected error on our side.Reads: yes, with backoff. Orders: check first, see Go-live.

Full list of messages: Errors.

Pagination

List endpoints such as GET /b2b/shipments and GET /b2b/user-balance/logs use a cursor:

ParameterMeaning
limitItems per page. Default 25, maximum 100.
cursorLeave it out for the first page. For the next page, send the nextCursor from the previous response.

The response has nextCursor. When it is null, you have reached the last page. Treat the cursor as an opaque string: don't build or change it yourself, and keep the other filters the same between pages.

Region search (GET /b2b/region/find) works the same way, with a default limit of 20 (maximum 100).

This loop reads every delivered shipment from November 2026:

cursor=""
while :; do
  page=$(curl -s -G "$FASTRAC_API/b2b/shipments" \
    -H "Authorization: Bearer $FASTRAC_TOKEN" \
    --data-urlencode "status=DELIVERED" \
    --data-urlencode "startDate=2026-11-01T00:00:00+07:00" \
    --data-urlencode "endDate=2026-11-30T23:59:59+07:00" \
    --data-urlencode "limit=100" \
    ${cursor:+--data-urlencode "cursor=$cursor"})
  echo "$page" | jq -c '.data.shipments[] | {code, airwayBill, status}'
  cursor=$(echo "$page" | jq -r '.data.nextCursor // empty')
  [ -z "$cursor" ] && break
done

IDs

ObjectFormatExampleUse it to
Shipping rateSR- + 8 charactersSR-7KQ2M9XABook: shippingRateCode in POST /b2b/orders.
OrderFSO-YYMMDD-XXXXXXFSO-261120-A1B2C3Cancel every shipment in the order.
ShipmentSHP-YYMMDD-XXXXXXSHP-261120-K7Q2MXRead, track, cancel and simulate one shipment. Webhooks send it as shipment_code.
Airway billSet by the courierJX1234567890Track with the courier, or with GET /b2b/shipments/track/{code}. Can change: see shipment.airway_bill_updated.
SubdistrictNumeric string3174091001subdistrictId in rate requests.

Responses also contain numeric id fields. Store and use the codes above; they are what the endpoints take.

Units and formats

WhatFormatExample
MoneyWhole Rupiah, integer. No decimals.12984 = Rp 12.984
CurrencyAlways IDR"currency": "IDR"
WeightGrams800 = 0,8 kg
DimensionsCentimetres{ "length": 20, "width": 15, "height": 10 }
CoordinatesDecimal degrees-6.2297, 106.8536
Phone numbersIndonesian numbers081234567890 or +6281234567890
BooleansJSON true / false, not strings"insurance": false

Time

  • Send times in ISO 8601 with an offset, for example 2026-11-21T10:00:00+07:00. Times without an offset are read as WIB (Asia/Jakarta, UTC+7).
  • Responses return timestamps in ISO 8601, usually in UTC (2026-11-20T09:15:00.000Z). Convert them to WIB before showing them to Indonesian customers.
  • Business rules that depend on the clock, such as how far ahead a pickup must be booked, use WIB.
  • Webhook payloads use a different format. See Webhook events.

Message language

Response and error messages are mostly in English. A few come from Indonesian sources and are in Indonesian, for example some pickup schedule errors, courier status descriptions in shipment histories, and balance log descriptions such as Tagihan retur (RTS) resi …. Show your own text to end users, and use statusCode, error and code in your logic rather than the wording of message.

Was this page helpful?

On this page