kiriminaja

README

KiriminAja Go SDK

Official Go SDK for the KiriminAja logistics API. Zero dependencies beyond the standard library.

Requirements

• Go 1.21+

Installation

go get github.com/kiriminaja/go

---

Quick Start

Create a client with kiriminaja.New(), then call any service method.

package main

import (
    "fmt"
    "log"
    "os"

    kiriminaja "github.com/kiriminaja/go"
)

func main() {
    client := kiriminaja.New(kiriminaja.Config{
        Env:    kiriminaja.EnvSandbox, // or kiriminaja.EnvProduction
        APIKey: os.Getenv("KIRIMINAJA_API_KEY"),
    })

    // Use any service
    provinces, err := client.Address.Provinces()
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Provinces: %+v\n", provinces)
}

---

Config Options

Option	Type	Default	Description
Env	Env	EnvSandbox	Target environment
APIKey	string	—	Your KiriminAja API key
BaseURL	string	Derived from Env	Override the base URL
HTTPClient	*http.Client	http.DefaultClient	Custom HTTP client (proxy / test mock)

// Custom base URL
client := kiriminaja.New(kiriminaja.Config{
    BaseURL: "https://tdev.kiriminaja.com",
    APIKey:  os.Getenv("KIRIMINAJA_API_KEY"),
})

// Custom HTTP client (e.g. with timeout or transport)
client := kiriminaja.New(kiriminaja.Config{
    APIKey: "...",
    HTTPClient: &http.Client{Timeout: 10 * time.Second},
})

---

Services

Address

// List all provinces
client.Address.Provinces()

// Cities in a province (provinsi_id)
client.Address.Cities(5)

// Districts in a city (kabupaten_id)
client.Address.Districts(12)

// Sub-districts in a district (kecamatan_id)
client.Address.SubDistricts(77)

// Search districts by name
client.Address.DistrictsByName("jakarta")

---

Coverage Area & Pricing

// Express shipping rates
client.CoverageArea.PricingExpress(types.PricingExpressPayload{
    Origin:      1,
    Destination: 2,
    Weight:      1000, // grams
    ItemValue:   50000,
    Insurance:   0,
    Courier:     []string{"jne", "jnt"},
})

// Instant (same-day) rates
client.CoverageArea.PricingInstant(types.PricingInstantPayload{
    Service:     []types.InstantService{types.InstantServiceGosend},
    ItemPrice:   10000,
    Origin:      types.PricingInstantLocationPayload{Lat: -6.2, Long: 106.8, Address: "Jl. Sudirman No.1"},
    Destination: types.PricingInstantLocationPayload{Lat: -6.21, Long: 106.81, Address: "Jl. Thamrin No.5"},
    Weight:      1000,
    Vehicle:     types.InstantVehicleBike,
    Timezone:    "Asia/Jakarta",
})

---

Order — Express

// Track by order ID
client.Order.Express.Track("ORDER123")

// Cancel by AWB
client.Order.Express.Cancel("AWB123456", "Customer request")

// Request pickup
client.Order.Express.RequestPickup(types.RequestPickupPayload{
    Address:     "Jl. Jodipati No.29",
    Phone:       "08133345678",
    Name:        "Tokotries",
    KecamatanID: 548,
    Schedule:    "2021-11-30 22:00:00",
    Packages: []types.RequestPickupPackage{
        {
            OrderID:                "YGL-000000019",
            DestinationName:        "Flag Test",
            DestinationPhone:       "082223323333",
            DestinationAddress:     "Jl. Magelang KM 11",
            DestinationKecamatanID: 548,
            Weight:                 520,
            Width:                  8,
            Length:                 8,
            Height:                 8,
            ItemValue:              275000,
            ShippingCost:           65000,
            Service:                "jne",
            ServiceType:            "REG23",
            COD:                    0,
            PackageTypeID:          7,
            ItemName:               "TEST Item name",
            // Items is optional. When provided, it lists the individual
            // items contained in the package. item_value is still required.
            Items: []types.RequestPickupItem{
                {
                    Name:   "Kaos Polos",
                    Price:  125000,
                    Qty:    2,
                    Weight: 260,
                    Width:  4,
                    Length: 4,
                    Height: 4,
                    Metadata: &types.RequestPickupItemMetadata{
                        SKU:          "KP-001",
                        VariantLabel: "Merah / L",
                    },
                },
            },
        },
    },
})

---

Order — Instant

