{
 "openapi": "3.1.0",
 "info": {
  "title": "Triplicate API",
  "version": "1.0.0",
  "description": "Create matching export documents (proforma invoice, commercial invoice, packing list, shipping instruction) from order data, search HS codes and calculate shipments. Free, no key; nothing is stored. The documents endpoint returns a link that opens Triplicate's generator filled in, where the user reviews and saves the PDF. MCP server: https://api.triplicatedocs.com/mcp",
  "contact": {
   "url": "https://triplicatedocs.com/developers/"
  }
 },
 "servers": [
  {
   "url": "https://api.triplicatedocs.com"
  }
 ],
 "paths": {
  "/api/v1/documents": {
   "post": {
    "operationId": "createTradeDocuments",
    "summary": "Create export documents from order data",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "language": {
          "type": "string",
          "enum": [
           "en",
           "zh",
           "ar",
           "fr",
           "es",
           "pt",
           "ru",
           "tr",
           "hi",
           "ur",
           "bn",
           "id",
           "vi",
           "ja",
           "ko"
          ],
          "description": "Language of the generator page the link opens (documents are in English)",
          "default": "en"
         },
         "open_document": {
          "type": "string",
          "enum": [
           "pi",
           "ci",
           "pl",
           "si"
          ],
          "description": "pi proforma invoice, ci commercial invoice, pl packing list, si shipping instruction",
          "default": "ci"
         },
         "document": {
          "type": "object",
          "properties": {
           "number": {
            "type": "string",
            "description": "Invoice number"
           },
           "date": {
            "type": "string",
            "description": "YYYY-MM-DD"
           },
           "po": {
            "type": "string",
            "description": "Buyer's PO / contract number"
           },
           "valid_days": {
            "type": "number",
            "description": "Proforma validity in days"
           }
          }
         },
         "seller": {
          "type": "object",
          "properties": {
           "name": {
            "type": "string"
           },
           "address": {
            "type": "string",
            "description": "Full address, lines separated by \\n"
           },
           "tel": {
            "type": "string"
           },
           "email": {
            "type": "string"
           },
           "tax_id": {
            "type": "string",
            "description": "Tax / VAT / business registration number"
           }
          },
          "required": [
           "name"
          ],
          "description": "Seller / shipper / exporter"
         },
         "buyer": {
          "type": "object",
          "properties": {
           "name": {
            "type": "string"
           },
           "address": {
            "type": "string",
            "description": "Full address, lines separated by \\n"
           },
           "tel": {
            "type": "string"
           },
           "email": {
            "type": "string"
           },
           "tax_id": {
            "type": "string",
            "description": "Tax / VAT / business registration number"
           }
          },
          "required": [
           "name"
          ],
          "description": "Buyer / consignee / importer"
         },
         "notify": {
          "type": "object",
          "properties": {
           "name": {
            "type": "string"
           },
           "address": {
            "type": "string"
           }
          },
          "description": "Notify party, if different from the buyer"
         },
         "terms": {
          "type": "object",
          "properties": {
           "incoterm": {
            "type": "string",
            "enum": [
             "EXW",
             "FCA",
             "FAS",
             "FOB",
             "CFR",
             "CIF",
             "CPT",
             "CIP",
             "DAP",
             "DPU",
             "DDP"
            ]
           },
           "place": {
            "type": "string",
            "description": "Named place, e.g. 'Busan' for FOB Busan"
           },
           "payment": {
            "type": "string",
            "description": "e.g. 'T/T 30% deposit, 70% before shipment'"
           },
           "currency": {
            "type": "string",
            "enum": [
             "USD",
             "EUR",
             "GBP",
             "JPY",
             "CNY",
             "KRW",
             "VND"
            ]
           }
          }
         },
         "shipment": {
          "type": "object",
          "properties": {
           "port_of_loading": {
            "type": "string"
           },
           "port_of_discharge": {
            "type": "string"
           },
           "vessel_or_flight": {
            "type": "string"
           },
           "etd": {
            "type": "string",
            "description": "YYYY-MM-DD"
           },
           "country_of_origin": {
            "type": "string"
           }
          }
         },
         "charges": {
          "type": "object",
          "properties": {
           "freight": {
            "type": "number"
           },
           "insurance": {
            "type": "number"
           },
           "discount": {
            "type": "number"
           }
          }
         },
         "items": {
          "type": "array",
          "maxItems": 100,
          "items": {
           "type": "object",
           "properties": {
            "description": {
             "type": "string"
            },
            "hs_code": {
             "type": "string"
            },
            "quantity": {
             "type": "number"
            },
            "unit": {
             "type": "string",
             "enum": [
              "PCS",
              "SETS",
              "BOXES",
              "PAIRS",
              "KG",
              "M"
             ]
            },
            "unit_price": {
             "type": "number"
            },
            "pieces_per_carton": {
             "type": "number"
            },
            "net_weight_per_carton_kg": {
             "type": "number"
            },
            "gross_weight_per_carton_kg": {
             "type": "number"
            },
            "carton_length_cm": {
             "type": "number"
            },
            "carton_width_cm": {
             "type": "number"
            },
            "carton_height_cm": {
             "type": "number"
            }
           },
           "required": [
            "description",
            "quantity"
           ]
          }
         },
         "shipping_marks": {
          "type": "string",
          "description": "Optional; generated from buyer, destination and carton count if empty"
         },
         "bank": {
          "type": "object",
          "properties": {
           "bank_name": {
            "type": "string"
           },
           "swift": {
            "type": "string"
           },
           "account": {
            "type": "string"
           },
           "beneficiary": {
            "type": "string"
           },
           "bank_address": {
            "type": "string"
           }
          }
         },
         "signer": {
          "type": "object",
          "properties": {
           "name": {
            "type": "string"
           },
           "title": {
            "type": "string"
           }
          }
         }
        },
        "required": [
         "seller",
         "buyer",
         "items"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Link to the filled-in documents, totals and checks",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "url": {
           "type": "string",
           "description": "Open this link to review the documents and save the PDF"
          },
          "opens": {
           "type": "string"
          },
          "totals": {
           "type": "object"
          },
          "checks": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "severity": {
              "type": "string",
              "enum": [
               "error",
               "warning",
               "note"
              ]
             },
             "message": {
              "type": "string"
             }
            }
           }
          },
          "notes": {
           "type": "array",
           "items": {
            "type": "string"
           }
          },
          "next": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "detail": {
           "type": "string"
          }
         }
        }
       }
      }
     },
     "429": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "detail": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/hs": {
   "post": {
    "operationId": "lookupHsCode",
    "summary": "Search HS 2022 codes (6 digits) by English description or code prefix",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "query": {
          "type": "string"
         },
         "limit": {
          "type": "integer",
          "default": 8
         }
        },
        "required": [
         "query"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Candidate codes",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "detail": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/shipment": {
   "post": {
    "operationId": "calculateShipment",
    "summary": "CBM, chargeable weight and container fit from carton sizes",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "cartons": {
          "type": "array",
          "items": {
           "type": "object",
           "properties": {
            "length_cm": {
             "type": "number"
            },
            "width_cm": {
             "type": "number"
            },
            "height_cm": {
             "type": "number"
            },
            "quantity": {
             "type": "number"
            },
            "gross_weight_kg": {
             "type": "number"
            }
           },
           "required": [
            "length_cm",
            "width_cm",
            "height_cm",
            "quantity"
           ]
          }
         }
        },
        "required": [
         "cartons"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Totals",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "400": {
      "description": "Error",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "error": {
           "type": "string"
          },
          "detail": {
           "type": "string"
          }
         }
        }
       }
      }
     }
    }
   }
  }
 }
}