Skip to Content
FastracDocs

Quickstart

Ship your first order in the sandbox in about 10 minutes, from rate to delivery.

Product
APIShipping Engine API
Section
Get started
Reading time
9 min read

By the end of this page you will have priced a parcel from Jakarta to Bandung, booked it, marked it delivered, and seen its tracking history. This is the whole flow your integration will follow.

You need: a Fastrac business account with an API key, a terminal, and some sandbox balance. All requests go to the sandbox, so no courier is sent and your real balance is not used.

  1. Get your API credentials

    In the Fastrac dashboard, open API Integration in the side menu. Your key, under API Credentials Configuration, has three parts:

    ValueUse
    keyIdYour OAuth client_id. The same for sandbox and production.
    sandboxSecretThe client_secret for the sandbox.
    secretThe client_secret for production. Keep it for go-live.

    Treat secrets like passwords

    Copy the secrets into a secret manager or environment variables, never into source code. Anyone in your organisation who can open API Integration can see them. If a secret may have leaked, ask support to rotate the key. API keys are issued once your business verification (KYC) is approved.

    Save them as environment variables so you can copy the commands below unchanged:

    export FASTRAC_CLIENT_ID="your-key-id"
    export FASTRAC_CLIENT_SECRET="your-sandbox-secret"
    export FASTRAC_API="https://sandbox-api.fastrac.example"
    export FASTRAC_TOKEN_URL="https://sandbox-auth.fastrac.cc/realms/users/protocol/openid-connect/token"
  2. Get an access token

    Exchange your credentials for a short-lived access token using the standard OAuth2 client-credentials grant:

    curl -s -X POST "$FASTRAC_TOKEN_URL" \
      -d grant_type=client_credentials \
      -d client_id="$FASTRAC_CLIENT_ID" \
      -d client_secret="$FASTRAC_CLIENT_SECRET"
    InboundResponse
    {
      "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
      "expires_in": 300,
      "token_type": "Bearer"
    }
    export FASTRAC_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6..."

    Reuse the token

    Cache the token and reuse it until expires_in seconds have passed, then request a new one. Don't request a token for every API call.

  3. Look up the two regions

    Every address needs a subdistrictId. Search by name or postal code. This endpoint needs no token.

    curl -s "$FASTRAC_API/b2b/region/find?keyword=tebet%20barat"
    InboundResponse
    {
      "statusCode": 200,
      "message": "Request successful.",
      "data": {
        "regions": [
          { "id": "3174091001", "name": "Tebet Barat, Tebet, Kota Jakarta Selatan, DKI Jakarta", "postCode": 12810 }
        ],
        "nextCursor": null
      }
    }

    Do the same for the destination (keyword=braga bandung). In this guide we use 3174091001 for the origin and 3273011003 for the destination.

    In your app

    Run this search behind an address autocomplete, and save the chosen id with the customer's address. Then you never have to look it up again.

  4. Request shipping rates

    Ask every regular courier for a price at once by setting courierCode to REGULAR:

    curl -s -X POST "$FASTRAC_API/b2b/shipping-rate" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "origin":       { "fullAddress": "Jl. Tebet Raya No. 12, Jakarta Selatan", "subdistrictId": "3174091001" },
        "destinations": [{ "fullAddress": "Jl. Braga No. 8, Kota Bandung",         "subdistrictId": "3273011003" }],
        "courierCode": "REGULAR",
        "insurance": false,
        "packages": [{
          "itemValue": 250000,
          "isGlassware": false,
          "weight": 800,
          "dimension": { "length": 20, "width": 15, "height": 10 }
        }]
      }'
  5. Read the result

    You get one rate per courier service that can carry the parcel. Shortened:

    InboundResponse (trimmed)
    {
      "statusCode": 201,
      "message": "Shipping rate created successfully.",
      "data": [
        {
          "shippingRateCode": "SR-7KQ2M9XA", 
          "validUntil": "2026-11-20T09:15:00.000Z", 
          "courierCode": "JNE",
          "serviceName": "JNE Reguler",
          "serviceType": "REGULAR",
          "etdRange": "2 - 3 Days",
          "isSupportCod": true,
          "priceDetail": {
            "fastracPrice": 9000,
            "totalPrice": 9099, 
            "currency": "IDR"
          }
        }
      ]
    }

    Three fields matter most:

    • totalPrice is what you will pay. Show this to your customer.
    • shippingRateCode identifies this exact quote. You pass it to POST /b2b/orders to book.
    • validUntil is when the quote expires, usually about 15 minutes later. After that, request a new rate.

    Pick a rate with "isSupportDropOff": true and copy its shippingRateCode for the next step.

  6. Create an order

    Book the rate. You only add who sends and who receives; the route, parcel and price come from the rate. We use drop-off here, so the sender doesn't need map coordinates.

    curl -s -X POST "$FASTRAC_API/b2b/orders" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "shipments": [{
          "shippingRateCode": "SR-7KQ2M9XA",
          "sender":    { "name": "Toko Maju", "email": "[email protected]", "phoneNumber": "081234567890" },
          "receivers": [{
            "name": "Budi Santoso", "phoneNumber": "081298765432",
            "addressNote": "Rumah pagar hijau", "label": "Rumah", "stopSequence": 1
          }],
          "shippingOptions": { "fulfillmentMethod": "DROPOFF" }
        }]
      }'

    Shipping Engine pays for the shipment from your (sandbox) balance and books the courier in the same call:

    InboundResponse (trimmed)
    {
      "statusCode": 201,
      "message": "Resource created successfully.",
      "data": {
        "code": "FSO-261120-A1B2C3",
        "status": "CONFIRMED",
        "price": { "amount": 9099, "currency": "IDR" },
        "shipments": [
          {
            "code": "SHP-261120-K7Q2MX", 
            "courierCode": "JNE",
            "status": "PENDING_DROPOFF", 
            "fulfillmentMethod": "DROPOFF",
            "airwayBill": "JX1234567890", 
            "trackingUrl": "https://…"
          }
        ]
      }
    }

    Save the shipment code:

    export SHIPMENT="SHP-261120-K7Q2MX"

    Don't retry blindly

    Each successful call books and pays for a new shipment. If a request times out, check GET /b2b/shipments before sending it again. See Go-live checklist.

  7. Simulate delivery

    In production the courier reports progress. In the sandbox you trigger it yourself:

    curl -s -X POST "$FASTRAC_API/b2b/shipments/$SHIPMENT/simulate-status" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "status": "DELIVERED" }'
    InboundResponse
    {
      "statusCode": 200,
      "message": "Shipment status simulated successfully."
    }

    If you have registered a sandbox webhook, it now receives a shipment.delivered event. Other values, such as TRANSIT, CANCELLED and RTS, are listed in Use the sandbox.

  8. See it tracked

    Read the shipment back:

    curl -s "$FASTRAC_API/b2b/shipments/$SHIPMENT/details" \
      -H "Authorization: Bearer $FASTRAC_TOKEN"
    InboundResponse (trimmed)
    {
      "statusCode": 200,
      "message": "Shipment detail retrieved.",
      "data": {
        "code": "SHP-261120-K7Q2MX",
        "orderCode": "FSO-261120-A1B2C3",
        "status": "DELIVERED", 
        "airwayBill": "JX1234567890",
        "shippingRateCode": "SR-7KQ2M9XA",
        "histories": [
          { "status": "PENDING_DROPOFF", "description": "…", "timestamp": "2026-11-20T09:03:12.000Z" },
          { "status": "DELIVERED", "description": "Paket telah diterima (Simulasi B2B)", "timestamp": "2026-11-20T09:05:40.000Z" }
        ]
      }
    }

    That's the full loop: region → rate → order → tracking. Your integration does the same, with webhooks telling you when the status changes.

Next steps

Was this page helpful?

On this page