# The Guide

#### Shiip API Integration Guide

Welcome to the Shiip API Integration Guide. This document will walk you through the process from account creation to booking shipments and configuring webhooks. Follow these steps to get started with our API:

***

**1. Account Creation**

1. [**Sign Up**](https://developer.goshiip.com/getting-started/authentication)
   * Navigate to the [Shiip Business Dashboard](https://business.goshiip.com).
   * Create an account by providing the necessary information.
2. [**Authenticate Your Account**](https://developer.goshiip.com/getting-started/authentication)
   * To access your dashboard, you need to authenticate your account. This requires completing the registration process.

***

**2. Fund Your Wallet**

1. [**Add Funds**](https://developer.goshiip.com/getting-started/wallet-funding)
   * Before booking a shipment, you must fund your wallet. Ideally, add an amount over 5000.
   * Enter the desired amount and proceed with payment via the Flutterwave payment screen that appears.
   * After a successful transaction, your Shiip wallet will be securely credited.

***

**3. Retrieve Available Couriers**

1. [**Get Courier List**](https://developer.goshiip.com/api-references/get-available-couriers)
   * Send a request to retrieve a list of available couriers based on your route type (`interstate`, `intrastate`, `international`, `frozen-international`, `international_us`, or `all`).
   * Example Endpoint: `https://delivery-staging.apiideraos.com/api/v2/token/`shipments/courier-partners/?type=all
   * Replace `{type}` with the relevant route type.

***

**4. Retrieve Rates**

1. [**Get Single Carrier Rate**](https://developer.goshiip.com/api-references/get-single-rate)
   * Use the endpoint to query rates for a specific carrier.
   * Example Endpoint: `https://delivery-staging.apiideraos.com/api/v2/token/tariffs/getpricesingle/{carrier_name}`
   * Replace `{carrier_name}` with the name of the carrier obtained from the previous step.
2. **Use of Endpoint**
   * This endpoint provides faster queries as rates are retrieved individually for each carrier, improving the user experience compared to the `allprice` endpoint.

[**Get Multiple Shipment Rate**](https://developer.goshiip.com/api-references/get-shipment-rates)

If it suits your system architecture, you can use this endpoint to retrieve all available rates in a single request. While it may be slightly slower than the [`Get Single Carrier Rate`](https://developer.goshiip.com/api-references/get-single-rate) endpoint, the choice between the two depends on your functional requirements and design.

***

**5. Book a Shipment**

1. [**Submit Shipping Details**](https://developer.goshiip.com/api-references/book-shipment)
   * Use the `book shipment` endpoint to submit your shipping details to the Shiip operations team.
   * After booking, your shipment will be attended to within 1-3 hours, depending on daily operational surges.

***

**6. Assign a Shipment**

1. [**Ready for Pickup**](https://developer.goshiip.com/api-references/assign-shipment)
   * Use the `assign shipment` endpoint to indicate that you are ready for pickup.
   * This triggers a queue on our end, and the operations team will reach out for any further questions.

***

**7. Cancel a Shipment**

1. [**Cancel Request**](https://developer.goshiip.com/api-references/cancel-shipment)
   * To cancel a shipment, use the `cancel shipment` endpoint.
   * Include the shipment reference in the request:
     * Example Endpoint: `https://delivery-staging.apiideraos.com/api/v2/token/shipment/cancel/{reference}`
   * Replace `{reference}` with the shipment reference you received upon booking.
   * Note: Canceling a shipment after it has been assigned can be complex and may incur additional fees.

***

**8. Track a Shipment**

1. [**Track Status**](https://developer.goshiip.com/api-references/track-shipment)
   * Use the `track shipment` endpoint to view the status of your shipment and obtain a detailed status breakdown with timestamps.

***

**9. Configure Webhooks**

1. [**Set Up Webhooks**](https://developer.goshiip.com/getting-started/webhook)
   * Webhooks enable automated communication between applications.
   * Configure a webhook URL in your application settings to receive event notifications.
2. [**Webhook Configuration**](https://developer.goshiip.com/getting-started/webhook)
   * Log in to our business web app.
   * Navigate to **Settings** > **API Settings** and update your webhook URL.
3. [**Webhook Details**](https://developer.goshiip.com/getting-started/webhook)
   * The endpoint should accept **POST** requests.
   * The webhook timeout is **30 seconds**. For heavy operations, consider handling them asynchronously.
   * Test your endpoint to ensure it correctly receives payloads.
4. [**Notification Frequency**](https://developer.goshiip.com/getting-started/webhook)
   * In production, webhooks are sent every **30 minutes**.
   * In Sandbox/Staging, webhooks are dispatched every **5 minutes**.

***

By following this guide, you will be able to effectively integrate with the Shiip API, manage your shipments, and configure your webhooks. For additional details or assistance, refer to the specific endpoint documentation or contact our support team.