{
  "openapi": "3.1.0",
  "info": {
    "title": "Emi · API para agentes",
    "version": "1.0.0",
    "description": "Charity marketplace in Ecuador: every piece was donated and the money goes to the foundation shown. Search pieces and create orders that the buyer pays through payment_url (Payphone). Agents never handle card data. Prices in USD, VAT included. Content in Spanish."
  },
  "servers": [
    {
      "url": "https://emiloop.com"
    }
  ],
  "paths": {
    "/api/agent/products": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Search donated pieces for sale",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Free text in Spanish or English"
          },
          {
            "name": "max_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "min_price",
            "in": "query",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "foundation",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "producto",
                "servicio",
                "experiencia"
              ]
            }
          },
          {
            "name": "condition",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "new",
                "used"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            },
            "description": "Integer from 1 to 50. Any other value returns 400."
          }
        ],
        "responses": {
          "200": {
            "description": "Results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "url": {
                            "type": "string"
                          },
                          "image": {
                            "type": "string"
                          },
                          "type": {
                            "type": "string",
                            "enum": [
                              "producto",
                              "servicio",
                              "experiencia"
                            ]
                          },
                          "condition": {
                            "type": "string",
                            "enum": [
                              "new",
                              "used"
                            ]
                          },
                          "condition_detail": {
                            "type": "string",
                            "nullable": true
                          },
                          "price": {
                            "type": "number"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "reference_price": {
                            "type": "number"
                          },
                          "discount_pct": {
                            "type": "integer"
                          },
                          "available": {
                            "type": "integer"
                          },
                          "foundation": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "url": {
                                "type": "string"
                              }
                            }
                          },
                          "donor": {
                            "type": "string",
                            "nullable": true
                          },
                          "description": {
                            "type": "string"
                          },
                          "includes": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "delivery": {
                            "type": "string"
                          },
                          "delivery_options": {
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": [
                                "online",
                                "domicilio",
                                "retiro"
                              ]
                            }
                          },
                          "delivered_as": {
                            "type": "string",
                            "enum": [
                              "physical_item",
                              "voucher_code"
                            ]
                          },
                          "impact": {
                            "type": "string",
                            "nullable": true
                          },
                          "promoted": {
                            "type": "boolean"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameter (for example limit outside 1-50)"
          }
        }
      }
    },
    "/api/agent/products/{id}": {
      "get": {
        "operationId": "getProduct",
        "summary": "One piece",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Piece",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "image": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string",
                      "enum": [
                        "producto",
                        "servicio",
                        "experiencia"
                      ]
                    },
                    "condition": {
                      "type": "string",
                      "enum": [
                        "new",
                        "used"
                      ]
                    },
                    "condition_detail": {
                      "type": "string",
                      "nullable": true
                    },
                    "price": {
                      "type": "number"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "reference_price": {
                      "type": "number"
                    },
                    "discount_pct": {
                      "type": "integer"
                    },
                    "available": {
                      "type": "integer"
                    },
                    "foundation": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "url": {
                          "type": "string"
                        }
                      }
                    },
                    "donor": {
                      "type": "string",
                      "nullable": true
                    },
                    "description": {
                      "type": "string"
                    },
                    "includes": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "delivery": {
                      "type": "string"
                    },
                    "delivery_options": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "enum": [
                          "online",
                          "domicilio",
                          "retiro"
                        ]
                      }
                    },
                    "delivered_as": {
                      "type": "string",
                      "enum": [
                        "physical_item",
                        "voucher_code"
                      ]
                    },
                    "impact": {
                      "type": "string",
                      "nullable": true
                    },
                    "promoted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/agent/foundations": {
      "get": {
        "operationId": "listFoundations",
        "summary": "Foundations and what their money achieves",
        "responses": {
          "200": {
            "description": "Foundations",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/agent/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "Reserve pieces for 30 minutes and get a payment_url for the buyer",
        "description": "Ask the buyer before calling. Requires their real details; the Ecuadorian cédula (10 digits) or RUC (13 digits) is needed for the receipt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "items",
                  "buyer"
                ],
                "properties": {
                  "items": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                      "type": "object",
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "quantity": {
                          "type": "integer",
                          "minimum": 1,
                          "maximum": 20
                        }
                      }
                    }
                  },
                  "buyer": {
                    "type": "object",
                    "required": [
                      "name",
                      "id_number",
                      "email",
                      "phone"
                    ],
                    "properties": {
                      "name": {
                        "type": "string"
                      },
                      "id_number": {
                        "type": "string"
                      },
                      "email": {
                        "type": "string"
                      },
                      "phone": {
                        "type": "string"
                      }
                    }
                  },
                  "delivery": {
                    "type": "string",
                    "enum": [
                      "retiro",
                      "envio"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order awaiting payment",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "awaiting_payment",
                        "paid",
                        "expired",
                        "cancelled",
                        "under_review"
                      ]
                    },
                    "total": {
                      "type": "number"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "payment_url": {
                      "type": "string",
                      "description": "Give this URL to the buyer to pay. Present only while awaiting payment."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status_url": {
                      "type": "string"
                    },
                    "next_step": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid data (for example delivery other than retiro or envio)"
          },
          "409": {
            "description": "Some pieces are no longer available, or the quantity is above what one order can reserve"
          },
          "429": {
            "description": "Too many pending orders or requests"
          },
          "503": {
            "description": "Orders from assistants are not available right now"
          }
        }
      }
    },
    "/api/agent/orders/{id}": {
      "get": {
        "operationId": "getOrderStatus",
        "summary": "Order status",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "order_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "awaiting_payment",
                        "paid",
                        "expired",
                        "cancelled",
                        "under_review"
                      ]
                    },
                    "total": {
                      "type": "number"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "items": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "payment_url": {
                      "type": "string",
                      "description": "Give this URL to the buyer to pay. Present only while awaiting payment."
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "status_url": {
                      "type": "string"
                    },
                    "next_step": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    }
  }
}