{
    "openapi": "3.1.1",
    "info": {
        "title": "onlinehandtekening.nl API",
        "version": "1.0.0",
        "description": "Een API-sleutel uit Dashboard → Integraties en een actief Onbeperkt-pakket zijn vereist. Maximaal 60 aanvragen per minuut per sleutel. Alle POST/PATCH-aanvragen vereisen een Idempotency-Key. JSON-datums zonder zone zijn Europe/Amsterdam. Gebruik HTTPS in productie."
    },
    "servers": [
        {
            "url": "http://localhost:8888/api/v1"
        }
    ],
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/documents": {
            "get": {
                "summary": "Documenten in deze werkruimte",
                "description": "Vereist recht: documents:read.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100,
                            "default": 25
                        }
                    },
                    {
                        "name": "before",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "draft",
                                "ready",
                                "sent",
                                "viewed",
                                "signed"
                            ]
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Document"
                                            }
                                        },
                                        "next_before": {
                                            "type": [
                                                "integer",
                                                "null"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "summary": "PDF uploaden als concept",
                "description": "Vereist recht: documents:write.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "Uniek per logische wijziging; herhaal exact dezelfde aanvraag met dezelfde sleutel bij een timeout. Hergebruik voor een andere aanvraag geeft 409.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_:\\-]{8,100}$"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Document"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "title",
                                    "document"
                                ],
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 180
                                    },
                                    "document": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "PDF: maximaal 10 MB en 50 pagina’s. Geen wachtwoordbeveiliging."
                                    },
                                    "recipient_name": {
                                        "type": "string",
                                        "maxLength": 180
                                    },
                                    "recipient_email": {
                                        "type": "string",
                                        "format": "email"
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "get": {
                "summary": "Document, velden en ondertekenstatus",
                "description": "Vereist recht: documents:read.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Document"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}/layout": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "patch": {
                "summary": "Volledige veldindeling en ontvangers vervangen",
                "description": "Vereist recht: documents:write.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "Uniek per logische wijziging; herhaal exact dezelfde aanvraag met dezelfde sleutel bij een timeout. Hergebruik voor een andere aanvraag geeft 409.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_:\\-]{8,100}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Document"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/Layout"
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}/send": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "post": {
                "summary": "Concept vastzetten en uitnodigingen in de verzendwachtrij plaatsen",
                "description": "Vereist recht: documents:send.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "Uniek per logische wijziging; herhaal exact dezelfde aanvraag met dezelfde sleutel bij een timeout. Hergebruik voor een andere aanvraag geeft 409.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_:\\-]{8,100}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Document"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "revision"
                                ],
                                "properties": {
                                    "revision": {
                                        "type": "integer",
                                        "minimum": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}/reminders": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "patch": {
                "summary": "Herinneringsschema voor een document instellen",
                "description": "Vereist recht: documents:send.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "Uniek per logische wijziging; herhaal exact dezelfde aanvraag met dezelfde sleutel bij een timeout. Hergebruik voor een andere aanvraag geeft 409.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_:\\-]{8,100}$"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/ReminderOptions"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/ReminderOptions"
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}/events": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "get": {
                "summary": "Laatste 100 documentgebeurtenissen, nieuwste eerst",
                "description": "Vereist recht: documents:read.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "id": {
                                                        "type": "integer"
                                                    },
                                                    "event_type": {
                                                        "type": "string"
                                                    },
                                                    "created_at": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/documents/{id}/file": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "get": {
                "summary": "PDF downloaden",
                "description": "Recht documents:read. signed is pas beschikbaar wanneer iedereen heeft ondertekend.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "variant",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "original",
                                "prepared",
                                "signed"
                            ],
                            "default": "prepared"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "PDF-bestand",
                        "content": {
                            "application/pdf": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/templates": {
            "get": {
                "summary": "Actieve sjablonen en hun ontvangerrollen",
                "description": "Vereist recht: templates:read.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "#/components/schemas/Template"
                                            }
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/templates/{id}": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "get": {
                "summary": "Sjabloon met ontvangerrollen",
                "description": "Vereist recht: templates:read.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Template"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/templates/{id}/documents": {
            "parameters": [
                {
                    "name": "id",
                    "in": "path",
                    "required": true,
                    "schema": {
                        "type": "integer",
                        "minimum": 1
                    }
                }
            ],
            "post": {
                "summary": "Nieuw concept uit een sjabloon maken",
                "description": "Vereist recht: templates:use.",
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "parameters": [
                    {
                        "name": "Idempotency-Key",
                        "in": "header",
                        "required": true,
                        "description": "Uniek per logische wijziging; herhaal exact dezelfde aanvraag met dezelfde sleutel bij een timeout. Hergebruik voor een andere aanvraag geeft 409.",
                        "schema": {
                            "type": "string",
                            "pattern": "^[A-Za-z0-9_:\\-]{8,100}$"
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Geslaagd",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "$ref": "#/components/schemas/Document"
                                        }
                                    },
                                    "required": [
                                        "data"
                                    ]
                                }
                            }
                        }
                    },
                    "default": {
                        "description": "De aanvraag is geweigerd. Bij 409: controleer revision of Idempotency-Key. Bij 429: volg Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                },
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": [
                                    "recipients"
                                ],
                                "properties": {
                                    "title": {
                                        "type": "string",
                                        "maxLength": 180
                                    },
                                    "recipients": {
                                        "type": "object",
                                        "description": "Een object met voor iedere key uit template.roles een nieuwe naam en e-mailadres.",
                                        "additionalProperties": {
                                            "type": "object",
                                            "required": [
                                                "name",
                                                "email"
                                            ],
                                            "properties": {
                                                "name": {
                                                    "type": "string",
                                                    "maxLength": 180
                                                },
                                                "email": {
                                                    "type": "string",
                                                    "format": "email"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "oh_live_…"
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "integer"
                            },
                            "message": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "code",
                            "message"
                        ]
                    }
                },
                "required": [
                    "error"
                ]
            },
            "Recipient": {
                "type": "object",
                "required": [
                    "key",
                    "name",
                    "email"
                ],
                "properties": {
                    "key": {
                        "type": "string",
                        "pattern": "^r-[a-zA-Z0-9-]{8,36}$"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 180
                    },
                    "email": {
                        "type": "string",
                        "format": "email"
                    },
                    "status": {
                        "type": "string",
                        "readOnly": true
                    },
                    "signed_at": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "readOnly": true
                    }
                }
            },
            "Field": {
                "type": "object",
                "required": [
                    "id",
                    "type",
                    "role",
                    "page",
                    "x",
                    "y",
                    "w",
                    "h",
                    "label"
                ],
                "properties": {
                    "id": {
                        "type": "string",
                        "pattern": "^f-[a-zA-Z0-9-]{8,36}$"
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "text",
                            "name",
                            "date",
                            "checkbox",
                            "signature"
                        ]
                    },
                    "role": {
                        "type": "string",
                        "enum": [
                            "sender",
                            "signer"
                        ]
                    },
                    "recipientKey": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Verplicht voor signer; moet verwijzen naar een ontvanger in dezelfde indeling."
                    },
                    "page": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "x": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                    },
                    "y": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 1
                    },
                    "w": {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 1
                    },
                    "h": {
                        "type": "number",
                        "exclusiveMinimum": 0,
                        "maximum": 1
                    },
                    "label": {
                        "type": "string",
                        "maxLength": 80
                    },
                    "required": {
                        "type": "boolean",
                        "default": false
                    },
                    "fontSize": {
                        "type": "integer",
                        "minimum": 8,
                        "maximum": 28,
                        "default": 12
                    },
                    "value": {
                        "type": "string",
                        "maxLength": 1500,
                        "description": "Alleen voor sender-tekst. Waarden van ondertekenaars worden niet via de API ingevuld."
                    }
                }
            },
            "Layout": {
                "type": "object",
                "required": [
                    "revision",
                    "recipients",
                    "fields"
                ],
                "properties": {
                    "revision": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "recipients": {
                        "type": "array",
                        "maxItems": 10,
                        "items": {
                            "$ref": "#/components/schemas/Recipient"
                        }
                    },
                    "fields": {
                        "type": "array",
                        "maxItems": 100,
                        "items": {
                            "$ref": "#/components/schemas/Field"
                        }
                    }
                }
            },
            "ReminderOptions": {
                "type": "object",
                "required": [
                    "enabled",
                    "interval_days",
                    "max"
                ],
                "properties": {
                    "enabled": {
                        "type": "boolean"
                    },
                    "interval_days": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 14
                    },
                    "max": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 5
                    }
                }
            },
            "Document": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "title": {
                        "type": "string"
                    },
                    "filename": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string",
                        "enum": [
                            "draft",
                            "ready",
                            "sent",
                            "viewed",
                            "signed"
                        ]
                    },
                    "revision": {
                        "type": "integer"
                    },
                    "created_at": {
                        "type": "string"
                    },
                    "pages": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "width": {
                                    "type": "number"
                                },
                                "height": {
                                    "type": "number"
                                }
                            }
                        }
                    },
                    "fields": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Field"
                        }
                    },
                    "recipients": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/Recipient"
                        }
                    },
                    "file": {
                        "type": "string",
                        "description": "Relatieve URL; vereist dezelfde Bearer-authenticatie."
                    },
                    "proof_code": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                }
            },
            "Template": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "name": {
                        "type": "string"
                    },
                    "description": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "revision": {
                        "type": "integer"
                    },
                    "pages": {
                        "type": "integer"
                    },
                    "archived": {
                        "type": "boolean"
                    },
                    "roles": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}