{
  "openapi": "3.0.3",
  "info": {
    "title": "Fliinow Partner API — read-only integration reference",
    "version": "1.8.0",
    "description": "Documented read-only subset of the Fliinow Partner API: health and indicative financing simulation. Transcribed from the official API reference; not the complete partner API contract. Consult the official documentation for operation creation, cancellation, refunds and current response structures.",
    "contact": { "name": "Fliinow", "url": "https://api.docs.fliinow.com/support" }
  },
  "externalDocs": { "description": "Authoritative Fliinow Partner API reference", "url": "https://api.docs.fliinow.com/api-reference" },
  "servers": [
    { "url": "https://demo.fliinow.com/integration-api/v1", "description": "Sandbox — partner test credentials required" },
    { "url": "https://app.fliinow.com/integration-api/v1", "description": "Production — partner live credentials required" }
  ],
  "security": [{ "PartnerApiKey": [] }],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getApiHealth",
        "summary": "Check Fliinow API health",
        "description": "Authenticated connectivity check. Returns health status, version, timestamp and partner code, according to the official API reference.",
        "parameters": [{ "$ref": "#/components/parameters/ManagementGroupAgency" }],
        "responses": {
          "200": { "description": "API responding correctly", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "partnerCode": { "type": "string" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/DataIntegrityError" },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    },
    "/financing/simulate/{totalPrice}": {
      "get": {
        "operationId": "simulatePartnerFinancing",
        "summary": "Retrieve indicative financing offers",
        "description": "Read-only simulation without creating an operation. Amount must be greater than zero. Optional countryCode selects the customer market; omission quotes Spain. Offers are indicative. Actual availability and terms depend on the partner's configured markets and financing approval.",
        "parameters": [
          { "name": "totalPrice", "in": "path", "required": true, "description": "Positive amount to simulate, as documented by the Partner API. Standard advertised EUR product range is 60–5,000.", "schema": { "type": "number", "minimum": 0, "exclusiveMinimum": true } },
          { "name": "countryCode", "in": "query", "description": "Customer residence country, ISO 3166-1 alpha-3. Optional; defaults to Spain according to official documentation.", "schema": { "type": "string" } },
          { "$ref": "#/components/parameters/ManagementGroupAgency" }
        ],
        "responses": {
          "200": { "description": "Indicative offers for the requested amount. Consult the official reference for the full offer shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "financialOffers": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } },
          "400": { "description": "VALIDATION_ERROR: totalPrice must be greater than zero", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "description": "NO_FINANCIAL_COMPANIES_CONFIGURED when no financing options are configured for the partner agency, or DATA_INTEGRITY_ERROR for a data conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
          "500": { "$ref": "#/components/responses/InternalError" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerApiKey": { "type": "apiKey", "in": "header", "name": "X-Fliinow-API-Key", "description": "Partner-issued agency or management group key. Never expose private keys in client-side code or public agent tools." }
    },
    "parameters": {
      "ManagementGroupAgency": { "name": "X-Fliinow-Agency", "in": "header", "required": false, "description": "Required for management group API keys on these endpoints; omit for agency keys. Use an agency ID returned by the group's authenticated GET /agencies call.", "schema": { "type": "string" } }
    },
    "schemas": {
      "ApiError": { "type": "object", "properties": { "errorCode": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }
    },
    "responses": {
      "Unauthorized": { "description": "Missing or invalid API key. Authentication errors use error_description rather than errorCode.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error_description": { "type": "string" } }, "additionalProperties": true } } } },
      "DataIntegrityError": { "description": "DATA_INTEGRITY_ERROR: conflict with existing data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "InternalError": { "description": "INTERNAL_ERROR: unexpected internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    }
  }
}