{
  "openapi": "3.0.3",
  "info": {
    "title": "Beste Boekhouding API - Boekhoudprogramma Vergelijking voor ZZP",
    "version": "1.0.0",
    "description": "Onafhankelijk AI-onderzoek naar boekhoudprogramma's voor ZZP-ers en ondernemers in Nederland. Vergelijk Jortt, Moneybird, Tellow, MoneyMonk, Snelstart en e-Boekhouden op basis van functies, prijzen en gebruikerservaringen.",
    "contact": {
      "name": "Beste Boekhouding",
      "url": "https://www.besteboekhouding.nl"
    },
    "license": {
      "name": "CC BY-NC 4.0",
      "url": "https://creativecommons.org/licenses/by-nc/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://www.besteboekhouding.nl",
      "description": "Production server"
    }
  ],
  "externalDocs": {
    "description": "Volledige vergelijking op de website",
    "url": "https://www.besteboekhouding.nl"
  },
  "tags": [
    {
      "name": "boekhoudprogrammas",
      "description": "Vergelijking van boekhoudprogramma's voor ZZP en ondernemers"
    },
    {
      "name": "rankings",
      "description": "Rankings en aanbevelingen"
    },
    {
      "name": "reviews",
      "description": "Gebruikersreviews en ervaringen"
    }
  ],
  "paths": {
    "/api/boekhoudprogrammas": {
      "get": {
        "tags": ["boekhoudprogrammas"],
        "summary": "Lijst alle boekhoudprogramma's",
        "description": "Retourneert een complete lijst van alle onderzochte boekhoudprogramma's met prijzen, functies en ratings",
        "operationId": "getBoekhoudprogrammas",
        "responses": {
          "200": {
            "description": "Succesvolle response met alle boekhoudprogramma's",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Boekhoudprogramma"
                      }
                    },
                    "metadata": {
                      "$ref": "#/components/schemas/Metadata"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/boekhoudprogrammas/{slug}": {
      "get": {
        "tags": ["boekhoudprogrammas"],
        "summary": "Haal specifiek boekhoudprogramma op",
        "description": "Retourneert gedetailleerde informatie over een specifiek boekhoudprogramma",
        "operationId": "getBoekhoudprogrammaBySlug",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["jortt", "moneybird", "tellow", "moneymonk", "snelstart", "e-boekhouden"]
            },
            "description": "Slug van het boekhoudprogramma"
          }
        ],
        "responses": {
          "200": {
            "description": "Succesvolle response met boekhoudprogramma details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BoekhoudprogrammaDetail"
                }
              }
            }
          }
        }
      }
    },
    "/api/rankings/zzp": {
      "get": {
        "tags": ["rankings"],
        "summary": "Top ranking voor ZZP-ers",
        "description": "Retourneert de top 6 ranking van boekhoudprogramma's specifiek voor ZZP-ers",
        "operationId": "getZZPRanking",
        "responses": {
          "200": {
            "description": "Succesvolle response met ZZP ranking",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ranking"
                }
              }
            }
          }
        }
      }
    },
    "/api/rankings/holding-bv": {
      "get": {
        "tags": ["rankings"],
        "summary": "Top ranking voor Holding BV",
        "description": "Retourneert de ranking van boekhoudprogramma's specifiek voor Holding BV's",
        "operationId": "getHoldingBVRanking",
        "responses": {
          "200": {
            "description": "Succesvolle response met Holding BV ranking",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Ranking"
                }
              }
            }
          }
        }
      }
    },
    "/api/comparison": {
      "get": {
        "tags": ["boekhoudprogrammas"],
        "summary": "Vergelijk boekhoudprogramma's",
        "description": "Vergelijk meerdere boekhoudprogramma's op basis van functies en prijzen",
        "operationId": "compareBoekhoudprogrammas",
        "parameters": [
          {
            "name": "programs",
            "in": "query",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "description": "Lijst van boekhoudprogramma slugs om te vergelijken (bijv. jortt,moneybird)"
          }
        ],
        "responses": {
          "200": {
            "description": "Succesvolle response met vergelijking",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Comparison"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Boekhoudprogramma": {
        "type": "object",
        "required": ["name", "slug", "rank", "price", "rating", "description"],
        "properties": {
          "name": {
            "type": "string",
            "description": "Naam van het boekhoudprogramma",
            "example": "Jortt"
          },
          "slug": {
            "type": "string",
            "description": "URL-vriendelijke slug",
            "example": "jortt"
          },
          "rank": {
            "type": "integer",
            "description": "Positie in de ranking (1 = beste)",
            "example": 1
          },
          "price": {
            "type": "number",
            "format": "float",
            "description": "Maandelijkse prijs in EUR (excl. BTW)",
            "example": 19.95
          },
          "specialOffer": {
            "$ref": "#/components/schemas/SpecialOffer"
          },
          "rating": {
            "type": "number",
            "format": "float",
            "description": "Overall rating (1-5)",
            "example": 5.0
          },
          "reviewCount": {
            "type": "integer",
            "description": "Aantal reviews",
            "example": 500
          },
          "description": {
            "type": "string",
            "description": "Korte beschrijving van het programma",
            "example": "Modern boekhoudprogramma voor ZZP met automatisering, smartphone app, urentool, fiscaal advies en mogelijkheid om zelf jaarrekening te maken"
          },
          "website": {
            "type": "string",
            "format": "uri",
            "description": "Officiële website URL",
            "example": "https://www.jortt.nl"
          },
          "isRecommended": {
            "type": "boolean",
            "description": "Of dit programma wordt aanbevolen",
            "example": true
          },
          "style": {
            "type": "string",
            "enum": ["modern", "traditional"],
            "description": "Design stijl van het programma",
            "example": "modern"
          },
          "features": {
            "$ref": "#/components/schemas/Features"
          }
        }
      },
      "BoekhoudprogrammaDetail": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Boekhoudprogramma"
          },
          {
            "type": "object",
            "properties": {
              "pros": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Voordelen van het programma",
                "example": [
                  "Moderne en gebruiksvriendelijke smartphone app",
                  "Volledige automatisering van boekhouding",
                  "Geïntegreerde urentool voor projecten"
                ]
              },
              "cons": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Nadelen van het programma",
                "example": [
                  "Iets hoger geprijsd dan basis alternatieven"
                ]
              },
              "reviews": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Review"
                },
                "description": "Gebruikersreviews"
              },
              "detailedFeatures": {
                "$ref": "#/components/schemas/DetailedFeatures"
              }
            }
          }
        ]
      },
      "SpecialOffer": {
        "type": "object",
        "description": "Speciale promotie of aanbieding",
        "properties": {
          "freeTrialDays": {
            "type": "integer",
            "description": "Aantal dagen gratis proefperiode",
            "example": 30
          },
          "discountedPrice": {
            "type": "number",
            "format": "float",
            "description": "Kortingsprijs in EUR",
            "example": 9.95
          },
          "discountedMonths": {
            "type": "integer",
            "description": "Aantal maanden met korting",
            "example": 3
          },
          "normalPrice": {
            "type": "number",
            "format": "float",
            "description": "Normale prijs daarna in EUR",
            "example": 19.95
          },
          "description": {
            "type": "string",
            "description": "Beschrijving van de aanbieding",
            "example": "30 dagen gratis, daarna 3 maanden voor €9,95, daarna €19,95 per maand"
          }
        }
      },
      "Features": {
        "type": "object",
        "description": "Belangrijkste functies van het programma",
        "properties": {
          "smartphoneApp": {
            "type": "boolean",
            "description": "Heeft volwaardige smartphone app",
            "example": true
          },
          "automation": {
            "type": "boolean",
            "description": "Volledige automatisering beschikbaar",
            "example": true
          },
          "urentool": {
            "type": "boolean",
            "description": "Geïntegreerde urenregistratie",
            "example": true
          },
          "fiscalAdvice": {
            "type": "boolean",
            "description": "Proactief fiscaal advies",
            "example": true
          },
          "selfJaarrekening": {
            "type": "boolean",
            "description": "Zelf jaarrekening kunnen maken",
            "example": true
          },
          "taxFiling": {
            "type": "boolean",
            "description": "Directe aangifte inkomstenbelasting",
            "example": true
          },
          "bankConnection": {
            "type": "boolean",
            "description": "Automatische bankkoppeling",
            "example": true
          },
          "receiptScanning": {
            "type": "boolean",
            "description": "Bonnetjes scannen",
            "example": true
          },
          "invoicing": {
            "type": "boolean",
            "description": "Facturatie module",
            "example": true
          },
          "vatReturn": {
            "type": "boolean",
            "description": "BTW-aangifte",
            "example": true
          }
        }
      },
      "DetailedFeatures": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Features"
          },
          {
            "type": "object",
            "properties": {
              "aiCategorization": {
                "type": "boolean",
                "description": "AI-gestuurde categorisering",
                "example": true
              },
              "projectManagement": {
                "type": "boolean",
                "description": "Projectmanagement functies",
                "example": true
              },
              "multipleCompanies": {
                "type": "boolean",
                "description": "Ondersteuning voor meerdere bedrijven",
                "example": true
              },
              "cloudBased": {
                "type": "boolean",
                "description": "Cloud-based platform",
                "example": true
              },
              "realtimeSync": {
                "type": "boolean",
                "description": "Real-time synchronisatie",
                "example": true
              }
            }
          }
        ]
      },
      "Review": {
        "type": "object",
        "description": "Gebruikersreview",
        "properties": {
          "reviewerName": {
            "type": "string",
            "description": "Naam van de reviewer",
            "example": "Sophie van der Berg"
          },
          "rating": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "description": "Rating gegeven door reviewer (1-5)",
            "example": 5
          },
          "reviewText": {
            "type": "string",
            "description": "Review tekst",
            "example": "Jortt heeft mijn administratie gestroomlijnd. De app is super handig en ik kan nu eindelijk overal mijn facturen maken."
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "Datum van de review",
            "example": "2025-01-26"
          },
          "verified": {
            "type": "boolean",
            "description": "Of de review geverifieerd is",
            "example": true
          },
          "trustpilotUrl": {
            "type": "string",
            "format": "uri",
            "description": "Link naar originele Trustpilot review",
            "example": "https://nl.trustpilot.com/reviews/698f4c4efebe0f3fd80dd902"
          }
        }
      },
      "Ranking": {
        "type": "object",
        "description": "Ranking van boekhoudprogramma's",
        "properties": {
          "category": {
            "type": "string",
            "enum": ["zzp", "holding-bv", "mkb"],
            "description": "Categorie van de ranking",
            "example": "zzp"
          },
          "lastUpdated": {
            "type": "string",
            "format": "date",
            "description": "Laatste update datum",
            "example": "2026-02-17"
          },
          "ranking": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Boekhoudprogramma"
            },
            "description": "Gesorteerde lijst van boekhoudprogramma's"
          },
          "methodology": {
            "$ref": "#/components/schemas/Methodology"
          }
        }
      },
      "Methodology": {
        "type": "object",
        "description": "Onderzoeksmethode en profiel",
        "properties": {
          "profile": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "description": "Type ondernemer",
                "example": "ZZP'er / Freelancer"
              },
              "yearsInBusiness": {
                "type": "integer",
                "description": "Aantal jaren in business",
                "example": 2
              },
              "annualRevenue": {
                "type": "number",
                "description": "Jaaromzet in EUR",
                "example": 50000
              }
            }
          },
          "criteria": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Criteria waarop beoordeeld wordt",
            "example": [
              "Moderne technologie en automatisering",
              "Smartphone app kwaliteit",
              "Fiscaal advies en jaarrekening ondersteuning",
              "Prijs-kwaliteit verhouding",
              "Gebruikerservaringen en reviews",
              "Specifieke ZZP-functies zoals urentool"
            ]
          }
        }
      },
      "Comparison": {
        "type": "object",
        "description": "Vergelijking tussen boekhoudprogramma's",
        "properties": {
          "programs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Boekhoudprogramma"
            },
            "description": "Programma's in de vergelijking"
          },
          "featureComparison": {
            "type": "object",
            "description": "Feature-per-feature vergelijking",
            "additionalProperties": {
              "type": "object",
              "additionalProperties": {
                "type": "boolean"
              }
            }
          },
          "priceComparison": {
            "type": "object",
            "description": "Prijsvergelijking",
            "additionalProperties": {
              "type": "number"
            }
          },
          "recommendation": {
            "type": "string",
            "description": "Aanbeveling op basis van vergelijking",
            "example": "jortt"
          }
        }
      },
      "Metadata": {
        "type": "object",
        "description": "Metadata over de dataset",
        "properties": {
          "lastUpdated": {
            "type": "string",
            "format": "date-time",
            "description": "Laatste update timestamp",
            "example": "2026-02-17T10:00:00Z"
          },
          "totalPrograms": {
            "type": "integer",
            "description": "Totaal aantal onderzochte programma's",
            "example": 6
          },
          "source": {
            "type": "string",
            "description": "Bron van de data",
            "example": "Beste Boekhouding - Onafhankelijk AI-onderzoek"
          },
          "methodology": {
            "type": "string",
            "description": "Onderzoeksmethode",
            "example": "AI-gestuurde analyse van functies, prijzen, gebruikerservaringen en marktposities"
          }
        }
      }
    }
  }
}