PDF-Anhang für einen PDF-Upload reservieren

{
  "operationId": "post_v2_layout_list_pdfattachment",
  "summary": "PDF-Anhang für einen PDF-Upload reservieren",
  "description": "Reserviert einen PDF-Anhang oder eine PDF-Hintergrundvorlage für ein eigenes layoutpdf und liefert eine signierte upload_url. Der tatsächliche Objekttyp folgt data.type, unabhängig vom URL-Untertyp. Höchstens zwei Anhänge und eine Hintergrundvorlage pro PDF-Layout sind erlaubt. Dateiname muss mit kleinem .pdf enden und nach SQL-Escaping höchstens 150 Zeichen lang sein; MIME-Typ ist application/pdf. file_size wird zu int normalisiert und muss 21 bis 1.500.000 Bytes für Anhänge bzw. bis 1.000.000 Bytes für Hintergrundvorlagen betragen. Nach separatem Upload muss verify_object aufgerufen werden; URLs sind vertraulich.",
  "tags": [
    "layout"
  ],
  "security": [
    {
      "bearerAuth": [],
      "accountContext": []
    },
    {
      "sessionCookie": [],
      "accountContext": []
    }
  ],
  "parameters": [
    {
      "name": "X-Edoobox-If-Revision",
      "in": "header",
      "required": false,
      "schema": {
        "type": "string",
        "pattern": "^[a-f0-9]{32}$",
        "examples": [
          "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
        ]
      },
      "description": "Optional account mutation revision from a preceding authenticated auth-context snapshot. The dispatcher compares it while holding the account lock; mismatch409 requires a new review."
    }
  ],
  "responses": {
    "200": {
      "description": "data enthält insert=true, die öffentliche Uploadobjekt-ID und upload_url.",
      "content": {
        "application/json": {
          "example": {
            "success": true,
            "error": false,
            "data": {
              "insert": true,
              "id": "layoutpdfattachment_012345abcdef_123456",
              "upload_url": "https://storage.example.invalid/synthetic-layout-upload"
            }
          },
          "schema": {
            "type": "object",
            "properties": {
              "success": {
                "type": "boolean"
              },
              "error": {
                "type": [
                  "boolean",
                  "string"
                ]
              },
              "error_code": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "properties": {
                  "insert": {
                    "const": true
                  },
                  "id": {
                    "oneOf": [
                      {
                        "type": "string",
                        "pattern": "^layoutpdfattachment_[a-f0-9]{12}_-?[0-9]+$",
                        "description": "Öffentliche v2-ID aus diesem Konto; keine Datenbank-ID. Beispiel ist synthetisch.",
                        "examples": [
                          "layoutpdfattachment_012345abcdef_123456"
                        ]
                      },
                      {
                        "type": "string",
                        "pattern": "^layoutpdftemplate_[a-f0-9]{12}_-?[0-9]+$",
                        "description": "Öffentliche v2-ID aus diesem Konto; keine Datenbank-ID. Beispiel ist synthetisch.",
                        "examples": [
                          "layoutpdftemplate_012345abcdef_123456"
                        ]
                      }
                    ]
                  },
                  "upload_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Vertrauliche signierte Upload-URL."
                  }
                },
                "additionalProperties": true,
                "required": [
                  "insert",
                  "id",
                  "upload_url"
                ]
              },
              "type": {
                "type": "string"
              }
            },
            "additionalProperties": true
          }
        }
      },
      "headers": {
        "X-Edoobox-Revision": {
          "schema": {
            "type": "string",
            "pattern": "^[a-f0-9]{32}$"
          },
          "description": "Rotated account revision supplied for the next action in one reviewed sequence."
        }
      }
    },
    "400": {
      "description": "Invalid request.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED40006"
          }
        }
      }
    },
    "401": {
      "description": "Missing/expired token, missing account context, account paused or model-specific authorization failure.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED40103"
          }
        }
      }
    },
    "402": {
      "description": "Missing/invalid action data or subscription/operation restriction.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED80100"
          }
        }
      }
    },
    "403": {
      "description": "Permission denied. Browser CORS rejection may have an empty body.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED40340"
          }
        }
      }
    },
    "404": {
      "description": "Unknown resource/action or unsupported method.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED80019"
          }
        }
      }
    },
    "409": {
      "description": "The account changed after the reviewed read. No domain operation is dispatched; obtain fresh state and review again.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "example": {
            "error": "ED40901",
            "error_code": "mutation_revision_conflict"
          }
        }
      }
    },
    "422": {
      "description": "Validation failed.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED80020"
          }
        }
      }
    },
    "429": {
      "description": "Request/login rate limit exceeded. Honor Retry-After when supplied; legacy rate-limit paths may omit it. Retry only proven reads within a bounded deadline; a mutation is never automatically replayed after an ambiguous response.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED42902"
          }
        }
      },
      "headers": {
        "Retry-After": {
          "description": "Optional server delay in whole seconds or an HTTP date. Absence is not permission for an immediate retry.",
          "schema": {
            "type": "string",
            "examples": [
              "30"
            ]
          }
        }
      }
    },
    "502": {
      "description": "Server-side operation failed.",
      "content": {
        "application/json": {
          "example": {
            "success": false,
            "error": "ED50201"
          }
        }
      }
    },
    "503": {
      "description": "The account mutation lock or revision store is unavailable. No unprotected fallback is executed.",
      "headers": {
        "Retry-After": {
          "schema": {
            "type": "integer",
            "const": 1
          }
        }
      },
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          },
          "example": {
            "error": "ED50301",
            "error_code": "mutation_revision_busy"
          }
        }
      }
    }
  },
  "x-edoobox-mutates-state": true,
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "data": {
              "type": "object",
              "properties": {
                "layoutpdf": {
                  "type": "string",
                  "pattern": "^layoutpdf_[a-f0-9]{12}_-?[0-9]+$",
                  "description": "Opaque layoutpdf v2 ID returned by this account. Synthetic example is not a real record.",
                  "examples": [
                    "layoutpdf_012345abcdef_123456"
                  ]
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "pdfattachment",
                    "pdftemplate"
                  ],
                  "description": "The common _addObject handler selects the stored object type from this payload field; both URL branches delegate to the same handler."
                },
                "file_name": {
                  "type": "string",
                  "minLength": 5,
                  "pattern": "\\.pdf$",
                  "examples": [
                    "attendance.pdf"
                  ],
                  "maxLength": 150,
                  "description": "Native PDF filename requires raw UTF-8 length<=150 and SQL-escaped storage length<=150 before presign/reservation. Existing lowercase .pdf and size/type rules remain; quote/backslash-rich names can reach the encoded limit earlier."
                },
                "file_type": {
                  "const": "application/pdf"
                },
                "file_size": {
                  "minimum": 21,
                  "maximum": 1500000,
                  "description": "PHP-int-Normalisierung; nach der Normalisierung müssen 21 bis 1.500.000 (Anhang) bzw. 1.000.000 (Hintergrund) Bytes vorliegen. Numerische JSON-Zeichenfolgen werden ebenfalls normalisiert.",
                  "x-edoobox-canonicalType": "integer"
                }
              },
              "required": [
                "layoutpdf",
                "type",
                "file_name",
                "file_type",
                "file_size"
              ],
              "additionalProperties": true,
              "anyOf": [
                {
                  "properties": {
                    "type": {
                      "const": "pdfattachment"
                    },
                    "file_size": {
                      "maximum": 1500000
                    }
                  },
                  "required": [
                    "type",
                    "file_size"
                  ]
                },
                {
                  "properties": {
                    "type": {
                      "const": "pdftemplate"
                    },
                    "file_size": {
                      "maximum": 1000000
                    }
                  },
                  "required": [
                    "type",
                    "file_size"
                  ]
                }
              ]
            }
          },
          "required": [
            "data"
          ],
          "additionalProperties": true
        },
        "examples": {
          "request": {
            "summary": "PDF-Anhang für einen PDF-Upload reservieren",
            "value": {
              "data": {
                "layoutpdf": "layoutpdf_012345abcdef_123456",
                "type": "pdfattachment",
                "file_name": "Unterlage.pdf",
                "file_type": "application/pdf",
                "file_size": 1024
              }
            }
          }
        }
      }
    }
  },
  "x-edoobox-upload-ticket": {
    "provider": "s3",
    "bucketEnv": "AWS_S3_BUCKET",
    "regionEnv": "AWS_S3_REGION",
    "urlPointer": "/data/upload_url",
    "pathPrefixTemplate": "/ED{fid}F_{appVersion}/mail/",
    "method": "PUT",
    "minBytes": 21,
    "mimeType": "application/pdf",
    "expiresInSeconds": 1800,
    "source": {
      "file": "application/libraries/edoobox/integrations/file/File.php",
      "line": 296
    },
    "maxBytes": 1500000,
    "workflowSelector": {
      "requestPointer": "/body/data/type",
      "variants": {
        "pdfattachment": {
          "metadataCreatedBeforeTransfer": true,
          "requiresApiFinalization": true,
          "scope": "object",
          "finalization": {
            "operationId": "put_v2_layout_id_pdfattachment_verify_object",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "scope": "object",
            "after": "successful-storage-transfer"
          },
          "readback": {
            "operationId": "get_v2_layout_id_pdfattachment",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "proves": "native-verification-record"
          },
          "abort": {
            "operationId": "delete_v2_layout_id_pdfattachment_remove_object",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "storageCleanup": "native-delete-attempt"
          },
          "successCriteria": {
            "responsePointers": {
              "/error": false,
              "/data/verify": true
            },
            "readbackRecord": {
              "verify": true
            }
          },
          "notes": [
            "Verify, readback and removal use the newly returned layout child ID, never the parent layoutpdf ID.",
            "Native verification checks storage bytes and MIME before marking the child verified. PDF import validation is not a formal PDF/A certification.",
            "Native removal attempts storage deletion for pending and verified uploads before deleting metadata. Storage cleanup is not guaranteed after a reported failure.",
            "Native deletion does not revoke a previously issued presigned URL. Do not race an in-flight transfer with abort; a late PUT can recreate an orphaned object."
          ]
        },
        "pdftemplate": {
          "metadataCreatedBeforeTransfer": true,
          "requiresApiFinalization": true,
          "scope": "object",
          "finalization": {
            "operationId": "put_v2_layout_id_pdftemplate_verify_object",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "scope": "object",
            "after": "successful-storage-transfer"
          },
          "readback": {
            "operationId": "get_v2_layout_id_pdftemplate",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "proves": "native-verification-record"
          },
          "abort": {
            "operationId": "delete_v2_layout_id_pdftemplate_remove_object",
            "argumentBindings": [
              {
                "target": "/path/id",
                "source": "/data/id"
              }
            ],
            "storageCleanup": "native-delete-attempt"
          },
          "successCriteria": {
            "responsePointers": {
              "/error": false,
              "/data/verify": true
            },
            "readbackRecord": {
              "verify": true
            }
          },
          "notes": [
            "Verify, readback and removal use the newly returned layout child ID, never the parent layoutpdf ID.",
            "Native verification checks storage bytes and MIME before marking the child verified. PDF import validation is not a formal PDF/A certification.",
            "Native removal attempts storage deletion for pending and verified uploads before deleting metadata. Storage cleanup is not guaranteed after a reported failure.",
            "Native deletion does not revoke a previously issued presigned URL. Do not race an in-flight transfer with abort; a late PUT can recreate an orphaned object."
          ]
        }
      }
    },
    "workflow": {
      "metadataCreatedBeforeTransfer": true,
      "requiresApiFinalization": true,
      "scope": "object",
      "finalization": {
        "operationId": "put_v2_layout_id_pdfattachment_verify_object",
        "argumentBindings": [
          {
            "target": "/path/id",
            "source": "/data/id"
          }
        ],
        "scope": "object",
        "after": "successful-storage-transfer"
      },
      "readback": {
        "operationId": "get_v2_layout_id_pdfattachment",
        "argumentBindings": [
          {
            "target": "/path/id",
            "source": "/data/id"
          }
        ],
        "proves": "native-verification-record"
      },
      "abort": {
        "operationId": "delete_v2_layout_id_pdfattachment_remove_object",
        "argumentBindings": [
          {
            "target": "/path/id",
            "source": "/data/id"
          }
        ],
        "storageCleanup": "native-delete-attempt"
      },
      "successCriteria": {
        "responsePointers": {
          "/error": false,
          "/data/verify": true
        },
        "readbackRecord": {
          "verify": true
        }
      },
      "notes": [
        "Verify, readback and removal use the newly returned layout child ID, never the parent layoutpdf ID.",
        "Native verification checks storage bytes and MIME before marking the child verified. PDF import validation is not a formal PDF/A certification.",
        "Native removal attempts storage deletion for pending and verified uploads before deleting metadata. Storage cleanup is not guaranteed after a reported failure.",
        "Native deletion does not revoke a previously issued presigned URL. Do not race an in-flight transfer with abort; a late PUT can recreate an orphaned object."
      ]
    }
  },
  "x-edoobox-upload-input-review": {
    "rawFilenameMaxLength": 150,
    "escapedFilenameMaxLength": 150,
    "source": {
      "file": "application/models/v2/Layoutfunc.php",
      "line": 1271,
      "sha256": "04d3a25db87fd8c8e5f6fd8b6ec9cb899bf3d0bafcc7f286b76381c9e28afdc1",
      "lineEnd": 1277
    }
  },
  "x-edoobox-upload-kind-review": {
    "requestPointer": "/body/data/type",
    "nativeEffectiveByteLimits": {
      "pdfattachment": 1500000,
      "pdftemplate": 1000000
    },
    "minimumBytes": 21,
    "ticketCapMeaning": "Union cap; the request schema enforces the per-kind maximum before native metadata creation and the staged transfer must exactly equal that validated file_size. Runtime must choose the reviewed workflow variant from the unchanged validated request, with no URL/default fallback.",
    "sources": [
      {
        "file": "application/models/v2/Layout.php",
        "line": 500,
        "lineEnd": 520,
        "sha256": "d5bf4faf862da921710d9d2f553b14778a2b78eb8281a2f195dd5d52f9886eaf",
        "reason": "Both contextual URL branches call the same _addObject; body.data.type selects the actual stored kind."
      },
      {
        "file": "application/models/v2/Layoutfunc.php",
        "line": 13,
        "lineEnd": 17,
        "sha256": "04d3a25db87fd8c8e5f6fd8b6ec9cb899bf3d0bafcc7f286b76381c9e28afdc1",
        "reason": "Native size predicate requires >20 and includes the per-kind maximum: attachment1500000, template1000000."
      },
      {
        "file": "application/models/v2/Layoutfunc.php",
        "line": 1187,
        "lineEnd": 1207,
        "sha256": "04d3a25db87fd8c8e5f6fd8b6ec9cb899bf3d0bafcc7f286b76381c9e28afdc1",
        "reason": "Actual data.type allowlist and own parent selection before reservations."
      },
      {
        "file": "application/models/v2/Layoutfunc.php",
        "line": 1279,
        "lineEnd": 1336,
        "sha256": "04d3a25db87fd8c8e5f6fd8b6ec9cb899bf3d0bafcc7f286b76381c9e28afdc1",
        "reason": "Native integer-cast size validation and selected per-body-kind insert/public child response; valid cross-type URL payloads remain valid."
      }
    ]
  },
  "x-edoobox-runtimeMutationGuard": true,
  "x-edoobox-documentationReview": {
    "file": "docs/openapi/operation-contracts/07-layout-files.json",
    "notes": []
  },
  "x-edoobox-source": {
    "file": "application/models/v2/Layout.php",
    "method": "postLayout",
    "line": 496
  },
  "x-edoobox-documentationStatus": "reviewed",
  "x-edoobox-readOnly": false,
  "x-edoobox-safeForAutomation": false,
  "x-edoobox-permission": {
    "resource": "layout",
    "short": "lyot",
    "checkedByDispatcher": true,
    "levels": [
      2,
      3,
      4
    ],
    "description": "Resource permission mapping from APIPermissions(), Authfunc::_getCheckJWT. Additional model/admin/plugin checks may apply; resources absent from api_permission do not acquire a fictitious scope."
  }
}