// Create instant pickup
client.Order.Instant.Create(types.InstantPickupPayload{
    Service:     types.InstantServiceGosend,
    ServiceType: "instant",
    Vehicle:     types.InstantVehicleBike,
    OrderPrefix: "BDI",
    Packages: []types.InstantPickupPackage{
        {
            OriginName:             "Rizky",
            OriginPhone:            "081280045616",
            OriginLat:              -7.854584,
            OriginLong:             110.331154,
            OriginAddress:          "Wirobrajan, Yogyakarta",
            OriginAddressNote:      "Dekat Kantor",
            DestinationName:        "Okka",
            DestinationPhone:       "081280045616",
            DestinationLat:         -7.776192,
            DestinationLong:        110.325053,
            DestinationAddress:     "Godean, Sleman",
            DestinationAddressNote: "Dekat Pasar",
            ShippingPrice:          34000,
            Item: types.InstantPickupItem{
                Name:        "Barang 1",
                Description: "Barang 1 Description",
                Price:       20000,
                Weight:      1000,
            },
        },
    },
})

// Find a new driver for an existing order
client.Order.Instant.FindNewDriver("ORDER123")

// Cancel instant order
client.Order.Instant.Cancel("ORDER123")

// Track instant order
client.Order.Instant.Track("ORDER123")

---

Courier

// List available couriers
client.Courier.List()

// Courier groups
client.Courier.Group()

// Courier service detail
client.Courier.Detail("jne")

// Set whitelist services
client.Courier.SetWhitelistServices([]string{"jne_reg", "jne_yes"})

---

Pickup Schedules

client.Pickup.Schedules()

---

Payment

client.Payment.GetPayment("PAY123")

---

Credit

// Get the current KiriminAja credit balance
balance, err := client.Credit.Balance(ctx)
// balance.Data.Balance -> float64

---

AWB (Print Waybill)

// Print shipping label / waybill by AWB number(s)
res, err := client.AWB.Print(ctx, &types.PrintAWBRequest{
    AWB: []string{"AWB123", "AWB456"},
})
// res.Data.Data.URL -> PDF download URL

---

Calculations (COD)

// Calculate COD (Cash on Delivery) fee
res, err := client.Calculations.COD(ctx, &types.CalculateCODRequest{
    ItemPrice: 100000,
    Data: []types.CalculateCODDataItem{
        {
            CourierCode:        "jne",
            CourierServiceCode: "reg",
            ShippingCost:       10000,
        },
    },
})
// res.Results -> slice of fee breakdown per courier/service

---

Profile

// Get member profile and metadata
res, err := client.Profile.Get(ctx)
// res.Results.ID, res.Results.Email, res.Results.Name, res.Results.Metadata

Preferences

// Set the merchant callback used for tracking notifications.
res, err := client.Preference.SetCallback(ctx, "https://example.com/kiriminaja/callback")

// Configure courier preferences (also available through client.Courier).
res, err := client.Preference.SetWhitelistServices(ctx, []string{"jne", "jnt"})

Callback URLs must be absolute HTTP(S) URLs; whitelist entries must be non-empty.

Full express pricing

// Request all rates without sending optional courier/insurance filters.
res, err := client.CoverageArea.FullShippingPrice(ctx, types.FullShippingPricePayload{
    Origin: 548,
    Destination: 539,
    Weight: 1000,
})

Profile and credit response compatibility

Profile.Get normalizes results, result, data, and unwrapped profile responses into res.Results. Credit.Balance normalizes results, result, data, payload, and top-level balances into res.Data.Balance, including numeric strings and zero balances. Both accept successful responses without an explicit status, use message when text is missing, and accept numeric or string response codes without changing their public string fields.

Successful responses with missing profile data or missing/non-numeric balances return an error rather than silently returning empty values. As with other SDK services, an explicit API status: false remains a response with Status == false (and the server's message in Text); callers should check both err and Status. Non-2xx HTTP responses continue to return *http.APIError.

Utilities — Volumetric

Estimate the smallest bounding box (WxLxH) for a multi-item package by trying vertical / horizontal / side-by-side stacking and returning the arrangement with the smallest volume.

import "github.com/kiriminaja/go/utils/volumetric"

dim := volumetric.Calculate([]volumetric.Item{
    {Qty: 2, Length: 10, Width: 10, Height: 2},
    {Qty: 1, Length: 5,  Width: 5,  Height: 5},
})
// dim.Length, dim.Width, dim.Height

---

Development

go build ./...   # build all packages
go test ./...    # run tests

Documentation

Index

• Constants
• type Client
  • func New(cfg Config) *Client
• type Config
• type Env

Constants

const (
	EnvSandbox    = config.EnvSandbox
	EnvProduction = config.EnvProduction
)

Types

type Client

type Client struct {
	Address      *address.Service
	AWB          *awb.Service
	Calculations *calculations.Service
	Courier      *courier.Service
	CoverageArea *coveragearea.Service
	Credit       *credit.Service
	Order        *order.Service
	Payment      *payment.Service
	Pickup       *pickup.Service
	Profile      *profile.Service
	Preference   *preference.Service
	// contains filtered or unexported fields
}

func New

func New(cfg Config) *Client

type Config

type Config = config.Config

type Env

type Env = config.Env