# POST /v2/layout/post/pdftemplate/add_object

PDF-Hintergrundvorlage für einen PDF-Upload reservieren

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.

- Operation-ID: post_v2_layout_post_pdftemplate_add_object
- Dokumentation: /docs/api/v2/operations/post-v2-layout-post-pdftemplate-add-object-99afbd84f107/
- OpenAPI-Version: 3.2.1
- Vollständige Spezifikation: /docs/api/v2/openapi.json
- Dokumentationsstatus: reviewed
- Ändert Zustand: ja
- Für Automation freigegeben: nein

## Server

Serverwerte stammen unverändert aus der Datei. Eine lokale Entwicklungsadresse ist keine bestätigte Produktionsadresse. `API_ORIGIN` muss auf die passende Instanz gesetzt werden.

```json
[
  {
    "url": "https://app2.edoobox.com",
    "description": "edoobox API"
  }
]
```

## Authentifizierung

Eine der folgenden Alternativen genügt (ODER). Innerhalb einer Alternative müssen alle Verfahren gemeinsam erfüllt sein (UND).

1. **bearerAuth** (HTTP bearer) — Existing edoobox v2 access token. Never substitute API key/secret headers. **UND** **accountContext** (header: edid) — Selected login/account context from the JWT, not a database primary key. Required even for a JWT with one account.
2. **sessionCookie** (cookie: _edlogin) — Existing browser login session, with the same permission checks as Bearer authentication. **UND** **accountContext** (header: edid) — Selected login/account context from the JWT, not a database primary key. Required even for a JWT with one account.

### Wirksame Security Requirements und vollständige Verfahren

```json
{
  "security": [
    {
      "bearerAuth": [],
      "accountContext": []
    },
    {
      "sessionCookie": [],
      "accountContext": []
    }
  ],
  "securitySchemes": {
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT",
      "description": "Existing edoobox v2 access token. Never substitute API key/secret headers."
    },
    "accountContext": {
      "type": "apiKey",
      "in": "header",
      "name": "edid",
      "description": "Selected login/account context from the JWT, not a database primary key. Required even for a JWT with one account."
    },
    "sessionCookie": {
      "type": "apiKey",
      "in": "cookie",
      "name": "_edlogin",
      "description": "Existing browser login session, with the same permission checks as Bearer authentication."
    }
  }
}
```

## Parameter

| Name | Ort | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| X-Edoobox-If-Revision | header | nein | 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. |

### Vollständige wirksame Parameterdefinitionen

```json
[
  {
    "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."
  }
]
```

## Anfrage

```json
{
  "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-Hintergrundvorlage für einen PDF-Upload reservieren",
          "value": {
            "data": {
              "layoutpdf": "layoutpdf_012345abcdef_123456",
              "type": "pdftemplate",
              "file_name": "Unterlage.pdf",
              "file_type": "application/pdf",
              "file_size": 1024
            }
          }
        }
      }
    }
  }
}
```

## Antworten

HTTP-Status und Antwortinhalt gemeinsam auswerten. Die folgenden Beschreibungen und Schemata sind die Angaben der Quelldatei.

```json
{
  "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": "layoutpdftemplate_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"
        }
      }
    }
  }
}
```

## Aufrufbeispiele

Anpassen vor dem Ausführen. Platzhalter und veröffentlichte Beispiele sind synthetisch. Die Beispiele senden hier keine Anfrage; sie ergänzen keine unbekannten Pflichtfelder.

### cURL

```sh
# Zeigt Authentifizierungsalternative 1; alle Verfahren dieser Alternative sind gemeinsam erforderlich.
# Request Body: synthetisches Beispiel aus der Spezifikation; Werte und Vollständigkeit vor Verwendung prüfen.
: "${API_ORIGIN:?API_ORIGIN setzen}"
: "${AUTH_BEARERAUTH:?AUTH_BEARERAUTH setzen}"
: "${AUTH_ACCOUNTCONTEXT:?AUTH_ACCOUNTCONTEXT setzen}"
cat > payload.json <<'EDOOBOX_JSON_EXAMPLE'
{
  "data": {
    "layoutpdf": "layoutpdf_012345abcdef_123456",
    "type": "pdftemplate",
    "file_name": "Unterlage.pdf",
    "file_type": "application/pdf",
    "file_size": 1024
  }
}
EDOOBOX_JSON_EXAMPLE
curl --request 'POST' \
  --url "${API_ORIGIN%/}"'/v2/layout/post/pdftemplate/add_object' \
  --header 'Authorization: Bearer '"${AUTH_BEARERAUTH}" \
  --header 'edid: '"${AUTH_ACCOUNTCONTEXT}" \
  --header 'Content-Type: application/json' \
  --data-binary '@payload.json'
```

