{
  "openapi": "3.1.0",
  "info": {
    "title": "SQ hubb: ingestion API",
    "version": "1.0.0",
    "description": "The ingestion API lets an accredited seller push listings and stocks from their ERP. It goes through the same chain as the file import: same checks, same defaults.\n\n- 60 calls per minute and per token; beyond that, a 429 response with the Retry-After header.\n\n- At most 500 items per call.\n\n- The seller reference is mandatory. A reference you already use updates its listing: replaying a call never creates a duplicate.\n\n- A listing created through the API starts as a draft and goes through the marketplace moderation before publication. Only the fields sent are changed.\n\n- Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration."
  },
  "servers": [
    {
      "url": "https://sqhubb.com/api/v1/ingestion"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/listings": {
      "post": {
        "operationId": "pushListings",
        "summary": "Creates or updates listings, in batches.",
        "parameters": [
          {
            "name": "dry_run",
            "in": "query",
            "required": false,
            "description": "Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "name": "janus",
            "in": "query",
            "required": false,
            "description": "When the marketplace has opened Janus on import, add janus=1: the items become a received Janus import (taxonomy matching, enrichment), which you launch from My Space after seeing its cost.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "202": {
            "description": "the Janus import is received, to launch from My Space.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "400": {
            "description": "the body is not readable JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "invalid_json"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "token missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "unauthorized"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "the API is not open on this marketplace.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "suspended",
                            "closed"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "invalid body (no list, empty list, too many items, janus and dry_run together).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "invalid_payload"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "too many calls, retry after the indicated delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limited"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before the next call.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "503": {
            "description": "rate limiting temporarily unavailable, retry after the given delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limiter_unavailable"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ListingsBatch"
              },
              "example": {
                "listings": [
                  {
                    "reference": "SKU-001",
                    "title": "Réducteur SEW R97",
                    "price": 1850,
                    "currency": "EUR",
                    "quantity": 3,
                    "condition": "new_unused",
                    "incoterm": "EXW",
                    "brand": "SEW",
                    "model": "R97",
                    "origin_country": "DE",
                    "pickup_country": "FR",
                    "unit_weight_kg": 120,
                    "certifications": [
                      "CE"
                    ],
                    "price_tiers": [
                      {
                        "min_quantity": 2,
                        "unit_price": 1750
                      }
                    ],
                    "images": [
                      "https://images.example.com/sku-001-face.jpg"
                    ],
                    "specifications": {
                      "puissance": "7,5 kW",
                      "hs_code": "8483.40"
                    }
                  },
                  {
                    "reference": "SKU-002",
                    "price": 940,
                    "quantity": 0
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/listings/{reference}": {
      "get": {
        "operationId": "getListing",
        "summary": "Reads a listing by its reference: status, price, stock, translations.",
        "parameters": [
          {
            "name": "reference",
            "in": "path",
            "required": true,
            "description": "Your reference, mandatory and unique on your side.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListingResponse"
                }
              }
            }
          },
          "401": {
            "description": "token missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "unauthorized"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "the API is not open on this marketplace.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "suspended",
                            "closed"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "no listing of this seller has this reference.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "not_found"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "too many calls, retry after the indicated delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limited"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before the next call.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "503": {
            "description": "rate limiting temporarily unavailable, retry after the given delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limiter_unavailable"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/stocks": {
      "post": {
        "operationId": "pushStocks",
        "summary": "Updates the available quantity, and the price when provided, by reference. An unknown reference is rejected, never created.",
        "parameters": [
          {
            "name": "dry_run",
            "in": "query",
            "required": false,
            "description": "Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration.",
            "schema": {
              "type": "boolean",
              "default": false
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunResponse"
                }
              }
            }
          },
          "400": {
            "description": "the body is not readable JSON.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "invalid_json"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "token missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "unauthorized"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "the API is not open on this marketplace.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "suspended",
                            "closed"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "422": {
            "description": "invalid body (no list, empty list, too many items, janus and dry_run together).",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "invalid_payload"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "too many calls, retry after the indicated delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limited"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before the next call.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "503": {
            "description": "rate limiting temporarily unavailable, retry after the given delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limiter_unavailable"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StocksBatch"
              },
              "example": {
                "stocks": [
                  {
                    "reference": "SKU-001",
                    "quantity": 2
                  },
                  {
                    "reference": "SKU-002",
                    "quantity": 5,
                    "price": 900
                  }
                ]
              }
            }
          }
        }
      }
    },
    "/runs": {
      "get": {
        "operationId": "listRuns",
        "summary": "The last twenty runs, through the API and through the daily synchronisation.",
        "responses": {
          "200": {
            "description": "Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunsResponse"
                }
              }
            }
          },
          "401": {
            "description": "token missing, invalid or revoked.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "unauthorized"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "403": {
            "description": "the API is not open on this marketplace.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "suspended",
                            "closed"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "too many calls, retry after the indicated delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limited"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "The number of seconds to wait before the next call.",
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          },
          "503": {
            "description": "rate limiting temporarily unavailable, retry after the given delay.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Error"
                    },
                    {
                      "properties": {
                        "error": {
                          "enum": [
                            "rate_limiter_unavailable"
                          ]
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sqh_…",
        "description": "Each call carries the seller's token in the Authorization header. The token files everything it pushes under the seller company that created it."
      }
    },
    "schemas": {
      "Listing": {
        "type": "object",
        "required": [
          "reference"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "description": "Your reference, mandatory and unique on your side."
          },
          "title": {
            "type": "string",
            "description": "The listing title, mandatory on creation."
          },
          "description": {
            "type": "string",
            "description": "The description, in French."
          },
          "summary": {
            "type": "string",
            "description": "A one-line summary."
          },
          "category": {
            "type": "string",
            "description": "The family: its name or identifier (slug)."
          },
          "condition": {
            "type": "string",
            "description": "The condition of the item (values below).",
            "examples": [
              "new_unused",
              "new_surplus",
              "workshop_checked",
              "audited",
              "good_condition",
              "dismantled_tagged",
              "for_parts"
            ]
          },
          "price": {
            "type": "number",
            "description": "The unit price excluding tax."
          },
          "reference_price": {
            "type": "number",
            "description": "The reference price (new or market), higher than the price."
          },
          "currency": {
            "type": "string",
            "description": "The currency, EUR by default."
          },
          "quantity": {
            "type": "integer",
            "description": "The available quantity."
          },
          "sale_unit": {
            "type": "string",
            "description": "The sale unit (unit, lot, tonne, kilogram, pallet...).",
            "examples": [
              "unit",
              "lot",
              "tonne",
              "kilogram",
              "liter",
              "square_meter",
              "linear_meter",
              "cubic_meter",
              "pallet"
            ]
          },
          "lot_size": {
            "type": "integer",
            "description": "The lot size."
          },
          "minimum_order_quantity": {
            "type": "integer",
            "description": "The minimum order quantity."
          },
          "packaging": {
            "type": "string",
            "description": "The packaging (pallet, wooden_crate, big_bag...).",
            "examples": [
              "pallet",
              "wooden_crate",
              "big_bag",
              "bulk",
              "container",
              "parcel",
              "loose",
              "oversized"
            ]
          },
          "incoterm": {
            "type": "string",
            "description": "The Incoterm 2020 (values below).",
            "examples": [
              "EXW",
              "FCA",
              "FAS",
              "FOB",
              "CFR",
              "CIF",
              "CPT",
              "CIP",
              "DAP",
              "DPU",
              "DDP"
            ]
          },
          "pickup_country": {
            "type": "string",
            "maxLength": 2,
            "description": "The pickup country, two-letter ISO code."
          },
          "pickup_region": {
            "type": "string",
            "description": "The pickup region."
          },
          "pickup_city": {
            "type": "string",
            "description": "The pickup city."
          },
          "pickup_postal_code": {
            "type": "string",
            "description": "The pickup postal code."
          },
          "origin_country": {
            "type": "string",
            "maxLength": 2,
            "description": "The country of origin, two-letter ISO code."
          },
          "brand": {
            "type": "string",
            "description": "The brand."
          },
          "model": {
            "type": "string",
            "description": "The model or manufacturer reference."
          },
          "year_of_manufacture": {
            "type": "integer",
            "description": "The year of manufacture."
          },
          "unit_weight_kg": {
            "type": "number",
            "description": "The unit weight in kilograms."
          },
          "length_cm": {
            "type": "integer",
            "description": "The length in centimetres."
          },
          "width_cm": {
            "type": "integer",
            "description": "The width in centimetres."
          },
          "height_cm": {
            "type": "integer",
            "description": "The height in centimetres."
          },
          "seo_title": {
            "type": "string",
            "description": "The title for search engines."
          },
          "seo_description": {
            "type": "string",
            "description": "The description for search engines."
          },
          "certifications": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The list of certifications and labels, for example [\"CE\", \"ISO 9001\"]."
          },
          "price_tiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PriceTier"
            },
            "description": "Volume price tiers excl. VAT, for example [{\"min_quantity\": 10, \"unit_price\": 95}]. A tier at or above the base price is discarded."
          },
          "images": {
            "type": "array",
            "maxItems": 5,
            "items": {
              "type": "string",
              "format": "uri",
              "maxLength": 2000
            },
            "description": "The web addresses of the photos (JPEG, PNG or WebP, 10 MB at most), five at most. The first one becomes the main photo. They are downloaded after the listing is saved."
          },
          "specifications": {
            "type": "object",
            "description": "The family specifications, as a key and value object.",
            "additionalProperties": {
              "type": [
                "string",
                "number",
                "boolean"
              ]
            }
          }
        }
      },
      "ListingsBatch": {
        "type": "object",
        "required": [
          "listings"
        ],
        "properties": {
          "listings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Listing"
            },
            "maxItems": 500,
            "minItems": 1
          }
        }
      },
      "StockLine": {
        "type": "object",
        "required": [
          "reference",
          "quantity"
        ],
        "properties": {
          "reference": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": 0
          },
          "price": {
            "type": "number"
          }
        }
      },
      "StocksBatch": {
        "type": "object",
        "required": [
          "stocks"
        ],
        "properties": {
          "stocks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/StockLine"
            },
            "maxItems": 500
          }
        }
      },
      "PriceTier": {
        "type": "object",
        "required": [
          "min_quantity",
          "unit_price"
        ],
        "properties": {
          "min_quantity": {
            "type": "integer",
            "minimum": 1
          },
          "unit_price": {
            "type": "number"
          }
        }
      },
      "Run": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "channel": {
            "type": "string",
            "enum": [
              "api",
              "sync"
            ]
          },
          "kind": {
            "type": "string",
            "enum": [
              "listings",
              "stocks"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "partial",
              "failed",
              "unchanged",
              "janus_received"
            ]
          },
          "received": {
            "type": "integer"
          },
          "created": {
            "type": [
              "integer",
              "null"
            ]
          },
          "updated": {
            "type": [
              "integer",
              "null"
            ]
          },
          "rejected": {
            "type": [
              "integer",
              "null"
            ]
          },
          "rejections": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "reference": {
                  "type": "string"
                },
                "reasons": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "error": {
            "type": [
              "string",
              "null"
            ]
          },
          "janus_import_id": {
            "type": [
              "integer",
              "null"
            ]
          },
          "started_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "finished_at": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "RunResponse": {
        "type": "object",
        "required": [
          "run"
        ],
        "properties": {
          "run": {
            "$ref": "#/components/schemas/Run"
          },
          "dry_run": {
            "type": "boolean",
            "description": "Add dry_run=1 to a write call: the batch is checked as it would be, and the response returns the same report (creations, updates, detailed rejections), but nothing is written, no listing, no stock, no run in the log. Any token allows it: it is the trial token of your first integration."
          }
        }
      },
      "RunsResponse": {
        "type": "object",
        "properties": {
          "runs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Run"
            }
          }
        }
      },
      "ListingResponse": {
        "type": "object",
        "properties": {
          "listing": {
            "type": "object",
            "properties": {
              "reference": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "price": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "price_on_request": {
                "type": "boolean"
              },
              "currency": {
                "type": "string"
              },
              "quantity": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "condition": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "incoterm": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "origin_country": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "certifications": {
                "type": "array"
              },
              "price_tiers": {
                "type": "array"
              },
              "updated_at": {
                "type": "string"
              },
              "translations": {
                "type": "array"
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_json",
              "unauthorized",
              "suspended",
              "closed",
              "not_found",
              "invalid_payload",
              "rate_limited",
              "rate_limiter_unavailable"
            ]
          },
          "message": {
            "type": "string"
          }
        }
      }
    }
  }
}