This guide walks you through placing a test order in GelatoConnect using Postman, a popular API testing tool. This is useful for testing your integration, validating order workflows, and troubleshooting API issues.
Prerequisites
Before you begin, ensure you have:
Postman installed on your computer (available at postman.com)
A GelatoConnect account with API access
A connector set up for your customer in GelatoConnect
Step 1: Set Up Your Connector in GelatoConnect
First, you need to create or access an existing connector:
Log in to GelatoConnect and navigate to Workflow > Order Intake > Connectors
Select API Connector and Select your customer from the list or create a new customer if needed
Click on the connector you want to use for testing
Copy the following information:
Submit Order Endpoint: The full URL for submitting orders
X-API-KEY: Your authentication credentials (in the format
key:secret)
Step 2: Configure Postman
Now set up your API request in Postman:
Set the Request Method and URL
Open Postman and create a new request
Set the method to POST
Paste your Submit Order Endpoint into the URL field
Add Authentication Header
Click on the Headers tab
Add a new header:
Key:
X-API-KEYValue: Paste your copied API key (it should look like
your-key:your-secret)
Add Content-Type header:
Key:
Content-TypeValue:
application/json
Step 3: Create Your Order Body
Switch to the Body tab in Postman and select raw and JSON format. Here's a basic test order example:
{
"orderReferenceId": "TEST-ORDER-001",
"orderType": "order",
"currency": "USD",
"shippingAddress": {
"country": "US",
"firstName": "Test",
"lastName": "Customer",
"addressLine1": "123 Test Street",
"city": "Test City",
"postCode": "12345",
"state": "CA",
"email": "[email protected]",
"phone": "555-123-4567"
},
"items": [
{
"itemReferenceId": "TEST-ITEM-001",
"productUid": "flat_product_pf_a4_pt_200-gsm-uncoated_cl_4-0_ct_none_prt_none_sft_none_set_none_hor",
"quantity": 1,
"files": [
{
"type": "default",
"url": "https://example.com/path/to/test-file.pdf"
}
]
}
]
}Key Points for Your Test Order:
Use a unique orderReferenceId for each test order
Provide a valid shipping address
Choose an appropriate productUid from your available products
Ensure your file URL is publicly accessible and downloads immediately when accessed
Step 4: Submit the Test Order
Review your request to ensure all information is correct
Click the Send button in Postman
Check the response:
Success (200): You'll receive an order ID and creation timestamp
Error (4xx/5xx): Review the error message and fix any issues
Successful Response Example:
{
"id": "32884a3e-bd09-42be-8225-c5cea7d24611",
"orderReferenceId": "TEST-ORDER-001",
"createdAt": "2025-01-15T10:23:28+00:00"
}Step 5: Verify Your Order in GelatoConnect
Go back to GelatoConnect
Navigate to Workflow > Order Intake > Manage Orders
Look for your test order using the order reference ID
Check the order details to ensure everything was processed correctly
Common Issues and Solutions
Authentication Errors (401)
Check your X-API-KEY format: Should be
key:secretVerify the API key is active in your connector settings
Ensure you're using HTTPS, not HTTP
Bad Request Errors (400)
Validate your JSON format using Postman's built-in JSON validator
Check required fields: All required fields must be included and properly formatted
Verify product UID exists in your system
Ensure file URL is accessible without authentication
File Access Issues
Test your file URL in a private browser window to ensure it's publicly accessible
Verify the URL downloads immediately without showing preview pages
Product Not Found Errors
Confirm the productUid is correct and available in your system
Alternative: Use customer products with
productNameandproductVariantinstead ofproductUid