> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grdd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start Guide

> Technical integration guide for GNet Platform API

## Overview

The GNet platform is an integration platform that connects ground transportation companies, dispatch/reservation systems, and other custom integrations. Members of GNet can send (farm-out) and/or receive (farm-in) reservations. In this process, the sending party (also known as the requester) and the receiving party (the provider) are key players in ensuring smooth reservation transactions.

<img src="https://mintcdn.com/gnet/phSKiVmS09wOnmYf/images/GNet-Diagram.svg?fit=max&auto=format&n=phSKiVmS09wOnmYf&q=85&s=4b038b6587f3042364098946768660f2" alt="GNet Platform Diagram" width="1960" height="1064" data-path="images/GNet-Diagram.svg" />

**Notes**:

* The requester and provider should establish a partnership in [GNet Connect](https://connect.grdd.net) before conducting business with each other to ensure proper integration and service delivery.
* For all API calls, you need to [get the token](#step-1-get-token) using your API Gateway user.
* Visit our [YouTube playlist](https://www.youtube.com/playlist?list=PLMOcutHcYhbI4RoQp8TAgl_RSI614Vgx4) for detailed integration tutorials and walkthroughs.
* For API reference: [GNet Platform API](/platform-api/overview).
* *For legacy Apiary reference: [GNet API on Apiary](https://gnet.docs.apiary.io/)*

<Card title="Interactive Setup Wizard" icon="wand-magic-sparkles" href="https://connect.grdd.net/products/gnet-platform/get-started">
  Prefer a guided experience? Try our interactive step-by-step wizard to see exactly how to connect to the GNet platform quickly and easily.
</Card>

### Authentication

* Platform API requests (e.g., `sendTrip`, `providerUpdateStatusByResNo`) require a `token` header obtained from [`getToken2`](#step-1-get-token).
* Your inbound Farm In endpoint should be protected (e.g., Basic Authentication using your issued API key/secret) and must accept JSON.

### Sign Up to GNet

*If you haven't already, please complete the Sign Up page.*

1. Visit and sign up: [https://connect.grdd.net/sign-up](https://connect.grdd.net/sign-up)
2. The GNet team will review and approve your account
3. API credentials will be provided upon approval

# Farm In (Receiving Reservations)

Please ask your technical team to create a webservice REST Endpoint (i.e. [https://api.example.com/api/gnet-farmin](https://api.example.com/api/gnet-farmin)) to accept POST requests with the following specifications:

### Request Format

* **Method**: POST
* **Headers**:
  * `content-type: application/json`
  * `Authorization: basic authentication (api_key/api_secret)`
* **Body**: JSON reservation payload ([see sample](https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/main/gnet-sample-reservation.json))

### Success Response

```json theme={null}
{
   "success": true,
   "reservationId": "11545-001",
   "totalAmount": "130.67",
   "transactionId": "<tx>"
}
```

### Error Response

```json theme={null}
{
   "success": false,
   "message": "Unable to process the request due to XYZ.",
   "transactionId": "<tx>"
}
```

## Reservation Status Updates

Send reservation updates such as confirmations and status changes (including `CONFIRMED`, `ASSIGNED`, `EN_ROUTE`, `ON_LOCATION`) to this endpoint:

**Endpoint**: `https://api.grdd.net/Platform.svc/providerUpdateStatusByResNo/{GRIDDID}/{RESNO}/{VERSION}`

Headers:

* `token: <from getToken2>`
* `Content-Type: application/json`

For example, to accept a booking request:

```json theme={null}
{
   "status": "CONFIRMED",
   "totalAmount": "120.00",
   "resNo": "<reservation_number>",
   "griddID": "<provider_griddid>"
}
```

For detailed documentation, see: [Provider Update Status API](https://api.grdd.net/Platform.svc/help/operations/providerUpdateStatusByResNo) and ( see other ASSIGNED payload [example](https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/main/gnet-sample-webhook.json))

<Note>
  * To see a list of all supported status codes, see [Status Codes](/platform-api/reference/status-codes)
  * To see a list of all supported vehicle types, see [Vehicle Types](/platform-api/reference/vehicle-types)
</Note>

## GPS Location Updates

[Update current location of drivers using this API](/connect-api/location/save-gps):

**Endpoint**: `POST https://location.grdd.net/api/GGPS.svc/saveGPScache`

Headers:

* `token: <from getToken2>`
* `Content-Type: application/json`

### Sample Payload

```json theme={null}
{
   "chfName": "Jane Doe",
   "driverId": "123456",
   "griddid": "{{providerId}}",
   "internalBookingId": "123456",
   "latitude": "40.74",
   "locationDateTime": "2024-01-23T18:52:34",
   "longitude": "-100.56",
   "phoneNo": "+15555555555",
   "transactionId": "<>"
}
```

Example curl:

```bash theme={null}
curl -X POST \
  "https://location.grdd.net/api/GGPS.svc/saveGPScache" \
  -H "token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chfName": "Jane Doe",
    "driverId": "123456",
    "griddid": "{{providerId}}",
    "internalBookingId": "123456",
    "latitude": "40.74",
    "locationDateTime": "2024-01-23T18:52:34",
    "longitude": "-100.56",
    "phoneNo": "+15555555555",
    "transactionId": "<>"
  }'
```

## Quote Requests

If the payload contains `reservationType` that is set to "QUOTE":

* Return the same payload structure as the Farm In success response
* Include `totalAmount` in the response
* You don't need to create a reservation record in your database for quotes

# Farm Out (Sending Reservations)

### Step 1: Get Token

```bash theme={null}
POST https://api.grdd.net/Platform.svc/getToken2
Content-Type: application/json

{
  "pw": "<password>",
  "uid": "<user_id>"
}
```

### Step 2: Send Reservation

```bash theme={null}
POST https://api.grdd.net/Platform.svc/sendTrip/v1
Headers:
  token: <from step 1>
  Content-Type: application/json

<your reservation json payload>
```

Example curl:

```bash theme={null}
curl -X POST \
  "https://api.grdd.net/Platform.svc/sendTrip/v1" \
  -H "token: $TOKEN" \
  -H "Content-Type: application/json" \
  -d @reservation.json
```

### Step 3: Register Callback Webhook

Register a callback webhook to receive reservation updates from providers. Your endpoint should:

* Accept POST requests
* Return 200 status code
* Process reservation updates
* A [sample payload](https://github.com/GRiDD/GRiDD.github.io/blob/main/gnet-sample-webhook.json) will be sent to your webhook URL

### Step 4: Send Booking Updates or Cancel Requests

#### Updates

Include `transactionId` in payload and set `affiliateReservation.action` to "UPDATE"

#### Cancel Request

```
POST cancelTripByTransactionId/{TRANSACTIONID}/{version}
```

For detailed documentation, see: [Cancel Trip API](https://api.grdd.net/Platform.svc/help/operations/cancelTripByTransactionId)

## Testing

### GBOOK Testing Utility

To test incoming trips, log in to the GBOOK utility:

* **User**: (use username/password provided by GNET)
* **URL**: [https://api.grdd.net/gbook](https://api.grdd.net/gbook)

#### Testing Steps:

1. Log in to GBOOK
2. Go to BOOK menu
3. Select `<griddid>` from the affiliate dropdown box
4. Fill in trip details and click BOOK
5. You will receive the trip in your system

**Note**: Click "SHOW JSON" to see the exact payload structure you need to submit to GNet.

### POSTMAN Collection

Download the complete collection: [GNET.postman\_collection.json](https://raw.githubusercontent.com/GRiDD/GRiDD.github.io/refs/heads/main/GNET.postman_collection.json)

#### Setup:

1. Import the collection
2. Set environment variables:
   * `token`
   * `requesterId`
   * `providerId`
3. Use the "Get Token" request first to obtain authentication token

## Health Check

We use the Farm In Adapter GET endpoint for health checks.

**Expected Response**:

* Status code: 200
* Body:

```json theme={null}
{
   "success": true
}
```

Example (assuming your Farm In endpoint is `https://api.example.com/api/gnet-farmin`):

```bash theme={null}
curl -X GET "https://api.example.com/api/gnet-farmin" -i
```

## Need Help?

<Card title="Contact Support" icon="headphones" href="mailto:support@grdd.net">
  Our support team is here to help you with integration questions and troubleshooting.
</Card>

<Card title="API Documentation" icon="book" href="/platform-api/overview">
  Complete API reference and detailed endpoint documentation.
</Card>