{
 "openapi": "3.1.0",
 "info": {
  "title": "ENGICOR agent API — wholesale used engines",
  "version": "1.0.0",
  "description": "For AI agents and procurement software buying used engines wholesale. ENGICOR (UAE) sells Grade A used petrol and diesel engines by the container from a warehouse in Guangzhou, China: 20-ft = 90 engines or 45 engines + 45 gearboxes; 40-ft = 130 or 65 + 65; a new customer's first order can be 20, 30 or 40 engines. Prices: USD per unit, FOB Guangzhou, list price. A human confirms every quotation and issues the Proforma Invoice; nothing is payable before it. The same tools are available over MCP at https://engicor.com/mcp. No API key needed.",
  "contact": {
   "name": "ENGICOR sales",
   "email": "sales@engicor.com",
   "url": "https://engicor.com/agents/"
  },
  "termsOfService": "https://engicor.com/payment-protection/"
 },
 "servers": [
  {
   "url": "https://engicor.com/api/v1"
  }
 ],
 "externalDocs": {
  "url": "https://engicor.com/agents/",
  "description": "Agent door documentation"
 },
 "paths": {
  "/terms": {
   "get": {
    "operationId": "getTerms",
    "summary": "Trade terms (order formats, payment, check, warranty, markets, contacts)",
    "responses": {
     "200": {
      "description": "Terms",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/prices": {
   "get": {
    "operationId": "getPriceList",
    "summary": "Published wholesale list prices (USD per unit, FOB Guangzhou) and gearbox options",
    "responses": {
     "200": {
      "description": "Price list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/search": {
   "get": {
    "operationId": "searchStock",
    "summary": "Search the warehouse list (~488 families, 38 makes) by engine code, vehicle or make",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "example": "Hilux"
     },
     {
      "name": "make",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "priced_only",
      "in": "query",
      "schema": {
       "type": "boolean"
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 50,
       "default": 10
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Matching families",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/engines/{code}": {
   "get": {
    "operationId": "getEngine",
    "summary": "One engine family: spec, vehicles, configurations, price and gearbox options if published",
    "parameters": [
     {
      "name": "code",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "example": "QR25DE"
     }
    ],
    "responses": {
     "200": {
      "description": "Engine",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Not in the stock list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/estimate": {
   "post": {
    "operationId": "estimateOrder",
    "summary": "Validate an order and compute FOB total and 30/70 payment split. Registers nothing.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Order"
       },
       "example": {
        "order_type": "first_order",
        "lines": [
         {
          "code": "1NZ-FE",
          "quantity": 20
         },
         {
          "code": "TR-1NZ-FE",
          "quantity": 5
         }
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Valid order with totals",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "422": {
      "description": "Invalid order, with the reasons",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/quote": {
   "post": {
    "operationId": "requestQuote",
    "summary": "Register a quotation request on behalf of a buyer (with their consent). A human confirms and sends the Proforma Invoice within one business day.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/QuoteRequest"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Registered: reference, quotation link (priced models) or request for manual pricing",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "403": {
      "description": "Destination not served",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "422": {
      "description": "Invalid",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "429": {
      "description": "Daily limit reached",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Line": {
    "type": "object",
    "required": [
     "code",
     "quantity"
    ],
    "properties": {
     "code": {
      "type": "string",
      "example": "1NZ-FE"
     },
     "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 500
     }
    }
   },
   "Order": {
    "type": "object",
    "required": [
     "order_type",
     "lines"
    ],
    "properties": {
     "order_type": {
      "type": "string",
      "enum": [
       "first_order",
       "container_20ft",
       "container_40ft"
      ],
      "description": "first_order = new customer, 20/30/40 engines + optional gearboxes (LCL). container_20ft = 90 engines or 45+45. container_40ft = 130 or 65+65."
     },
     "lines": {
      "type": "array",
      "minItems": 1,
      "maxItems": 40,
      "items": {
       "$ref": "#/components/schemas/Line"
      }
     }
    }
   },
   "QuoteRequest": {
    "allOf": [
     {
      "$ref": "#/components/schemas/Order"
     },
     {
      "type": "object",
      "required": [
       "buyer"
      ],
      "properties": {
       "buyer": {
        "type": "object",
        "required": [
         "name",
         "country"
        ],
        "description": "Give email or phone.",
        "properties": {
         "name": {
          "type": "string"
         },
         "company": {
          "type": "string"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "phone": {
          "type": "string",
          "description": "With country code"
         },
         "country": {
          "type": "string",
          "description": "Destination country"
         }
        }
       },
       "destination_port": {
        "type": "string"
       },
       "purchase_preference": {
        "type": "string",
        "enum": [
         "remote",
         "visit",
         "help"
        ]
       },
       "notes": {
        "type": "string",
        "maxLength": 600
       },
       "agent": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "platform": {
          "type": "string"
         }
        }
       }
      }
     }
    ]
   }
  }
 }
}