API Reference

Introduction Authentication Rate Limits Deliveries API Returns API Products API Supermarkets API Webhooks Error Handling

API Documentation

Our API is currently in beta. Features and endpoints may change as we continue to improve the service.

Introduction

The wallmarkets API allows you to programmatically access and manage your logistics data. You can create and track deliveries, process returns, manage products, and more.

Base URL

https://api.wallmarkets-logistics.com/v1

Response Format

All responses are returned in JSON format. Each response includes a status code and a data payload.

{
  "status": "success",
  "data": {
    // Response data here
  }
}

Authentication

To authenticate with the API, you need to include your API key in the request headers.

API Keys

You can generate API keys in your account settings. Keep your API keys secure and do not share them publicly.

Authentication Header

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET \
  https://api.wallmarkets-logistics.com/v1/deliveries \
  -H 'Authorization: Bearer YOUR_API_KEY'

Rate Limits

To ensure the stability of our service, we apply rate limits to API requests.

Limits by Plan

Plan	Rate Limit	Burst Limit
Free	60 requests/hour	10 requests/minute
Pro	1,000 requests/hour	60 requests/minute
Business	10,000 requests/hour	300 requests/minute

Rate Limit Headers

Each response includes headers that indicate your current rate limit status:

X-RateLimit-Limit: The maximum number of requests you can make per hour
X-RateLimit-Remaining: The number of requests remaining in the current rate limit window
X-RateLimit-Reset: The time at which the current rate limit window resets (UTC epoch seconds)

Deliveries API

List Deliveries

GET /api/v1/deliveries

Returns a paginated list of all deliveries for the authenticated user.

# Query Parameters
?page=1&per_page=20&status=pending&date_from=2024-01-01

Get a Delivery

GET /api/v1/deliveries/{delivery_id}

# Response Example
{
  "id": 123,
  "supermarket_name": "E-mart",
  "subchain_name": "Sukhbaatar Branch",
  "products": "Product A (10), Product B (5)",
  "total_value": 150000,
  "delivery_date": "2024-10-15",
  "status": "completed",
  "created_at": "2024-10-01T10:30:00Z"
}

Create a Delivery

POST /api/v1/deliveries

# Request Body
{
  "supermarket_id": 5,
  "subchain_id": 12,
  "products": [
    {"product_id": 8, "quantity": 10},
    {"product_id": 15, "quantity": 5}
  ],
  "delivery_date": "2024-10-20",
  "notes": "Urgent delivery"
}

Update a Delivery

PUT /api/v1/deliveries/{delivery_id}

# Request Body
{
  "status": "completed",
  "notes": "Delivered successfully"
}

Delete a Delivery

DELETE /api/v1/deliveries/{delivery_id}

Note: Completed deliveries cannot be deleted for audit compliance.

Returns API

List Returns

GET /api/v1/returns

Returns a paginated list of all product returns.

Get a Return

GET /api/v1/returns/{return_id}

Create a Return

POST /api/v1/returns

# Request Body
{
  "supermarket_id": 5,
  "subchain_id": 12,
  "product_id": 8,
  "quantity": 3,
  "reason": "damaged",
  "return_date": "2024-10-18",
  "description": "Products arrived damaged"
}

Return Reasons

- damaged
- expired
- wrong_product
- quality_issue
- overstock
- customer_complaint
- other

Update a Return

PUT /api/v1/returns/{return_id}

Delete a Return

DELETE /api/v1/returns/{return_id}

Products API

List Products

GET /api/v1/products

Get a Product

GET /api/v1/products/{product_id}

# Response Example
{
  "id": 8,
  "name": "Premium Rice 5kg",
  "sku": "RICE-PRE-5KG",
  "category": "Grains",
  "price": 12500,
  "weight": 5.0,
  "unit": "kg",
  "stock_quantity": 450,
  "image_url": "/static/uploads/rice_premium.jpg",
  "created_at": "2024-09-15T08:00:00Z"
}

Create a Product

POST /api/v1/products

# Request Body (multipart/form-data)
{
  "name": "Premium Rice 5kg",
  "sku": "RICE-PRE-5KG",
  "category": "Grains",
  "price": 12500,
  "weight": 5.0,
  "unit": "kg",
  "stock_quantity": 450,
  "image": <file>
}

