SPY System API V1 Documentation: Sales and Purchase Operations

This document provides detailed information for developers on authenticating and interacting with the SPY System's API V1, which is primarily designed for managing transactional sales and purchase data.

OpenAPI Specification (OAS)

We utilize Swagger to generate and publish an OpenAPI Specification (OAS) document for the SPY System API. This specification is compatible with a wide range of tools, enabling you to:

• View and Test Resources: Use tools like Swagger UI, Postman, or similar to explore and test API endpoints before integration.
• Generate Client Libraries: Automatically generate client libraries in various programming languages (e.g., PHP, Ruby, Python, Go, C#, and many more) using tools like OpenAPI Generator.

Critical Order and Delivery Flow

Understanding the order and delivery lifecycle within the SPY System is crucial for successful integration.

1. Order Creation: Once an order is created via the API, it's imported into the SPY System and awaits packing.
2. Packing Notification: Upon packing completion, a webhook event is triggered, notifying your system that the order has been packed and requires acceptance before shipment. At this stage, the delivery status is pending.
3. Accepting Delivery: Change the delivery status to accepted to signal to the SPY System that the delivery is approved for shipment and invoicing.
4. Rejecting Delivery: Changing the status to rejected will cancel the specific delivery, making it immutable. To re-attempt delivery for the order, a new delivery must be created (not a new order).
5. Status Flexibility:
   • You can toggle a delivery's status between accepted and pending as needed.
   • A rejected status is final and locks the delivery.

New Webhook Model (Introduced v1.3.0)

We have introduced a new, more robust webhook model utilizing Svix as an intermediary layer between the SPY System and your service.

How it Works:

1. SPY to Svix: The SPY System sends webhook events to Svix.
2. Svix to Your Service: You subscribe to desired events within Svix, which then forwards them to your configured endpoint.

Accessing Your Svix Portal:

• Initial Access: To gain access to your dedicated Svix portal (where you manage webhooks for your integration), call the POST /webhook-portal endpoint. This will return a secure, single-use link.
• Subsequent Access: If you need to access the portal again later, simply call the POST /webhook-portal endpoint once more to generate a new single-use link.

Within the Svix Portal, you can:

• Configure Endpoints: Define the URL(s) where you want to receive webhooks.
• Subscribe to Events: Select which specific event types you wish to receive for each endpoint.
• Monitor and Resend Events: View a history of received and sent events, and re-send any if necessary for testing or troubleshooting.

Changelog

This section outlines significant changes and additions to API V1.

Version 1.4.12

• Create Order Response: Added delivery references for deliveries created synchronously with the order.

Version 1.4.11

• Pending Refund Support:
  • New Endpoints:
    • POST /orders/{orderId}/pending-refunds
    • GET /orders/{orderId}/pending-refunds
    • GET /orders/{orderId}/pending-refunds/{pendingRefundId}
  • Refund Fields: Added pendingRefundId to the SalesOrderRefund schema when a confirmed refund was created from a pending refund.

Version 1.4.9

• Variant Stock Endpoints:
  • Added optional query parameter includeVariantsOnOrder to the stock variant endpoints:
    • GET /variants/stock
    • GET /variants/stock/{barcode}
  • Note: Add includeVariantsOnOrder=true to the query string to include variants from the customer's running sales orders in the response with quantity = 0.

Version 1.4.4

• Create Order Response: Added the full Sales Order to the response object.

Version 1.4.1

• Variant Fields: Added b2cSalePrice to the Variant schema.

Version 1.4.0

• Variant Stock and Season Data:
  • New Endpoints:
    • GET /variants/stock
    • GET /variants/stock/{barcode}
    • GET /variants/season
    • GET /variants/season/{barcode}
  • Deprecated Endpoints:
    • GET /variants (use GET /variants/stock instead)
    • GET /variants/{barcode} (use GET /variants/stock/{barcode} instead)
  • Note: New endpoints (stock/season) by default return only barcode and quantity. Add detailed=true to the query string for full variant details.
• Pre-Order Support:
  • Enabled by adding SeasonName to the order and DeliveryName to each order line.
  • Season and Delivery names can be retrieved via GET /seasons.

Version 1.3.3

• Freight Requirement: Freight is no longer a mandatory field when creating an order. (Note: System configuration may still enforce it).

Version 1.3.0

• Schema Name Changes: Some schema names have been updated.
• New Order and Refund Endpoints:
  • GET /orders
  • GET /orders/{orderId}
  • GET /orders/{orderId}/deliveries
  • GET /orders/{orderId}/deliveries/{orderDeliveryId}
  • POST /orders/{orderId}/deliveries/{orderDeliveryId}
  • GET /orders/{orderId}/refunds
  • GET /orders/{orderId}/refunds/{orderRefundId}
  • POST /orders/{orderId}/refunds/{orderRefundId}
• New Webhook Model (Beta):
  • Requires explicit access in the SPY System.
  • Access the Svix portal via POST /webhook-portal.
  • Webhooks are now documented here.

Version 1.2.56

• Variant Fields: Added colorCode and care label fields (careLabelWash, careLabelIron, careLabelDry, careLabelDryClean, careLabelBleach) to the Variant schema.

Version 1.2.55

• OrderData: shippingAddress is no longer a required field on OrderData.

Version 1.2.54

• Freight Field: Added warehouseCode to the Freight schema.

Version 1.2.50

• Variant Field: Added priceOriginal to the Variant schema.

Version 1.2.45

• Style Field: Added designer to the Style schema.

Version 1.2.38

• Variant Field: Added seasonName to the Variant schema.

Version 1.2.37

• Variant Field: Added wspPrice to the Variant schema.

Version 1.2.17

• Delivery Endpoint: Added endpoint for getting a single delivery.
• Variant Information: Added more details to Variants: B2B Hidden, Color Active, Tags, Customs Tariff Number, Country of Origin, Weight.

Version 1.2.14

• Variant Field: Added variantType to the Variant schema.

Version 1.2.8

• Variant Information: Added more details to Variants: Style Description, Wash, Category, Quality, Type, Gender.

Version 1.2.7

• New Endpoints: Added Freight and Brands endpoints.

Version 1.2.6

• New Endpoints: Added Variants, Delivery, and Orders endpoints.