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

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
	// contains filtered or unexported fields
}

func New

func New(cfg Config) *Client

type Config

type Config = config.Config

type Env

type Env = config.Env