{
  "openapi": "3.0.3",
  "info": {
    "title": "IBAN Validator & Parser API",
    "version": "1.0.0",
    "description": "ISO 13616 IBAN validation using the MOD-97 algorithm. Supports 40+ countries. Extracts bank code, account number, and formatted IBAN. Batch validation for up to 100 IBANs per request. No external dependencies — built on Node.js built-ins.\n",
    "contact": {
      "name": "Revenue Lab API Support",
      "email": "api@hiroapp.cc"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.sprytools.com/v1/iban",
      "description": "Production (SpryTools API Gateway)"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/api/v1/validate": {
      "get": {
        "operationId": "validateIBAN",
        "summary": "Validate a single IBAN",
        "description": "Validates an IBAN using the MOD-97 checksum algorithm (ISO 13616). Returns validity flag, country, check digits, and an error message when the IBAN is invalid.\n",
        "parameters": [
          {
            "name": "iban",
            "in": "query",
            "required": true,
            "description": "The IBAN to validate (spaces are stripped automatically).",
            "schema": {
              "type": "string",
              "example": "DE89370400440532013000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                },
                "example": {
                  "valid": true,
                  "iban": "DE89370400440532013000",
                  "country": "DE",
                  "countryName": "Germany",
                  "checkDigits": "89",
                  "length": 22
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/parse": {
      "get": {
        "operationId": "parseIBAN",
        "summary": "Parse an IBAN and extract components",
        "description": "Validates and fully parses an IBAN. Returns the BBAN, bank code, account number (country-specific decomposition), formatted IBAN with spaces for display, and full country information.\n",
        "parameters": [
          {
            "name": "iban",
            "in": "query",
            "required": true,
            "description": "The IBAN to parse (spaces are stripped automatically).",
            "schema": {
              "type": "string",
              "example": "DE89370400440532013000"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Parsed IBAN result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ParseResult"
                },
                "example": {
                  "valid": true,
                  "iban": "DE89370400440532013000",
                  "formattedIBAN": "DE89 3704 0044 0532 0130 00",
                  "country": "DE",
                  "countryName": "Germany",
                  "checkDigits": "89",
                  "bban": "370400440532013000",
                  "bankCode": "37040044",
                  "accountNumber": "0532013000",
                  "length": 22
                }
              }
            }
          },
          "400": {
            "description": "Missing or malformed query parameter",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/validate/batch": {
      "post": {
        "operationId": "validateBatch",
        "summary": "Validate up to 100 IBANs in a single request",
        "description": "Validates a list of IBANs (max 100) using the MOD-97 algorithm. Each result includes the original IBAN for easy mapping. Returns aggregate counts of valid and invalid IBANs.\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BatchRequest"
              },
              "example": {
                "ibans": [
                  "DE89370400440532013000",
                  "GB29NWBK60161331926819",
                  "INVALID123"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch validation results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BatchResult"
                },
                "example": {
                  "results": [
                    {
                      "iban": "DE89370400440532013000",
                      "valid": true,
                      "country": "DE"
                    },
                    {
                      "iban": "GB29NWBK60161331926819",
                      "valid": true,
                      "country": "GB"
                    },
                    {
                      "iban": "INVALID123",
                      "valid": false,
                      "error": "Invalid IBAN format"
                    }
                  ],
                  "total": 3,
                  "validCount": 2,
                  "invalidCount": 1
                }
              }
            }
          },
          "400": {
            "description": "Missing body or ibans array, or array exceeds 100 items",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/countries": {
      "get": {
        "operationId": "listCountries",
        "summary": "List all supported countries",
        "description": "Returns all countries supported by this API, including the ISO 3166-1 alpha-2 country code, country name, and the expected IBAN length for that country.\n",
        "responses": {
          "200": {
            "description": "List of supported countries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "countries": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CountryInfo"
                      }
                    },
                    "total": {
                      "type": "integer",
                      "example": 44
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Health check",
        "description": "Returns service health status. No authentication required.",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "service": {
                      "type": "string",
                      "example": "iban-api"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-RapidAPI-Key"
      }
    },
    "schemas": {
      "ValidationResult": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean",
            "description": "Whether the IBAN passed MOD-97 validation."
          },
          "iban": {
            "type": "string",
            "description": "The IBAN as provided (spaces stripped)."
          },
          "country": {
            "type": "string",
            "description": "ISO 3166-1 alpha-2 country code.",
            "example": "DE"
          },
          "countryName": {
            "type": "string",
            "description": "Full country name.",
            "example": "Germany"
          },
          "checkDigits": {
            "type": "string",
            "description": "The two check digits of the IBAN.",
            "example": "89"
          },
          "length": {
            "type": "integer",
            "description": "Length of the IBAN.",
            "example": 22
          },
          "error": {
            "type": "string",
            "description": "Error message when valid is false."
          }
        },
        "required": [
          "valid"
        ]
      },
      "ParseResult": {
        "type": "object",
        "properties": {
          "valid": {
            "type": "boolean"
          },
          "iban": {
            "type": "string",
            "description": "The IBAN (spaces stripped)."
          },
          "formattedIBAN": {
            "type": "string",
            "description": "IBAN formatted in groups of 4 characters for display.",
            "example": "DE89 3704 0044 0532 0130 00"
          },
          "country": {
            "type": "string",
            "example": "DE"
          },
          "countryName": {
            "type": "string",
            "example": "Germany"
          },
          "checkDigits": {
            "type": "string",
            "example": "89"
          },
          "bban": {
            "type": "string",
            "description": "Basic Bank Account Number (national part).",
            "example": "370400440532013000"
          },
          "bankCode": {
            "type": "string",
            "description": "Bank identifier extracted from BBAN (country-specific).",
            "example": "37040044"
          },
          "accountNumber": {
            "type": "string",
            "description": "Account number extracted from BBAN (country-specific).",
            "example": "0532013000"
          },
          "length": {
            "type": "integer",
            "example": 22
          },
          "error": {
            "type": "string",
            "description": "Error message when valid is false."
          }
        },
        "required": [
          "valid"
        ]
      },
      "BatchRequest": {
        "type": "object",
        "required": [
          "ibans"
        ],
        "properties": {
          "ibans": {
            "type": "array",
            "description": "Array of IBANs to validate. Maximum 100 items.",
            "maxItems": 100,
            "items": {
              "type": "string"
            },
            "example": [
              "DE89370400440532013000",
              "GB29NWBK60161331926819"
            ]
          }
        }
      },
      "BatchResultItem": {
        "type": "object",
        "properties": {
          "iban": {
            "type": "string"
          },
          "valid": {
            "type": "boolean"
          },
          "country": {
            "type": "string"
          },
          "error": {
            "type": "string"
          }
        },
        "required": [
          "iban",
          "valid"
        ]
      },
      "BatchResult": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/BatchResultItem"
            }
          },
          "total": {
            "type": "integer"
          },
          "validCount": {
            "type": "integer"
          },
          "invalidCount": {
            "type": "integer"
          }
        }
      },
      "CountryInfo": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "example": "DE"
          },
          "name": {
            "type": "string",
            "example": "Germany"
          },
          "ibanLength": {
            "type": "integer",
            "example": 22
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message."
          }
        },
        "required": [
          "error"
        ]
      }
    }
  }
}