{
  "Protocol": "AIXE",
  "Version": "1.0",
  "Endpoint": "/aixe/works/create-invoice",
  "DiscoveryRequest": "GET /aixe/works/create-invoice/?",
  "CanonicalHelpTrigger": "GET /aixe/works/create-invoice/?",
  "ActionRequest": "POST /aixe/works/create-invoice",
  "Method": "POST",
  "ContentType": "application/json; charset=utf-8",
  "Title": "Create Invoice",
  "AuthenticationRequired": false,
  "DataIsFictional": true,
  "Purpose": "Create an invoice header for a customer and automatically assign the next compact sequential invoice number when the caller does not provide one.",
  "DocumentationSource": "AIXEEndpointRegistry",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe",
    "IncludeIn": [
      "/aixe.ai starter discovery documents",
      "Every endpoint self-description returned by GET /endpoint/?"
    ],
    "AIInstruction": "Read this live endpoint contract as operational guidance, not merely as a transport schema. Use its purpose, field meanings, business rules, outcomes, and recovery guidance to reason about whether and how to perform the capability."
  },
  "AutomaticInvoiceNumber": {
    "Format": "INV-[sequential number]",
    "Example": "INV-4018",
    "InputPolicy": "InvoiceNumber is output-only. Do not include InvoiceNumber in the POST body.",
    "Rule": "The endpoint always finds the highest existing numeric INV- number in the shared Bayline company and assigns the next number. Existing legacy invoice numbers with a nonnumeric suffix remain unchanged and do not affect the sequence."
  },
  "UsageGuidance": "Never send InvoiceNumber. Preserve the returned InvoiceKey for adding detail lines and use the returned system-generated InvoiceNumber when speaking to the human about the invoice.",
  "AIUsageGuidance": {
    "ContractRole": "This live document teaches an AI what the capability means and how to use it; it is not merely a list of request fields.",
    "ReasoningInstruction": "Decide whether this capability serves the human's intent from Purpose and BusinessRules, gather values using each field's Description and constraints, then interpret the returned SuccessCode before reporting an outcome.",
    "FieldInstruction": "Field names are transport labels. Their Description, source, constraints, and business meaning explain what information the AI should obtain and why."
  },
  "RequiredFields": {
    "AIXEWorksKey": {
      "Type": "string",
      "Description": "The opaque public key returned by the Works connect or start capability. It selects the permanent shared fictional Bayline A/C Supply company; it is context, not an authentication credential.",
      "Required": true,
      "SubmittedIn": "JSON body"
    },
    "CustomerKey": {
      "Type": "string",
      "Description": "The public key of the customer selected from a Works search, create, or detail response.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "InvoiceDate": {
      "Type": "string (date-time)",
      "Description": "The business date on which the invoice was issued.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "InvoiceDueDate": {
      "Type": "string (date-time)",
      "Description": "The date by which the invoice balance is expected to be paid.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "InvoiceStatus": {
      "Type": "string",
      "Description": "The invoice's current business workflow state.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "AllowedValues": [
        "Draft",
        "Open",
        "PartiallyPaid",
        "Paid",
        "Void"
      ]
    },
    "InvoiceNotes": {
      "Type": "string",
      "Description": "Free-form business notes associated with the invoice header.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "InvoiceTaxAmount": {
      "Type": "number",
      "Description": "The tax amount applied to the invoice.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "MinValue": 0
    }
  },
  "BusinessRules": [
    "Public fictional demo: no PersonKey, WorkmatePersonKey, SupervisorPersonKey, profile key, site login, or other identity credential is required. AIXEWorksKey only selects the permanent shared Bayline A/C Supply company; it is not an authentication credential.",
    "Except for connect and start, AIXEWorksKey is required. Records in the shared company persist and remain available to future visitors unless intentionally deleted through a documented record-level CRUD capability. Only public keys are returned; internal numeric identifiers are never part of the contract.",
    "InvoiceNumber is system-generated and output-only. The calling AI must never include InvoiceNumber in the request.",
    "If InvoiceNumber is submitted—even as a blank string—the request fails without creating an invoice.",
    "Every successful create assigns the next compact sequential number in INV-[number] format.",
    "Add products or services with create-invoice-detail. Totals are recalculated from detail lines. Record payments later with update-invoice."
  ],
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "One or more required request values are missing or malformed.",
      "Recovery": "Use the field descriptions and constraints in this same live contract, correct the named fields, and retry the same capability.",
      "Recoverable": true
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "A submitted public key did not identify a record within this endpoint's declared scope.",
      "Recovery": "Re-check the selected key against a current list or creation response; do not treat this as a missing web route.",
      "Recoverable": true
    },
    {
      "SuccessCode": "BUSINESS_RULE_FAILED",
      "Meaning": "The request was understood but could not run because a declared business or state-transition rule was not satisfied.",
      "Recovery": "Explain the governing rule to the human and retry only after the required business condition or decision changes.",
      "Recoverable": true
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "The endpoint could not complete the operation for a non-business-rule execution failure.",
      "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.",
      "Recoverable": false
    }
  ],
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "FailureCodes": [
      "VALIDATION_FAILED",
      "NOT_FOUND",
      "BUSINESS_RULE_FAILED",
      "FAILED"
    ],
    "NonFinalCodes": [],
    "MissingOrEmptyResponse": "Treat as FAILED.",
    "Rule": "The endpoint response is authoritative. Only an exact SuccessCode value listed in SuccessCodes means the business action succeeded; HTTP status alone does not declare the AIXE outcome."
  }
}