diff --git a/RAJAONGKIR_INTEGRATION.md b/RAJAONGKIR_INTEGRATION.md new file mode 100644 index 0000000..f24a012 --- /dev/null +++ b/RAJAONGKIR_INTEGRATION.md @@ -0,0 +1,204 @@ +# Rajaongkir Integration with WooNooW + +This guide explains how to bridge the Rajaongkir shipping plugin with WooNooW's admin order form and checkout flow. + +--- + +## The Challenge + +Rajaongkir doesn't use standard WooCommerce address fields. Instead of using `city` and `state`, it requires a **destination ID** from its own Indonesian location database. + +**Standard WooCommerce Flow:** +``` +Country → State → City → Postcode +``` + +**Rajaongkir Flow:** +``` +Country (ID) → Destination ID (subdistrict level) +``` + +--- + +## WooNooW Integration Hook + +WooNooW provides a hook that fires **before** shipping calculation. This allows plugins like Rajaongkir to set session variables or prepare any data they need. + +### Hook: `woonoow/shipping/before_calculate` + +```php +do_action( 'woonoow/shipping/before_calculate', $shipping_data, $items ); +``` + +**Parameters:** +- `$shipping_data` (array) - The shipping address from frontend: + - `country` - Country code (e.g., 'ID') + - `state` - State code + - `city` - City name + - `postcode` - Postal code + - `address_1` - Street address + - `address_2` - Additional address (optional) + - + Any custom fields added by addons +- `$items` (array) - Cart items being shipped + +--- + +## Code Snippet: Rajaongkir Bridge + +Add this code to your theme's `functions.php` or via a code snippets plugin: + +```php +session->__unset( 'selected_destination_id' ); + WC()->session->__unset( 'selected_destination_label' ); + return; + } + + // Check if destination_id is provided by frontend + if ( ! empty( $shipping['destination_id'] ) ) { + WC()->session->set( 'selected_destination_id', $shipping['destination_id'] ); + WC()->session->set( 'selected_destination_label', $shipping['destination_label'] ?? $shipping['city'] ); + return; + } + + // Fallback: Try to lookup destination from city name + // This requires the Rajaongkir database lookup + $destination = rajaongkir_lookup_destination( $shipping['city'], $shipping['state'] ); + if ( $destination ) { + WC()->session->set( 'selected_destination_id', $destination['id'] ); + WC()->session->set( 'selected_destination_label', $destination['label'] ); + } +}, 10, 2 ); + +/** + * Helper: Lookup Rajaongkir destination by city/state name. + * + * This is a simplified example. Implement based on your Rajaongkir data structure. + */ +function rajaongkir_lookup_destination( $city, $state ) { + // Query the Rajaongkir location database + // This depends on how your Rajaongkir plugin stores location data + + // Example using transient/option storage: + $locations = get_option( 'cekongkir_destinations', [] ); + + foreach ( $locations as $location ) { + if ( + stripos( $location['city'], $city ) !== false || + stripos( $location['district'], $city ) !== false + ) { + return [ + 'id' => $location['id'], + 'label' => $location['label'], + ]; + } + } + + return null; +} +``` + +--- + +## Frontend Integration (Optional) + +To add a proper Rajaongkir destination selector to WooNooW's admin order form, you need to: + +### 1. Register Custom Address Fields + +```php +add_filter( 'woonoow/checkout/address_fields', function( $fields ) { + // Only for Indonesia + if ( WC()->customer && WC()->customer->get_shipping_country() === 'ID' ) { + $fields['destination_id'] = [ + 'type' => 'hidden', + 'required' => true, + ]; + $fields['destination_selector'] = [ + 'type' => 'custom', + 'component' => 'RajaongkirDestinationSelector', + 'label' => __( 'Destination', 'woonoow-rajaongkir' ), + 'required' => true, + ]; + } + return $fields; +} ); +``` + +### 2. Enqueue JavaScript for Destination Search + +```php +add_action( 'woonoow/admin/enqueue_scripts', function() { + wp_enqueue_script( + 'woonoow-rajaongkir', + plugins_url( 'assets/js/woonoow-integration.js', __FILE__ ), + [ 'woonoow-admin' ], + '1.0.0', + true + ); + + wp_localize_script( 'woonoow-rajaongkir', 'WNW_RAJAONGKIR', [ + 'ajaxUrl' => admin_url( 'admin-ajax.php' ), + 'nonce' => wp_create_nonce( 'rajaongkir_search' ), + ] ); +} ); +``` + +--- + +## Testing + +1. Install and configure Rajaongkir plugin +2. Add the code snippet above +3. Go to WooNooW → Orders → Create New Order +4. Add a product +5. Set country to Indonesia +6. Fill in city/state (or use destination selector if implemented) +7. Click "Calculate Shipping" +8. Verify Rajaongkir rates appear + +--- + +## Troubleshooting + +### Rates not appearing? + +1. Check browser DevTools Network tab for `/shipping/calculate` response +2. Look for `debug` object in response: + ```json + { + "methods": [...], + "debug": { + "packages_count": 1, + "cart_items_count": 1, + "address": { ... } + } + } + ``` + +3. Verify Rajaongkir session is set: + ```php + error_log( 'destination_id: ' . WC()->session->get( 'selected_destination_id' ) ); + ``` + +### Session not persisting? + +Make sure WooCommerce session is initialized before the hook runs. The hook fires during REST API calls where session may not be initialized by default. + +--- + +## Related Documentation + +- [SHIPPING_INTEGRATION.md](SHIPPING_INTEGRATION.md) - General shipping integration guide +- [SHIPPING_METHOD_TYPES.md](SHIPPING_METHOD_TYPES.md) - Shipping method types explanation +- [Rajaongkir Plugin Documentation](https://cekongkir.com/docs) diff --git a/admin-spa/src/routes/Orders/partials/OrderForm.tsx b/admin-spa/src/routes/Orders/partials/OrderForm.tsx index 092bed4..df8219a 100644 --- a/admin-spa/src/routes/Orders/partials/OrderForm.tsx +++ b/admin-spa/src/routes/Orders/partials/OrderForm.tsx @@ -1126,16 +1126,13 @@ export default function OrderForm({