{
  "openapi": "3.1.0",
  "info": {
    "title": "Invoity Document Review Link API",
    "version": "1.0.0",
    "description": "Prepare a financial-document draft and return a link where the user can review it in Invoity. This API never sends, saves, downloads, or finalizes a document."
  },
  "servers": [
    {
      "url": "https://invoity.com"
    }
  ],
  "paths": {
    "/api/ai/document-link": {
      "post": {
        "operationId": "createInvoityDocumentReviewLink",
        "summary": "Create a review link for a financial-document draft",
        "description": "Use only details supplied by the user. Omit unknown fields. The response opens an editable draft that requires human review; it does not take any external action.",
        "x-openai-isConsequential": false,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentDraft"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A private-fragment URL for human review",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReviewLinkResponse"
                }
              }
            }
          },
          "400": {
            "description": "The payload contains no supported document type or usable document field"
          },
          "429": {
            "description": "Rate limit exceeded"
          },
          "413": {
            "description": "Payload exceeds the 64 KB draft limit"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Party": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "name": { "type": "string", "maxLength": 120 },
          "email": { "type": "string", "maxLength": 254 },
          "phone": { "type": "string", "maxLength": 50 },
          "address": { "type": "string", "maxLength": 240 },
          "city": { "type": "string", "maxLength": 100 },
          "state": { "type": "string", "maxLength": 100 },
          "zip": { "type": "string", "maxLength": 32 },
          "country": { "type": "string", "maxLength": 80 },
          "taxId": { "type": "string", "maxLength": 80 }
        }
      },
      "LineItem": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "description": { "type": "string", "maxLength": 300 },
          "quantity": { "type": "number", "minimum": 0, "maximum": 1000000, "default": 1 },
          "rate": { "type": "number", "minimum": 0, "maximum": 1000000000, "default": 0 }
        }
      },
      "DocumentDraft": {
        "type": "object",
        "additionalProperties": false,
        "required": ["documentType"],
        "properties": {
          "documentType": {
            "type": "string",
            "enum": ["invoice", "tax-invoice", "proforma-invoice", "receipt", "sales-receipt", "cash-receipt", "quote", "estimate", "credit-note", "purchase-order", "delivery-note"]
          },
          "business": { "$ref": "#/components/schemas/Party" },
          "client": { "$ref": "#/components/schemas/Party" },
          "documentNumber": { "type": "string", "maxLength": 80 },
          "issueDate": { "type": "string", "format": "date" },
          "dueDate": { "type": "string", "format": "date" },
          "reference": { "type": "string", "maxLength": 120 },
          "currency": { "type": "string", "enum": ["USD", "CAD", "EUR", "GBP", "AUD", "NZD", "INR", "ZAR", "SGD", "AED"], "default": "USD" },
          "notes": { "type": "string", "maxLength": 1500 },
          "terms": { "type": "string", "maxLength": 1500 },
          "taxRate": { "type": "number", "minimum": 0, "maximum": 100 },
          "discountValue": { "type": "number", "minimum": 0, "maximum": 1000000000 },
          "shipping": { "type": "number", "minimum": 0, "maximum": 1000000000 },
          "amountPaid": { "type": "number", "minimum": 0, "maximum": 1000000000 },
          "paymentMethod": { "type": "string", "maxLength": 120 },
          "items": {
            "type": "array",
            "maxItems": 20,
            "items": { "$ref": "#/components/schemas/LineItem" }
          }
        }
      },
      "ReviewLinkResponse": {
        "type": "object",
        "required": ["review_url", "document_type", "requires_human_review", "action_taken"],
        "properties": {
          "review_url": { "type": "string", "format": "uri" },
          "document_type": { "type": "string" },
          "requires_human_review": { "type": "boolean", "const": true },
          "action_taken": { "type": "string", "const": "none" }
        }
      }
    }
  }
}