### JavaScript (Node.js)

```javascript
// Zeigt Authentifizierungsalternative 1; alle Verfahren dieser Alternative sind gemeinsam erforderlich.
// Request Body: synthetisches Beispiel aus der Spezifikation; Werte und Vollständigkeit vor Verwendung prüfen.
const required = (name) => {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
};
let path = "/v2/layout/post/pdftemplate/add_object";
const origin = required('API_ORIGIN');
const url = new URL((origin.endsWith('/') ? origin.slice(0, -1) : origin) + path);
const headers = {};
headers["Authorization"] = "Bearer " + required("AUTH_BEARERAUTH");
headers["edid"] = "" + required("AUTH_ACCOUNTCONTEXT");
headers['Content-Type'] = "application/json";
const body = JSON.stringify({
  "data": {
    "layoutpdf": "layoutpdf_012345abcdef_123456",
    "type": "pdftemplate",
    "file_name": "Unterlage.pdf",
    "file_type": "application/pdf",
    "file_size": 1024
  }
});
const response = await fetch(url, { method: "POST", headers, body, redirect: 'manual' });
const text = await response.text();
console.log(response.status, text);
// HTTP-Status und dokumentierte error/success-Felder gemeinsam prüfen.
```

### Python

```python
# Zeigt Authentifizierungsalternative 1; alle Verfahren dieser Alternative sind gemeinsam erforderlich.
# Request Body: synthetisches Beispiel aus der Spezifikation; Werte und Vollständigkeit vor Verwendung prüfen.
import os
import urllib.parse
import urllib.request
import urllib.error

path = "/v2/layout/post/pdftemplate/add_object"
url = os.environ["API_ORIGIN"].rstrip("/") + path
headers = {}
headers["Authorization"] = "Bearer " + os.environ["AUTH_BEARERAUTH"]
headers["edid"] = "" + os.environ["AUTH_ACCOUNTCONTEXT"]
headers["Content-Type"] = "application/json"
body = "{\"data\":{\"layoutpdf\":\"layoutpdf_012345abcdef_123456\",\"type\":\"pdftemplate\",\"file_name\":\"Unterlage.pdf\",\"file_type\":\"application/pdf\",\"file_size\":1024}}".encode("utf-8")

# Redirects nicht automatisch verfolgen.
class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None
request = urllib.request.Request(url, headers=headers, method="POST", data=body)
try:
    response = urllib.request.build_opener(NoRedirect).open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error
print(response.status, response.read().decode("utf-8", errors="replace"))
# HTTP-Status und dokumentierte error/success-Felder gemeinsam prüfen.
```

## Vollständige Operationsdefinition und edoobox-Hinweise

Alle Originalfelder einschliesslich `x-edoobox-*`, requestBody und responses bleiben erhalten. Teilweise dokumentierte Schemata sind kein vollständiger Validierungsvertrag.

```json
{
  "operationId": "post_v2_layout_post_pdftemplate_add_object",
  "summary": "PDF-Hintergrundvorlage 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": "layoutpdftemplate_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-Hintergrundvorlage für einen PDF-Upload reservieren",
            "value": {
              "data": {
                "layoutpdf": "layoutpdf_012345abcdef_123456",
                "type": "pdftemplate",
                "file_name": "Unterlage.pdf",
                "file_type": "application/pdf",
                "file_size": 1024
              }
            }
          }
        }
      }
    }
  },
  "x-edoobox-routeAliasEvidence": {
    "file": "application/models/v2/Layout.php",
    "line": 517,
    "reason": "postLayout selects the literal segment4 pdftemplate branch and delegates to Layoutfunc::_addObject; this source-backed Vue URL supplies post/add_object as contextual segments.",
    "sha256": "d5bf4faf862da921710d9d2f553b14778a2b78eb8281a2f195dd5d52f9886eaf",
    "method": "postLayout"
  },
  "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_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."
      ]
    }
  },
  "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."
  }
}
```