Store immutable supplier report or invoice evidence

POST /api/v1/internal/fulfilment/bookings/{bookingId}/lines/{lineId}/finance/artifacts

{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "fileName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "mediaType": {
            "type": "string",
            "enum": [
              "application/pdf",
              "text/csv",
              "application/json",
              "application/vnd.ms-excel",
              "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
            ]
          },
          "contentBase64": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2796204
          }
        },
        "required": [
          "fileName",
          "mediaType",
          "contentBase64"
        ],
        "additionalProperties": false
      }
    }
  }
}

{
  "x-response-schema-completeness": "modeled",
  "x-rate-limit": {
    "requests": 300,
    "windowMilliseconds": 60000,
    "key": "request IP",
    "headers": [
      "x-ratelimit-limit",
      "x-ratelimit-remaining",
      "x-ratelimit-reset"
    ]
  },
  "x-idempotency": {
    "policy": "not-generalized",
    "note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
  },
  "x-human-only": true,
  "x-required-human-permissions": [],
  "x-internal-staff-only": true,
  "x-staff-authority": "server-owned revocable membership and explicit client assignments",
  "x-body-limit-bytes": 2800300
}

{
  "operationId": "post_api_v1_internal_fulfilment_bookings_bookingId_lines_lineId_finance_artifacts",
  "summary": "Store immutable supplier report or invoice evidence",
  "description": "Internal staff surface. Client data is restricted to explicit server-owned customer assignments; inaccessible resources return 404. Product/channel entitlements also apply.\n\nRequires a verified Supabase human web session and active, revocable database-owned staff membership. Customer operator permissions, request headers and delegated agents cannot grant staff access. The session endpoint returns access:false to nonstaff without staff or customer identifiers.\n\nThe request schema is generated from the runtime Zod input validator. Cross-field refinements and state-dependent constraints are additionally enforced by the API.",
  "tags": [
    "Internal"
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "parameters": [
    {
      "name": "bookingId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1
      }
    },
    {
      "name": "lineId",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 1
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "fileName": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "mediaType": {
              "type": "string",
              "enum": [
                "application/pdf",
                "text/csv",
                "application/json",
                "application/vnd.ms-excel",
                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
              ]
            },
            "contentBase64": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2796204
            }
          },
          "required": [
            "fileName",
            "mediaType",
            "contentBase64"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "400": {
      "description": "Invalid request or unsupported fields",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "403": {
      "description": "Permission or product scope refused",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "404": {
      "description": "Route or tenant-scoped resource not found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "409": {
      "description": "State, revision, approval, funding or idempotency conflict",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "422": {
      "description": "Supplier configuration, capability or upstream refusal",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "429": {
      "description": "Rate limit reached; wait before retrying",
      "headers": {
        "x-ratelimit-limit": {
          "description": "Maximum requests permitted in the current rate-limit window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-remaining": {
          "description": "Requests remaining in the current window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-reset": {
          "description": "Seconds until the current rate-limit window resets.",
          "schema": {
            "type": "integer"
          }
        },
        "retry-after": {
          "description": "Minimum seconds to wait before retrying.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "500": {
      "description": "Internal error; inspect state before retrying a mutation",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "503": {
      "description": "Dependency or authentication verifier unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Error"
          }
        }
      }
    },
    "2XX": {
      "description": "Successful response.",
      "headers": {
        "x-ratelimit-limit": {
          "description": "Maximum requests permitted in the current rate-limit window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-remaining": {
          "description": "Requests remaining in the current window.",
          "schema": {
            "type": "integer"
          }
        },
        "x-ratelimit-reset": {
          "description": "Seconds until the current rate-limit window resets.",
          "schema": {
            "type": "integer"
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "artifact": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "campaignId": {
                    "type": "string"
                  },
                  "sha256": {
                    "type": "string"
                  },
                  "byteSize": {
                    "type": "integer"
                  },
                  "mediaType": {
                    "type": "string"
                  },
                  "fileName": {
                    "type": "string"
                  },
                  "uploadedBy": {
                    "type": "string"
                  },
                  "uploadedActor": {
                    "type": "string"
                  },
                  "uploadedSource": {
                    "type": "string"
                  },
                  "uploadedAt": {
                    "type": "string"
                  },
                  "uploadedClientId": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "campaignId",
                  "sha256",
                  "byteSize",
                  "mediaType",
                  "fileName",
                  "uploadedBy",
                  "uploadedActor",
                  "uploadedSource",
                  "uploadedAt"
                ],
                "additionalProperties": false
              },
              "replayed": {
                "type": "boolean"
              }
            },
            "required": [
              "artifact",
              "replayed"
            ],
            "additionalProperties": false
          }
        }
      }
    }
  },
  "x-response-schema-completeness": "modeled",
  "x-rate-limit": {
    "requests": 300,
    "windowMilliseconds": 60000,
    "key": "request IP",
    "headers": [
      "x-ratelimit-limit",
      "x-ratelimit-remaining",
      "x-ratelimit-reset"
    ]
  },
  "x-idempotency": {
    "policy": "not-generalized",
    "note": "There is no universal Idempotency-Key middleware. Only the documented endpoint mechanisms protect retries."
  },
  "x-human-only": true,
  "x-required-human-permissions": [],
  "x-internal-staff-only": true,
  "x-staff-authority": "server-owned revocable membership and explicit client assignments",
  "x-body-limit-bytes": 2800300
}