{
  "openapi": "3.1.0",
  "info": {
    "title": "Sudski Tumač Tuzla REST API",
    "version": "1.0.0",
    "description": "Zvanični REST API i specifikacija usluga stalnih sudskih tumača i prevodilaca za engleski i njemački jezik u Tuzli i Lukavcu.",
    "contact": {
      "name": "Stalni Sudski Tumači Tuzla",
      "url": "https://sudski-tumac-tuzla.com",
      "email": "info@sudski-tumac-tuzla.com"
    }
  },
  "x-api-version": "1.0.0",
  "x-deprecation-policy": "We maintain a minimum 12-month deprecation notice period before any backward-incompatible changes.",
  "servers": [
    {
      "url": "https://sudski-tumac-tuzla.com/v1",
      "description": "Production API v1"
    }
  ],
  "paths": {
    "/services": {
      "get": {
        "operationId": "getServicesList",
        "summary": "List translation and court interpretation services",
        "description": "Retrieve a paginated catalog of all official translation, court interpretation, and proofreading services.",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number for pagination",
            "schema": {
              "type": "integer",
              "default": 1,
              "minimum": 1
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Number of items to return per page",
            "schema": {
              "type": "integer",
              "default": 10,
              "minimum": 1,
              "maximum": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of translation services",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServicesListResponse"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/pricing": {
      "get": {
        "operationId": "getPricingTiers",
        "summary": "Get official translation pricing tiers and fee schedule",
        "description": "Retrieve the official fee schedule for certified court translations, norm-page calculation principles, and accepted currencies.",
        "responses": {
          "200": {
            "description": "Detailed pricing breakdown and fee tiers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PricingResponse"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/quote": {
      "post": {
        "operationId": "requestTranslationQuote",
        "summary": "Submit a document translation inquiry or quote request",
        "description": "Submit translation parameters to obtain an official quote from certified court interpreters. Asynchronous job created.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "description": "Unique UUID or token to ensure request idempotency and prevent duplicate quote submissions",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Client contact details and document parameters",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Quote inquiry accepted for asynchronous processing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid quote request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "operationId": "getJobStatus",
        "summary": "Check status of an asynchronous quote or translation request",
        "description": "Retrieve the current processing state of an async translation request by its unique Job ID.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "Unique identifier of the translation job or quote inquiry",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current status of the asynchronous job",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResponse"
                }
              }
            }
          },
          "404": {
            "description": "Job not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "default": {
            "description": "Unexpected error response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "example": "not_found"
              },
              "message": {
                "type": "string",
                "example": "The requested API endpoint was not found."
              },
              "status": {
                "type": "integer",
                "example": 404
              },
              "details": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "code",
              "message",
              "status"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "example": 1
          },
          "limit": {
            "type": "integer",
            "example": 10
          },
          "total": {
            "type": "integer",
            "example": 4
          },
          "totalPages": {
            "type": "integer",
            "example": 1
          },
          "hasMore": {
            "type": "boolean",
            "example": false
          }
        },
        "required": [
          "page",
          "limit",
          "total",
          "totalPages",
          "hasMore"
        ]
      },
      "ServiceItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ovjereni-prijevodi"
          },
          "title": {
            "type": "string",
            "example": "Ovjereni Prijevodi (Pečat Sudskih Tumača)"
          },
          "description": {
            "type": "string",
            "example": "Zvanični ovjereni prijevodi sa pečatom i izjavom sudskog tumača priznati u BiH i inostranstvu."
          },
          "pricingTier": {
            "type": "string",
            "example": "20–35 KM po norm-strani"
          },
          "certified": {
            "type": "boolean",
            "example": true
          }
        },
        "required": [
          "id",
          "title",
          "description",
          "certified"
        ]
      },
      "ServicesListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ServiceItem"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        },
        "required": [
          "data",
          "pagination"
        ]
      },
      "PricingTierItem": {
        "type": "object",
        "properties": {
          "tier": {
            "type": "string",
            "example": "Tier 1"
          },
          "category": {
            "type": "string",
            "example": "Standardni lični dokumenti"
          },
          "priceBAM": {
            "type": "string",
            "example": "20 - 25 KM"
          },
          "priceEUR": {
            "type": "string",
            "example": "10 - 13 EUR"
          },
          "unit": {
            "type": "string",
            "example": "po dokumentu"
          },
          "turnaround": {
            "type": "string",
            "example": "24h"
          }
        },
        "required": [
          "tier",
          "category",
          "priceBAM",
          "unit",
          "turnaround"
        ]
      },
      "PricingResponse": {
        "type": "object",
        "properties": {
          "normPageDefinition": {
            "type": "string",
            "example": "1.500 karaktera bez razmaka (ISO 17100)"
          },
          "currenciesAccepted": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "BAM",
              "EUR",
              "USD"
            ]
          },
          "tiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PricingTierItem"
            }
          }
        },
        "required": [
          "normPageDefinition",
          "currenciesAccepted",
          "tiers"
        ]
      },
      "QuoteRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Client full name",
            "example": "Amir Hadžić"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Client contact email",
            "example": "amir@example.com"
          },
          "phone": {
            "type": "string",
            "description": "Phone number or WhatsApp",
            "example": "+38761123456"
          },
          "sourceLanguage": {
            "type": "string",
            "enum": [
              "Bosnian",
              "Croatian",
              "Serbian",
              "English",
              "German"
            ],
            "example": "Bosnian"
          },
          "targetLanguage": {
            "type": "string",
            "enum": [
              "English",
              "German",
              "Bosnian"
            ],
            "example": "German"
          },
          "documentType": {
            "type": "string",
            "description": "Category or title of the document",
            "example": "Fakultetska diploma i dodatak diplomi"
          },
          "pageCount": {
            "type": "integer",
            "description": "Estimated number of pages",
            "example": 2,
            "default": 1
          },
          "isUrgent": {
            "type": "boolean",
            "description": "Requires delivery within 24h",
            "default": false
          },
          "notes": {
            "type": "string",
            "description": "Additional instructions or notes"
          }
        },
        "required": [
          "name",
          "email",
          "sourceLanguage",
          "targetLanguage",
          "documentType"
        ]
      },
      "JobResponse": {
        "type": "object",
        "properties": {
          "jobId": {
            "type": "string",
            "example": "job_tr_982341"
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "processing",
              "completed",
              "failed"
            ],
            "example": "pending"
          },
          "statusUrl": {
            "type": "string",
            "example": "https://sudski-tumac-tuzla.com/v1/jobs/job_tr_982341"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-10-06T00:00:00Z"
          },
          "estimatedCompletionTime": {
            "type": "string",
            "example": "Within 30 minutes"
          },
          "message": {
            "type": "string",
            "example": "Quote request received. An interpreter is reviewing your submission."
          }
        },
        "required": [
          "jobId",
          "status",
          "statusUrl",
          "createdAt"
        ]
      }
    }
  }
}