{
 "openapi": "3.1.0",
 "info": {
  "title": "UTTPRO B2B API",
  "version": "1.0.0",
  "description": "Read-only API for linked business customers of UTTPRO. A client acts as the website member who created it. All identifiers are GUIDs; document numbers are labels only. Items carry the product alias, never the internal product name. Times are ISO 8601 (+08:00 unless the field says UTC); amounts are TWD."
 },
 "servers": [
  {
   "url": "https://api.uttpro.com"
  }
 ],
 "components": {
  "securitySchemes": {
   "oauth": {
    "type": "oauth2",
    "flows": {
     "clientCredentials": {
      "tokenUrl": "/oauth/token",
      "scopes": {
       "profile.read": "Member and company links",
       "quotes.read": "Quote list",
       "orders.read": "Sales orders and client purchase orders",
       "ar.read": "Receivables (needs a billing link)"
      }
     }
    }
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "request_id": {
      "type": "string",
      "format": "uuid",
      "description": "Quote this when contacting UTTPRO"
     }
    }
   }
  }
 },
 "security": [
  {
   "oauth": []
  }
 ],
 "paths": {
  "/oauth/token": {
   "post": {
    "summary": "Get an access token (client credentials, 15 minutes)",
    "security": [],
    "requestBody": {
     "content": {
      "application/x-www-form-urlencoded": {
       "schema": {
        "type": "object",
        "properties": {
         "grant_type": {
          "const": "client_credentials"
         },
         "client_id": {
          "type": "string",
          "format": "uuid",
          "description": "API client id"
         },
         "client_secret": {
          "type": "string"
         }
        }
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Token",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "access_token": {
           "type": "string"
          },
          "token_type": {
           "const": "Bearer"
          },
          "expires_in": {
           "type": "integer"
          },
          "scope": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "invalid_request / unsupported_grant_type"
     },
     "401": {
      "description": "invalid_client"
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/me": {
   "get": {
    "summary": "Member and the customer/company links it holds",
    "security": [
     {
      "oauth": [
       "profile.read"
      ]
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "member_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Website member"
          },
          "client": {
           "type": "object",
           "properties": {
            "client_id": {
             "type": "string",
             "format": "uuid",
             "description": "Client"
            },
            "name": {
             "type": "string"
            },
            "scopes": {
             "type": "array",
             "items": {
              "type": "string"
             }
            }
           }
          },
          "links": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "grant_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Link"
             },
             "customer_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Customer"
             },
             "customer_label": {
              "type": "string"
             },
             "company_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Issuing company"
             },
             "company_label": {
              "type": [
               "string",
               "null"
              ]
             },
             "contact_guid": {
              "type": [
               "string",
               "null"
              ],
              "format": "uuid"
             },
             "role": {
              "enum": [
               "buyer",
               "billing"
              ]
             },
             "expires_at": {
              "type": [
               "string",
               "null"
              ]
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/sales-orders": {
   "get": {
    "summary": "Approved sales orders for one customer and issuing company (50 per page)",
    "security": [
     {
      "oauth": [
       "orders.read"
      ]
     }
    ],
    "parameters": [
     {
      "name": "customer_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].customer_guid"
     },
     {
      "name": "company_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].company_guid"
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100000
      },
      "description": "Use next_offset from the previous page"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "customer_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Customer"
          },
          "company_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Issuing company"
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "sales_order_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Sales order"
             },
             "status": {
              "type": "string"
             },
             "client_po_reference": {
              "type": [
               "string",
               "null"
              ]
             },
             "total": {
              "type": "string",
              "description": "Decimal string"
             },
             "currency": {
              "type": "string"
             },
             "web_order_guid": {
              "type": [
               "string",
               "null"
              ],
              "format": "uuid"
             }
            }
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_offset": {
           "type": [
            "integer",
            "null"
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/purchase-orders": {
   "get": {
    "summary": "Client purchase orders you submitted, including withdrawn ones (50 per page)",
    "security": [
     {
      "oauth": [
       "orders.read"
      ]
     }
    ],
    "parameters": [
     {
      "name": "customer_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].customer_guid"
     },
     {
      "name": "company_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].company_guid"
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100000
      },
      "description": "Use next_offset from the previous page"
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "customer_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Customer"
          },
          "company_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Issuing company"
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "purchase_order_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Purchase order"
             },
             "reference": {
              "type": "string",
              "description": "Your PO reference (label)"
             },
             "document_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "note": {
              "type": [
               "string",
               "null"
              ]
             },
             "current_revision": {
              "type": "integer"
             },
             "revision_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Current revision"
             },
             "withdrawn_at": {
              "type": [
               "string",
               "null"
              ]
             },
             "file_guid": {
              "type": [
               "string",
               "null"
              ]
             },
             "file_sha256": {
              "type": [
               "string",
               "null"
              ]
             },
             "file_size": {
              "type": [
               "integer",
               "null"
              ]
             }
            }
           }
          },
          "has_more": {
           "type": "boolean"
          },
          "next_offset": {
           "type": [
            "integer",
            "null"
           ]
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/purchase-orders/{po}": {
   "get": {
    "summary": "One purchase order with its revisions and linked sales orders",
    "security": [
     {
      "oauth": [
       "orders.read"
      ]
     }
    ],
    "parameters": [
     {
      "name": "po",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     },
     {
      "name": "revision",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "purchase_order": {
           "type": "object",
           "properties": {
            "purchase_order_guid": {
             "type": "string",
             "format": "uuid",
             "description": "PO"
            },
            "customer_guid": {
             "type": "string",
             "format": "uuid",
             "description": "Customer"
            },
            "company_guid": {
             "type": "string",
             "format": "uuid",
             "description": "Company"
            },
            "current_revision": {
             "type": "integer"
            },
            "created_at": {
             "type": "string"
            },
            "withdrawn_at": {
             "type": [
              "string",
              "null"
             ]
            }
           }
          },
          "revision": {
           "type": "object",
           "properties": {
            "revision_guid": {
             "type": "string",
             "format": "uuid",
             "description": "Revision"
            },
            "revision": {
             "type": "integer"
            },
            "reference": {
             "type": "string"
            },
            "document_date": {
             "type": [
              "string",
              "null"
             ]
            },
            "note": {
             "type": [
              "string",
              "null"
             ]
            },
            "file_guid": {
             "type": [
              "string",
              "null"
             ]
            },
            "file_sha256": {
             "type": [
              "string",
              "null"
             ]
            },
            "file_size": {
             "type": [
              "integer",
              "null"
             ]
            },
            "created_at": {
             "type": "string"
            }
           }
          },
          "revisions": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "revision_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Revision"
             },
             "revision": {
              "type": "integer"
             },
             "reference": {
              "type": "string"
             },
             "document_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "file_guid": {
              "type": [
               "string",
               "null"
              ]
             },
             "created_at": {
              "type": "string"
             }
            }
           }
          },
          "sales_orders": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "sales_order_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Sales order"
             },
             "link_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Link"
             },
             "revoked_at": {
              "type": [
               "string",
               "null"
              ]
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/receivables": {
   "get": {
    "summary": "Receivables by delivery (100 per page, by due date). Needs a billing link for the customer and company.",
    "security": [
     {
      "oauth": [
       "ar.read"
      ]
     }
    ],
    "parameters": [
     {
      "name": "customer_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].customer_guid"
     },
     {
      "name": "company_guid",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "From /v1/me links[].company_guid"
     },
     {
      "name": "offset",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 0,
       "maximum": 100000
      },
      "description": "Use next_offset from the previous page"
     },
     {
      "name": "sales_order_guid",
      "in": "query",
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "customer_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Customer"
          },
          "company_guid": {
           "type": "string",
           "format": "uuid",
           "description": "Company"
          },
          "as_of_utc": {
           "type": "string",
           "description": "UTC"
          },
          "coverage": {
           "enum": [
            "partial",
            "unavailable"
           ]
          },
          "has_more": {
           "type": "boolean"
          },
          "next_offset": {
           "type": [
            "integer",
            "null"
           ]
          },
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "delivery_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Delivery"
             },
             "sales_order_guid": {
              "type": [
               "string",
               "null"
              ],
              "format": "uuid"
             },
             "delivery_reference": {
              "type": [
               "string",
               "null"
              ]
             },
             "invoice_reference": {
              "type": [
               "string",
               "null"
              ]
             },
             "shipping_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "invoice_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "due_date": {
              "type": [
               "string",
               "null"
              ]
             },
             "currency": {
              "const": "TWD"
             },
             "original_amount": {
              "type": [
               "number",
               "string",
               "null"
              ]
             },
             "applied_amount": {
              "type": [
               "number",
               "string",
               "null"
              ]
             },
             "open_amount": {
              "type": [
               "number",
               "string",
               "null"
              ]
             },
             "coverage": {
              "enum": [
               "complete",
               "unavailable"
              ]
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/v1/quotes": {
   "get": {
    "summary": "Quotes visible to the member (newest 100). Quote contents open on the website after e-mail verification.",
    "security": [
     {
      "oauth": [
       "quotes.read"
      ]
     }
    ],
    "responses": {
     "200": {
      "description": "OK",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "items": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "quote_guid": {
              "type": "string",
              "format": "uuid",
              "description": "Quote"
             },
             "number": {
              "type": "string",
              "description": "Label only"
             },
             "status": {
              "type": "string"
             },
             "handover_pending": {
              "type": "boolean"
             },
             "web_url": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "401": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "403": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "502": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "503": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  }
 }
}