{
  "openapi": "3.1.0",
  "info": {
    "title": "UAB Testas apskaita API",
    "version": "1.0.0",
    "description": "Pardavimo sąskaitų faktūrų API. Demonstracinė sistema per48h integracijos bandymams: duomenys netikri. Visos užklausos /api/* reikalauja antraštės `X-Api-Key: <API raktas>`. `external_id` yra unikalus: jį naudokite kaip jūsų sistemos įrašo ID, kad pakartota užklausa nesukurtų antros sąskaitos."
  },
  "servers": [{ "url": "https://p48demo-apskaita.per48h.lt" }],
  "security": [{ "apiKey": [] }],
  "paths": {
    "/api/invoices": {
      "post": {
        "operationId": "createInvoice",
        "summary": "Išrašyti sąskaitą faktūrą",
        "description": "Sukuria sąskaitą ir suteikia jai serijos numerį. Jei sąskaita su tokiu `external_id` jau yra, nieko nesukuria ir grąžina `409` su esama sąskaita lauke `invoice`.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewInvoice" } } }
        },
        "responses": {
          "201": {
            "description": "Sukurta sąskaita",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "409": {
            "description": "Sąskaita su šiuo `external_id` jau yra",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["error", "message", "invoice"],
                  "properties": {
                    "error": { "type": "string", "const": "duplicate_external_id" },
                    "message": { "type": "string" },
                    "invoice": { "$ref": "#/components/schemas/Invoice" }
                  }
                }
              }
            }
          },
          "422": { "$ref": "#/components/responses/Error" }
        }
      },
      "get": {
        "operationId": "listInvoices",
        "summary": "Sąskaitų paieška",
        "description": "Su `external_id`: sąrašas su ta sąskaita arba tuščias sąrašas. Be jo: naujausios sąskaitos.",
        "parameters": [
          { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Sąskaitos, nuo naujausios",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["invoices"],
                  "properties": { "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } } }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/invoices/{id}": {
      "get": {
        "operationId": "getInvoice",
        "summary": "Viena sąskaita",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }],
        "responses": {
          "200": {
            "description": "Sąskaita",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }
          },
          "401": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "API raktas, kurį išduoda apskaitos administratorius." }
    },
    "schemas": {
      "Buyer": {
        "type": "object",
        "required": ["name", "email"],
        "properties": {
          "name": { "type": "string", "maxLength": 200, "description": "Pirkėjo pavadinimas arba vardas, pavardė" },
          "email": { "type": "string", "format": "email" },
          "code": { "type": ["string", "null"], "maxLength": 20, "description": "Įmonės kodas; privačiam asmeniui null arba nenurodoma" }
        }
      },
      "Line": {
        "type": "object",
        "required": ["description", "quantity", "price"],
        "properties": {
          "description": { "type": "string", "maxLength": 300 },
          "quantity": { "type": "number", "exclusiveMinimum": 0, "description": "Kiekis, iki 3 skaitmenų po kablelio" },
          "price": { "type": "number", "minimum": 0, "description": "Vieneto kaina su PVM, iki 2 skaitmenų po kablelio" }
        }
      },
      "NewInvoice": {
        "type": "object",
        "required": ["external_id", "buyer", "lines", "currency"],
        "properties": {
          "external_id": { "type": "string", "maxLength": 100, "description": "Unikalus jūsų sistemos įrašo ID" },
          "buyer": { "$ref": "#/components/schemas/Buyer" },
          "lines": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/Line" } },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" }
        }
      },
      "Invoice": {
        "type": "object",
        "required": ["id", "series_number", "external_id", "created_at", "buyer", "lines", "total", "currency"],
        "properties": {
          "id": { "type": "integer" },
          "series_number": { "type": "string", "example": "TST-000001" },
          "external_id": { "type": "string" },
          "created_at": { "type": "string", "format": "date-time" },
          "buyer": { "$ref": "#/components/schemas/Buyer" },
          "lines": { "type": "array", "items": { "$ref": "#/components/schemas/Line" } },
          "total": { "type": "number", "description": "Suma su PVM: eilučių quantity × price suma" },
          "currency": { "type": "string" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error", "message"],
        "properties": {
          "error": { "type": "string", "description": "Mašininis kodas: unauthorized, invalid_json, validation_failed, duplicate_external_id, not_found, ..." },
          "message": { "type": "string" },
          "details": { "type": "array", "items": { "type": "string" } }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Klaida",
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    }
  }
}