Your First Request

This guide walks you through making your first API call to the Gateway. We’ll list available services as a practical example.

Prerequisites

✅ Obtained an access token
✅ Gateway URL (<GATEWAY_URL>)
✅ Token stored securely

Example: List Available Services

Services represent the e-commerce platforms available for integration (Shopify, Amazon, WooCommerce, etc.).

Request

curl -X GET https://<GATEWAY_URL>/api/2.0/app/services \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "data": [
    {
      "id": 1,
      "name": "Shopify",
      "type": "SHOPIFYV2",
      "logo": "https://<GATEWAY_URL>/storage/logos/shopify.png",
      "description": "Connect your Shopify store",
      "oauth_required": true,
      "active": true
    },
    {
      "id": 2,
      "name": "Amazon Seller Central",
      "type": "amazon",
      "logo": "https://<GATEWAY_URL>/storage/logos/amazon.png",
      "description": "Sync orders from Amazon",
      "oauth_required": true,
      "active": true
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 2,
    "per_page": 15,
    "total": 2,
    "last_page": 1
  }
}

Understanding the Response

Data Array

Contains the list of service objects with:

id - Unique service identifier
name - Human-readable service name
type - Service type identifier (used in code)
logo - URL to service logo
oauth_required - Whether OAuth2 flow is needed for installation
active - Service availability status

Meta Object

Pagination information:

current_page - Current page number
total - Total number of items
per_page - Items per page
last_page - Total number of pages

More Examples

Get Specific Service

curl -X GET https://<GATEWAY_URL>/api/2.0/app/services/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response:

{
  "data": {
    "id": 1,
    "name": "Shopify",
    "type": "SHOPIFYV2",
    "configuration": {
      "params": [
        {
          "name": "name",
          "type": "text",
          "label": "Integration Name",
          "required": true
        },
        {
          "name": "shop",
          "type": "text",
          "label": "Shop URL",
          "placeholder": "your-store.myshopify.com",
          "required": true
        }
      ],
      "resources": [
        {
          "name": "get_orders",
          "label": "Orders",
          "schedulable": true
        },
        {
          "name": "update_tracking",
          "label": "Update Tracking",
          "schedulable": true
        },
        {
          "name": "sync_inventory",
          "label": "Sync Inventory",
          "schedulable": true
        }
      ]
    }
  }
}

List Your Integrations

curl -X GET https://<GATEWAY_URL>/api/2.0/app/integrations \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response:

{
  "data": [
    {
      "id": 42,
      "name": "My Shopify Store",
      "service_id": 1,
      "service": {
        "name": "Shopify",
        "type": "SHOPIFYV2"
      },
      "configuration": {
        "shop": "mystore.myshopify.com",
        "filter": {}
      },
      "gateway_key": "abc123xyz",
      "status": "ACTIVE",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total": 1
  }
}

Common HTTP Methods

The Gateway API uses standard HTTP methods:

Method	Usage	Example
`GET`	Retrieve resources	List integrations, get service details
`POST`	Create resources	Create account, execute integration action
`PUT`	Update resources	Update integration configuration
`PATCH`	Partial update	Change integration status
`DELETE`	Delete resources	Remove integration

Working with Pagination

For endpoints returning lists, use pagination parameters:

curl -X GET "https://<GATEWAY_URL>/api/2.0/app/integrations?page=2&per_page=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Query Parameters:

page - Page number (default: 1)
per_page - Items per page (default: 15, max: 100)

Handling Errors

401 Unauthorized

{
  "message": "Unauthenticated."
}

Solution: Token expired or invalid. Refresh your token.

404 Not Found

{
  "message": "No query results for model [App\\Models\\Service] 999"
}

Solution: Resource with ID 999 doesn’t exist. Verify the ID.

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ]
  }
}

Solution: Fix validation errors in your request payload.

Next Steps

Now that you’ve made your first request:

Explore Each Function:
Learn About Integration Management:
For Developers:
- Create custom integrations
- Understand data mapping
Interactive Documentation:
- Swagger API Docs