Welcome to the Dora API v2 documentation. This API provides programmatic access to Dora's retail pricing and sales functionality.
All API requests require authentication using a Bearer token in the Authorization header.
Authorization: Bearer YOUR_ACCESS_TOKENAll API endpoints are relative to:
https://api.configuredora.com/The API accepts the following HTTP methods:
All responses are returned in JSON format with appropriate HTTP status codes.
Common status codes:
Authenticate a user and receive an access token.
POST /auth/login{
"username": "string",
"password": "string"
}// Success (200)
{
"user_id": number,
"country_id": number,
"country_code": "string",
"country_name": "string",
"currency_code": "string",
"dealer_name": "string",
"role": "string", // "admin", "extra", "nopurchase", or "dealer"
"token": "string" // JWT token valid for 1 hour
}Retrieve information about the currently authenticated user.
GET /auth/user// Success (200)
{
"user_id": number,
"dealer_name": "string",
"country_id": number,
"country_code": "string",
"country_name": "string",
"currency_code": "string",
"role": "string" // "admin", "extra", "nopurchase", or "dealer"
}Request a password reset link via email.
POST /auth/reset_password{
"username": "string"
}// Success (200)
{
"contact": {
// User contact information
}
}
// Error (404)
{
"error": {
"message": "User not found"
}
}End the current user's session.
POST /auth/logout{
"message": "Bye"
}Authenticates the current session and returns a fresh token.
GET /auth/authenticate// Success (200)
{
"token": "string" // Fresh bearer token valid for 1 hour
}// Unauthorized (401)
{
"error": {
"message": "Not authenticated"
}
}Retrieve available catalog collections for the current user's country.
GET /catalog/collections// Success (200)
[
{
"id": number, // Collection ID
"category_name": "string",
"collection_name": "string",
"is_new": boolean // Indicates if this is a new collection
"image": "string" // Full URL to image
}
]
// Error (404)
{
"error": {
"message": "No collections found"
}
}Search and retrieve catalog items with pagination and filtering options.
POST /catalog/items{
"search": "string", // optional - search by style number
"page": number, // optional - default: 1
"limit": number, // optional - default: 20, max: 100
"ids": number | number[], // optional - filter by specific style ID(s)
"collection_id": number | number[], // optional - filter by collection ID(s)
"metal_id": number | number[], // optional - filter by metal ID(s)
"sort_by": "string", // optional - "style_no", "style_name", or "style_price"
"sort_dir": "string", // optional - "asc" or "desc"
"show_home": boolean // optional - filter items shown on home page
}// Success (200)
{
"items": [
{
"id": number,
"style_no": "string",
"information": "string",
"collection_id": number,
"category_name": "string",
"collection_name": "string",
"metals": [ // Array of metal IDs
number
],
"width": number,
"size": number,
"currency": "string",
"currency_symbol": "string",
"price": number,
"image": "string" // Full URL to image
}
],
"available_metals": [ // List of all available metals with counts
{
"id": number,
"name": "string",
"count": number // Number of items available in this metal
}
],
"pagination": {
"total": number, // Total number of items
"page": number, // Current page
"limit": number, // Items per page
"pages": number // Total number of pages
}
}
// Error (404)
{
"error": {
"message": "No items found"
}
}Retrieve detailed information for a specific catalog item, including available sizes, widths, metals, and diamond specifications.
POST /catalog/item{
"id": number, // required - Item ID
"collection_id": number, // required - Collection ID
"mode": "string", // optional - "ring" (default) or "sample" - affects pricing
"size": number, // optional - Size in mm
"width": number, // optional - Width in mm
"parts": [ // optional - Parts configuration array
{
"name": "string", // required - Part name
"metal_id": number, // optional - Metal ID for this part
"color": "string", // optional - Metal color (White/Yellow/Rose)
"finish": "string" // optional - Surface finish
}
]
}// Success (200)
{
"id": number, // Style ID
"style_no": string, // Style number
"mode": string, // Current mode ("ring" or "sample")
"description": string, // Style description/text
"default_size_mm": number, // Default size in millimeters
"default_width": number, // Default width
"default_metal_id": number,// Default metal ID
"default_weight": string | null, // Client-specific weight category label (e.g. "Light", "Standard", "Heavy") or null if not applicable
"collection_id": number, // Collection ID
"collection_name": string, // Collection name
"shape": string, // 3D shape identifier
"size": number, // Selected or default size
"width": number, // Selected or default width
"min_width": number, // Minimum allowed width
"max_width": number, // Maximum allowed width
"country_code": string, // Country code
"currency": string, // Currency code
"currency_symbol": string,// Currency symbol
"total_price": number, // Total price in selected currency
"parts": [ // Available parts (e.g., "Band", "Setting")
{
"name": string, // Part name
"available_materials": [
{
"id": number, // Metal ID
"name": string, // Metal name
"code": string, // Metal code
"available_colors": [string], // Available colors: "White", "Yellow", "Rose"
"default_color": string | null, // Default color or null
"available_finishes": [string], // Available finishes: "Polished", "Hammered", "Brushed", "Iced"
"default_finish": string | null, // Default finish or null
"weight": number // Weight in grams
}
],
"default_material_id": number | null, // Default material ID or null
"selected_material_id": number | null, // Currently selected material ID or null
"selected_color": string | null, // Currently selected color or null
"selected_finish": string | null // Currently selected finish or null
}
],
"sizes": [ // Available sizes
{
"id": number, // Size ID
"size": number, // Size value in country's preferred unit
"size_mm": number, // Size in millimeters
"selected": boolean // Whether this size is selected
}
],
"widths": [ // Available widths
{
"width": number, // Width in mm
"selected": boolean // Whether this width is selected
}
],
"diamonds": [ // Diamond specifications if applicable
{
"cut_code": string, // Diamond cut code
"cut": string, // Diamond cut name
"count": number, // Number of diamonds
"size": number, // Diamond size
"total_weight": number,// Total diamond weight
"vary": number, // Size variation
"vary_quantity": number,// Quantity variation
"black_diamond": boolean,// Whether it's a black diamond
"quality": string // Diamond quality name
}
],
"related_weights": { // Related styles by weight category
"lighter": { // Lighter weight variation (rel_type = 1)
"id": number, // Style ID
"collection_id": number, // Collection ID
"style_no": string, // Style number
"shape": string // 3D shape identifier
} | null, // null if no lighter variation exists
"default": { // Default weight variation (rel_type = 8)
"id": number, // Style ID
"collection_id": number, // Collection ID
"style_no": string, // Style number
"shape": string // 3D shape identifier
} | null, // null if no default variation exists
"heavier": { // Heavier weight variation (rel_type = 2)
"id": number, // Style ID
"collection_id": number, // Collection ID
"style_no": string, // Style number
"shape": string // 3D shape identifier
} | null // null if no heavier variation exists
},
"related_rings": [ // Array of related ring styles (rel_type = 9)
{
"id": number, // Style ID
"collection_id": number, // Collection ID
"style_no": string, // Style number
"shape": string // 3D shape identifier
}
]
}// Error (400) - Missing Required Parameters
{
"error": {
"message": "Item ID and Collection ID are required"
}
}
// Error (400) - Invalid Width
{
"error": {
"message": "Width must be between {min} and {max}"
}
}
// Error (400) - Invalid Size
{
"error": {
"message": "Invalid size"
}
}
// Error (404) - Item Not Found
{
"error": {
"message": "Item not found"
}
}Generate and download a PDF specification sheet for a catalog item.
POST /catalog/pdfAuthorization: Bearer YOUR_ACCESS_TOKEN // Required - JWT token for authentication{
"style_id": number, // required - Item style ID
"mode": "string", // optional - "ring" (default) or "sample" - affects pricing
"size": number, // optional - Size in mm
"width": number, // optional - Width in mm
"metal_id": number, // optional - Metal ID
"image": string, // optional - Base64 encoded PNG image
"color": string, // optional - Metal color (White/Yellow/Rose)
"finish": string, // optional - Surface finish
"engraving_text": string, // optional - Engraving text
"engraving_font": string // optional - Engraving font
}// Success (200)
// Returns PDF file download with Content-Type: application/pdf
// Filename format: style_{style_no}.pdf
// Error (401)
{
"error": {
"message": "Not authenticated"
}
}
// Error (400)
{
"error": {
"message": "style_id parameter is required"
}
}
// Error (404)
{
"error": {
"message": "Item not found"
}
}Retrieve the current user's shopping cart.
GET /cart// Success (200)
{
"items": [
{
"type": "ring",
"id": number,
"quantity": number,
"price": number,
"item_key": "string",
"options": {
"size": number,
"width": number,
"parts": [ // Parts configuration array
{
"name": "string", // Part name (e.g., "Band", "Setting")
"metal_id": number, // Metal ID for this part
"color": "string", // Metal color (White/Yellow/Rose)
"finish": "string", // Surface finish (Polished/Hammered/Brushed/Iced)
"metal_name": "string"
}
],
"diamonds": [] // optional
},
"details": {
"style_no": "string",
"description": "string",
"default_size_mm": number,
"default_width": number,
"min_width": number,
"max_width": number,
"size_table": "string",
"local_size": number,
"image": "string" // Base64 encoded image data (data:image/png;base64,...)
}
}
],
"total": number
}Add or update items in the shopping cart. When adding items, if an identical configuration already exists, the quantities will be combined.
PUT /cart{
"item_key": "string", // Required - Unique identifier of existing cart item
"quantity": number // Required - Quantity to add/subtract (will be added to existing quantity)
}{
"type": "ring",
"id": number, // Required - Item ID
"quantity": number, // Required - Quantity to add (minimum 1)
"image": "string", // Optional - Base64 encoded PNG image (data:image/png;base64,...)
"options": {
"size": number, // Required - Size in mm
"width": number, // Required - Width in mm
"parts": [ // Required - Parts configuration array
{
"name": "string", // Required - Part name (e.g., "Band", "Setting")
"metal_id": number, // Optional - Metal ID for this part
"color": "string", // Optional - Metal color (White/Yellow/Rose)
"finish": "string" // Optional - Surface finish (Polished/Hammered/Brushed/Iced)
}
],
"diamonds": [ // Optional - diamond configurations
{
"diamond_cut_id": number, // Required - Diamond cut ID
"diamond_count_size": number, // Required - Diamond count size
"diamond_size": number, // Required - Diamond size
"diamond_quality_id": string // Required - Diamond quality ID
}
]
}
}{
"type": "product",
"id": number, // Product ID
"quantity": number // Quantity to add (minimum 1)
}// Success (200)
// Empty response with 200 status code
// Error (400) - Invalid Request Format
{
"error": "Invalid request format"
}
// Error (400) - Missing Parameters
{
"error": "Missing required parameters" | "Missing required ring options" |
"Quantity is required" | "Invalid item type" | "Part name is required" |
"Missing required ring size or width" | "Missing required ring options or invalid values"
}
// Error (400) - Invalid Image
{
"error": "Invalid image format. Only base64 encoded PNG images are supported." |
"Invalid base64 image data"
}
// Error (404) - Item Not Found
{
"error": "Item not found or incorrect options" | "Product not found"
}
// Error (500) - Server Error
{
"error": "Failed to save cart"
}Remove an item from the shopping cart.
DELETE /cart{
"item_key": "string" // Unique identifier of cart item to remove
}// Success (200)
// Empty response with 200 status code
// Error (400)
{
"error": "Item key required"
}
// Error (404)
{
"error": "Cart not found" | "Item not found in cart"
}
// Error (500)
{
"error": "Failed to save cart"
}Convert the current cart into a sales order.
POST /cart// Empty request body - uses current cart contents// Success (200)
{
"orderNo": "string", // Generated order number
"total": number // Total order amount
}
// Error (400)
{
"error": "Cart is empty"
}
// Error (404)
{
"error": "Cart not found"
}
// Error (500)
{
"error": "Failed to create order"
}Retrieve collections from the Directus CMS.
POST /directus/collections{
"search": "string" // optional - Search term to filter collections
}// Success (200)
[
{
"id": number,
"country_id": number,
"country_name": "string",
"collection_name": "string" // Format: "{country_name} - {collection_name}"
}
]
// Error (404)
{
"error": {
"message": "No collections found"
}
}Search and retrieve products with pagination and sorting options. Products are filtered by the current user's country.
POST /product/items{
"search": "string", // optional - search term for name or description
"page": number, // optional - default: 1
"limit": number, // optional - default: 20, max: 100
"sort_by": "string", // optional - "product_name" or "product_price"
"sort_dir": "string" // optional - "asc" or "desc"
}// Success (200)
{
"items": [
{
"id": number,
"name": "string",
"description": "string",
"price": number,
"image": "string" // Full URL to product image
}
],
"pagination": {
"total": number, // Total number of items
"page": number, // Current page
"limit": number, // Items per page
"pages": number // Total number of pages
}
}
// Error (404)
{
"error": {
"message": "No items found"
}
}Retrieve detailed information for a specific product.
GET /product/item/{id}id: number // Required - Product ID// Success (200)
{
"id": number,
"name": "string",
"description": "string",
"price": number,
"image": "string" // Full URL to product image
}
// Error (400)
{
"error": {
"message": "Item ID is required"
}
}
// Error (404)
{
"error": {
"message": "Item not found"
}
}Submit a customized product request form with dimensions and optional shipping details.
POST /product/request{
"name": "string", // Required - Product name
"width": number, // Required - Product width
"height": number, // Required - Product height
"logo": File, // Optional - Company logo file (multipart/form-data)
"store_name": "string", // Optional - Store name
"same_address": boolean,// Optional - Use same address flag
"streetname": "string", // Required if same_address is false - Street address
"city": "string", // Required if same_address is false - City
"country": "string", // Required if same_address is false - Country
"zipcode": "string", // Required if same_address is false - Zip/postal code
"notes": "string", // Optional - Additional notes
"terms": boolean // Required - Must be true to accept terms
}// Success (200)
{
"success": {
"message": "Request submitted successfully"
}
}
// Error (400) - Missing Required Fields
{
"error": {
"message": "Missing required fields"
}
}
// Error (400) - Invalid Address
{
"error": {
"message": "Invalid address fields"
}
}
// Error (500) - Email Send Failure
{
"error": {
"message": "Failed to send request: [error details]"
}
}Submit a contact form message. This endpoint requires authentication using a JWT token.
POST /contact/submit
Authorization: Bearer YOUR_ACCESS_TOKENAuthorization: Bearer YOUR_ACCESS_TOKEN // Required - JWT token for authentication{
"name": "string", // Required - Contact name
"email": "string", // Required - Contact email
"comment": "string" // Required - Message content
}// Success (200)
{
"success": {
"message": "Message sent successfully"
}
}
// Error (400) - Missing Required Fields
{
"error": {
"message": "Missing required fields"
}
}
// Error (400) - Invalid Email
{
"error": {
"message": "Invalid email format"
}
}
// Error (500) - Email Send Failure
{
"error": {
"message": "Failed to send message: [error details]"
}
}