Connecting a custom integration to Aide
info:
title: Order & Customer Management Integration API
version: '1.0.0'
description: |
Specification for integrating order and customer management platforms with Aide AI.
This API defines the minimum required endpoints and data structures
while allowing flexibility in implementation details.
Aide AI will poll these endpoints regularly (approximately once per minute)
to sync order and customer data.
servers:
- url: https://api.{platform}.com/v1
variables:
platform:
default: yourplatform
description: Your platform's API domain
paths:
/latest_orders:
get:
summary: List most recently updated orders
description: |
Retrieve the most recently updated orders, sorted by last update time in descending order.
This endpoint will be polled approximately once per minute by Aide AI to detect changes.
Implementation must provide at least the order ID and last update time.
parameters: - in: query
name: page_size
schema:
type: integer
minimum: 1
maximum: 100
default: 50
required: false
description: Number of orders to return per page - in: query
name: page_token
schema:
type: string
required: false
description: Token for pagination. Can be implemented as cursor or page number
responses:
'200':
description: Successfully retrieved orders
content:
application/json:
schema:
type: object
required: - orders
properties:
orders:
type: array
items:
$ref: '#/components/schemas/OrderSummary'
next_page_token:
type: string
description: Token for retrieving the next page of results
/orders/{orderId}:
get:
summary: Get order details
description: Retrieve detailed information about a specific order
parameters: - name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully retrieved order details
content:
application/json:
schema:
$ref: '#/components/schemas/OrderDetail'
'404':
description: Order not found
/customers/{customerId}:
get:
summary: Get customer details
description: Retrieve detailed information about a specific customer
parameters: - name: customerId
in: path
required: true
schema:
type: string
responses:
'200':
description: Successfully retrieved customer details
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerDetail'
'404':
description: Customer not found
components:
schemas:
OrderSummary:
type: object
required: - id - updated_at
properties:
id:
type: string
description: Unique identifier for the order
updated_at:
type: string
format: date-time
description: Time the order was last updated # Additional optional fields can be included
OrderDetail:
type: object
required:
- id
- created_at
- total_amount
properties:
id:
type: string
description: Unique identifier for the order
display_id:
type: string
description: Human-readable order identifier (e.g., order number, confirmation number)
created_at:
type: string
format: date-time
description: Time the order was placed
updated_at:
type: string
format: date-time
description: Time the order was last updated
total_amount:
type: number
format: float
description: Total amount for the order
currency:
type: string
description: Currency code (e.g., USD, EUR)
canceled_at:
type: string
format: date-time
nullable: true
description: Time the order was canceled, if applicable
customer_id:
type: string
description: ID of the customer who placed the order
status:
type: string
description: Current status of the order
billing_address:
type: object
description: |
Billing address as a JSON object. Common fields include:
- address1: Primary street address
- address2: Secondary street address (apt, suite, etc)
- city: City name
- province/state: Province or state
- zip/postal_code: ZIP or postal code
- country: Country code (e.g., US, GB)
You may include additional fields as needed for your platform
# Additional fields can be included
CustomerDetail:
type: object
required:
- id
properties:
id:
type: string
description: Unique identifier for the customer
first_name:
type: string
last_name:
type: string
email:
type: string
format: email
phone:
type: string
country:
type: string
description: Country code (e.g., US, GB)
billing_address:
type: object
description: |
Billing address as a JSON object. Common fields include:
- address1: Primary street address
- address2: Secondary street address (apt, suite, etc)
- city: City name
- province/state: Province or state
- zip/postal_code: ZIP or postal code
- country: Country code (e.g., US, GB)
You may include additional fields as needed for your platform
# Additional fields can be included
securitySchemes:
ApiKeyAut```
---