Technical documentation for developers. Connect BaseLinker, WooCommerce, Apilo, or your proprietary WMS/ERP solution directly to Scopio Marketplace. Provide hands-free order fetching and instant delivery status & tracking sync.
Seller API Keys
Every request to the Scopio API must be authorized with a unique seller token. This token is generated in the administration panel. Use the Authorization header with the Bearer prefix, or use the dedicated X-API-Key header directly.
Tokens contain permissions linked to your seller account and profile. Store them securely (e.g., in environment variables) and never expose them in client-side code. The API strictly requires TLS 1.3 encrypted connections.
# Authorization Header
Authorization: Bearer sk_mkt_ca1d5b9...
X-API-Key: sk_mkt_ca1d5b9...
Endpoint: GET /api/seller/orders
The endpoint enables automated retrieval of newly paid orders. It only returns items (order line elements) belonging to your seller catalog (filtered by sellerId). Buyer delivery details and preferred shipping methods are provided in standardized JSON formats.
The recommended polling interval is between 5 and 15 minutes. The response contains a shipping_address structure with the buyer's full contact details, a list of ordered products containing EAN codes, quantities, net prices, and gross prices.
# Response excerpt
{ "success": true, "orders": [...] }
Endpoint: POST /api/seller/orders/{orderId}/fulfill
After packing the shipment and generating a shipping label in your ERP (e.g. BaseLinker), send the fulfillment status back to Scopio. Provide the tracking number and carrier identifier, and the system will immediately update the order and notify the buyer.
Allowed carrier identifiers include inpost_locker (Locker points), inpost_courier, dpd, dhl, ups. You can optionally transmit a direct PDF download link for the shipping label (label_url), allowing it to be viewed directly inside the Scopio panel.
# Payload data
{ "tracking_number": "XYZ123", "carrier": "inpost_locker" }
Instant HTTP POST Events
Configure a Webhook URL in your seller profile to receive notifications in real-time. The system sends a POST request to your address immediately after a customer order payment is cleared, avoiding API polling overhead.
Each webhook payload contains a signature header computed using a shared Webhook Secret. Use this to verify sender authenticity. If your endpoint does not return a 200 OK status, the system retries the notification 3 times at 5-minute intervals.
Ready for the AI Agent economy
All order structures and statuses are fully compliant with the Universal Commerce Protocol (UCP) standard. This allows autonomous search and shopping bots to parse order details and index catalog nodes seamlessly.
By adhering to the UCP data formatting rules, orders placed by autonomous purchasing agents are routed to your CRM system without requiring custom parser code blocks for each individual bot.
Infrastructure security and performance
The default rate limit is 120 API requests per minute per IP address / API key. Exceeding this threshold returns HTTP status code 429 (Too Many Requests). All errors return a standardized JSON structure with code and description.
The API returns standard HTTP status codes: 400 (bad payload), 401 (unauthorized), 403 (access to order denied), 404 (order not found), 500 (internal server error). All error occurrences are automatically logged to seller_crm_logs for debugging.
# HTTP 429 Rate Limit Response
{ "error": "Too Many Requests", "retry_after_seconds": 60 }
