{
    "openapi": "3.1.0",
    "info": {
        "title": "Vembex API",
        "version": "1.0.0",
        "description": "Versioned API for Vembex compliance applications."
    },
    "servers": [
        {
            "url": "https://api.vembex.com/v1"
        }
    ],
    "externalDocs": {
        "description": "Vembex API Reference",
        "url": "https://developers.vembex.com/"
    },
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "paths": {
        "/": {
            "get": {
                "operationId": "getApiIndex",
                "summary": "Get API metadata",
                "security": [],
                "responses": {
                    "200": {
                        "description": "API metadata"
                    }
                }
            }
        },
        "/openapi.json": {
            "get": {
                "operationId": "getOpenApiDocument",
                "summary": "Get the OpenAPI document",
                "security": [],
                "responses": {
                    "200": {
                        "description": "OpenAPI 3.1 document"
                    }
                }
            }
        },
        "/vat-checks": {
            "post": {
                "tags": [
                    "VAT checks"
                ],
                "operationId": "createVatCheck",
                "summary": "Create a VAT-ID check",
                "description": "Creates an asynchronous check. Included plan units are consumed first; additional units are charged to the Compliance Budget before the run is created.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IdempotencyKey"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/VatCheckCreateRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "202": {
                        "description": "Check accepted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VatCheckResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/BadRequest"
                    },
                    "402": {
                        "$ref": "#/components/responses/PaymentRequired"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "409": {
                        "$ref": "#/components/responses/Conflict"
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "x-vembex-required-scope": "vatshaker.checks.create"
            }
        },
        "/vat-checks/{id}": {
            "get": {
                "tags": [
                    "VAT checks"
                ],
                "operationId": "getVatCheck",
                "summary": "Get a VAT-ID check",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Check",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/VatCheckResponse"
                                }
                            }
                        }
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "x-vembex-required-scope": "vatshaker.checks.read"
            }
        },
        "/vat-checks/{id}/results": {
            "get": {
                "tags": [
                    "VAT checks"
                ],
                "operationId": "listVatCheckResults",
                "summary": "List VAT-ID check results",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer",
                            "minimum": 1
                        }
                    },
                    {
                        "name": "cursor",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 0
                        }
                    },
                    {
                        "name": "per_page",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 250,
                            "default": 100
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Paginated results"
                    },
                    "403": {
                        "$ref": "#/components/responses/Forbidden"
                    },
                    "404": {
                        "$ref": "#/components/responses/NotFound"
                    }
                },
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "x-vembex-required-scope": "vatshaker.checks.read"
            }
        }
    },
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-API-Key",
                "description": "Company-bound Vembex API key with the required scope."
            }
        },
        "parameters": {
            "IdempotencyKey": {
                "name": "Idempotency-Key",
                "in": "header",
                "required": true,
                "description": "Unique key for one billable request. Reusing it with a different payload returns HTTP 409.",
                "schema": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 191,
                    "pattern": "^[A-Za-z0-9._:-]+$"
                }
            }
        },
        "responses": {
            "BadRequest": {
                "description": "Invalid request",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PaymentRequired": {
                "description": "Insufficient Compliance Budget",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Forbidden": {
                "description": "Missing scope or app access",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "NotFound": {
                "description": "Resource not found for this company",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "Conflict": {
                "description": "Idempotency or state conflict",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "ServiceUnavailable": {
                "description": "Service temporarily unavailable",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "schemas": {
            "Error": {
                "type": "object",
                "required": [
                    "code",
                    "message"
                ],
                "properties": {
                    "code": {
                        "type": "string"
                    },
                    "message": {
                        "type": "string"
                    },
                    "data": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "additionalProperties": true
                    }
                }
            },
            "VatCheckCreateRequest": {
                "type": "object",
                "required": [
                    "own_vat_id",
                    "items"
                ],
                "properties": {
                    "own_vat_id": {
                        "type": "string",
                        "description": "Verified company VAT ID used as requester."
                    },
                    "organization_unit_id": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "items": {
                        "type": "array",
                        "minItems": 1,
                        "maxItems": 10000,
                        "items": {
                            "$ref": "#/components/schemas/VatCheckItem"
                        }
                    }
                },
                "additionalProperties": false
            },
            "VatCheckItem": {
                "type": "object",
                "required": [
                    "vat_id"
                ],
                "properties": {
                    "vat_id": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "company_name": {
                        "type": "string",
                        "maxLength": 1000
                    },
                    "postal_code": {
                        "type": "string",
                        "maxLength": 1000
                    },
                    "city": {
                        "type": "string",
                        "maxLength": 1000
                    },
                    "street": {
                        "type": "string",
                        "maxLength": 1000
                    },
                    "reference": {
                        "type": "string",
                        "maxLength": 100
                    }
                },
                "additionalProperties": false
            },
            "VatCheckResponse": {
                "type": "object",
                "required": [
                    "data"
                ],
                "properties": {
                    "data": {
                        "type": "object",
                        "required": [
                            "id",
                            "status",
                            "totals",
                            "billing"
                        ],
                        "properties": {
                            "id": {
                                "type": "integer"
                            },
                            "status": {
                                "type": "string",
                                "enum": [
                                    "waiting",
                                    "preprocessing",
                                    "running",
                                    "success",
                                    "error"
                                ]
                            },
                            "created_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "completed_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "expires_at": {
                                "type": [
                                    "string",
                                    "null"
                                ],
                                "format": "date-time"
                            },
                            "totals": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "integer"
                                }
                            },
                            "billing": {
                                "type": "object",
                                "additionalProperties": true
                            }
                        }
                    },
                    "meta": {
                        "type": "object",
                        "additionalProperties": true
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "VAT checks",
            "description": "Asynchronous VAT-ID checks with tenant-scoped results."
        }
    ]
}