Update a Product

PUT /api/v1/products/{product_id}

Delete a Product

DELETE /api/v1/products/{product_id}

Note: Products used in deliveries/returns cannot be deleted.

Supermarkets API

List Supermarkets

GET /api/v1/supermarkets

Get a Supermarket

GET /api/v1/supermarkets/{supermarket_id}

# Response Example
{
  "id": 5,
  "name": "E-mart",
  "location": "Ulaanbaatar",
  "contact_person": "B. Dorj",
  "phone": "+976 7711 1234",
  "email": "dorj@emart.mn",
  "subchains_count": 12,
  "total_deliveries": 456,
  "created_at": "2024-01-10T12:00:00Z"
}

Create a Supermarket

POST /api/v1/supermarkets

# Request Body
{
  "name": "E-mart",
  "location": "Ulaanbaatar",
  "contact_person": "B. Dorj",
  "phone": "+976 7711 1234",
  "email": "dorj@emart.mn"
}

List Subchains

GET /api/v1/supermarkets/{supermarket_id}/subchains

Create a Subchain

POST /api/v1/supermarkets/{supermarket_id}/subchains

# Request Body
{
  "name": "Sukhbaatar Branch",
  "address": "Peace Avenue 15, Ulaanbaatar",
  "manager": "G. Bat",
  "phone": "+976 7722 5678"
}

Update a Supermarket

PUT /api/v1/supermarkets/{supermarket_id}

Delete a Supermarket

DELETE /api/v1/supermarkets/{supermarket_id}

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your wallmarkets account.

Setting Up Webhooks

Configure webhook endpoints in your account settings. We'll send POST requests to your URL when events occur.

Event Types

Event	Description
`delivery.created`	A new delivery was created
`delivery.updated`	A delivery was updated
`delivery.completed`	A delivery was marked as completed
`return.created`	A new return was created
`return.processed`	A return was processed
`product.low_stock`	A product's stock fell below threshold

Webhook Payload Example

{
  "event": "delivery.completed",
  "timestamp": "2024-10-15T14:30:00Z",
  "data": {
    "delivery_id": 123,
    "supermarket_name": "E-mart",
    "subchain_name": "Sukhbaatar Branch",
    "total_value": 150000,
    "completed_at": "2024-10-15T14:30:00Z"
  }
}

Webhook Security

Each webhook request includes an X-Webhook-Signature header with HMAC-SHA256 signature for verification.

# Python verification example
import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Error Handling

The wallmarkets API uses conventional HTTP response codes to indicate success or failure of requests.

HTTP Status Codes

Code	Status	Description
`200`	OK	Request succeeded
`201`	Created	Resource successfully created
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Access denied to resource
`404`	Not Found	Resource doesn't exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end

Error Response Format

{
  "status": "error",
  "error": {
    "code": "INVALID_DELIVERY_DATE",
    "message": "Delivery date must be in the future",
    "field": "delivery_date",
    "docs_url": "https://wallmarkets.store/api-docs#deliveries-api"
  }
}

Common Error Codes

Error Code	Description
`INVALID_API_KEY`	The provided API key is invalid
`RATE_LIMIT_EXCEEDED`	Too many requests, slow down
`RESOURCE_NOT_FOUND`	The requested resource doesn't exist
`VALIDATION_ERROR`	One or more fields failed validation
`INSUFFICIENT_PERMISSIONS`	Your account doesn't have access to this resource
`PRODUCT_OUT_OF_STOCK`	The requested product is out of stock

Handling Errors

# Python example
import requests

try:
    response = requests.get(
        'https://api.wallmarkets.store/v1/deliveries/123',
        headers={'Authorization': 'Bearer YOUR_API_KEY'}
    )
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    if e.response.status_code == 404:
        print("Delivery not found")
    elif e.response.status_code == 429:
        print("Rate limit exceeded, retry after:", 
              e.response.headers.get('Retry-After'))
    else:
        error_data = e.response.json()
        print(f"API Error: {error_data['error']['message']}")

Ready to Get Started?

Generate your API keys in your account settings and start integrating wallmarkets into your applications!

Generate API Key View Help Center

Back to Home