openapi: 3.0.2
info:
  title: Naamgeving API
  description: Naamgeving informatie opvragen van een specifiek bedrijf en/of vestiging
  termsOfService: https://www.kvk.nl/over-kvk/over-het-handelsregister/toegang-handelsregister/aanvraag-toegangscode/gebruiksvoorwaarden/
  contact:
    name: Kamer van Koophandel
    url: https://developers.kvk.nl/nl
  version: "1.1.1"
servers:
  - url: https://api.kvk.nl/test/api/v1
    description: Test API (uses Staat der Nederlanden Private Root CA – G1 certificate
      chain)
  - url: https://api.kvk.nl/api/v1
    description: Production API (uses Staat der Nederlanden Private Root CA – G1 certificate
      chain)
tags:
  - name: naamgeving
    externalDocs:
      description: 'Voor meer informatie over deze API'
      url: 'https://developers.kvk.nl/nl/support'
security:
  - ApiKeyAuth: [ ]
paths:
  /naamgevingen/kvknummer/{kvkNummer}:
    get:
      tags:
        - naamgeving
      summary: Voor een specifiek bedrijf naamgeving informatie opvragen op basis van een kvkNummer
      operationId: naamgevingBijKvkNummer
      parameters:
        - name: kvkNummer
          in: path
          description: '__Nederlands Kamer van Koophandel nummer__: bestaat uit 8 cijfers'
          example: "59581883"
          required: true
          schema:
            pattern: ^[0-9]{8}$
            type: string
      responses:
        '200':
          description: "Het verzoek levert een resultaat op.\
            \ Als geen resultaten worden gevonden die aan de path parameter\
            \ voldoen, wordt een 404 NotFound teruggegeven."
          headers:
            api-version:
              $ref: '#/components/headers/api_version'
            warning:
              $ref: '#/components/headers/warning'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Naamgeving'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Naamgeving'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '500':
          $ref: '#/components/responses/InternalServerError'
        default:
          description: Er is een onverwachte fout opgetreden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/hal+json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Naamgeving:
      type: object
      required:
        - kvkNummer
      properties:
        kvkNummer:
          description: Nederlands Kamer van Koophandel nummer
          example: "59581883"
          type: string
        rsin:
          description: |
            RSIN (Rechtspersonen en Samenwerkingsverbanden Informatienummer)

            Het RSIN kan voorloopnullen bevatten
          example: "823807071"
          type: string
          pattern: "^[0-9]{9}$"
        statutaireNaam:
          description: De naam van de rechtspersoon die opgenomen is in de oprichtingsakte
          type: string
          example: "Kamer van Koophandel"
        naam:
          description: Naam of eerste handelsnaam van de inschrijving
          type: string
          example: "Kamer van Koophandel"
        ookGenoemd:
          description: Een andere naam waaronder de vereniging, stichtingen en vereniging van eigenaars ook bekend is
          type: string
          example: "Kamer van Koophandel"
        startdatum:
          $ref: "#/components/schemas/Datum"
        einddatum:
          $ref: "#/components/schemas/Datum"
        vestigingen:
          description: Lijst van vestigingen
          type: array
          items:
            $ref: '#/components/schemas/Vestiging'
        links:
          description: URI naar API Basisprofiel voor het huidige kvknummer
          type: object
          required:
            - self
            - basisprofiel
          properties:
            self:
              $ref: '#/components/schemas/Link'
            basisprofiel:
              $ref: '#/components/schemas/Link'
          example:
            - title: Basisprofiel
              href: https://api.kvk.nl/api/v1/basisprofielen/59581883
    Vestiging:
      oneOf:
        - $ref: '#/components/schemas/CommercieleVestiging'
        - $ref: '#/components/schemas/NietCommercieleVestiging'
    CommercieleVestiging:
      description: Alle namen waaronder een vestiging handelt (op volgorde van registratie)
      type: object
      required:
        - vestigingsnummer
      properties:
        vestigingsnummer:
          description: Uniek nummer dat bestaat uit 12 cijfers
          example: "000015063097"
          type: string
          pattern: "^[0-9]{12}$"
        eersteHandelsnaam:
          description: De eerste handelsnaam van de Vestiging
          example: "Kamer van Koophandel"
          type: string
        handelsnamen:
          description: Alle namen waaronder een onderneming of vestiging handelt
          type: array
          items:
            $ref: '#/components/schemas/Handelsnaam'
        links:
          description: URI naar API Vestigingsprofiel voor het huidige vestigingsnummer
          type: object
          required:
            - vestigingsprofiel
          properties:
            vestigingsprofiel:
              $ref: '#/components/schemas/Link'
          example:
            - title: Vestigingsprofiel
              href: https://api.kvk.nl/api/v1/vestigingsprofielen/000015063097
    NietCommercieleVestiging:
      description: De naam waaronder een niet commerciele vestiging bekend is
      type: object
      required:
        - vestigingsnummer
      properties:
        vestigingsnummer:
          description: Uniek nummer dat bestaat uit 12 cijfers
          example: "000015063097"
          type: string
          pattern: "^[0-9]{12}$"
        naam:
          description: De naam van de Vestiging
          type: string
        ookGenoemd:
          description: Een andere naam waaronder de vereniging, stichtingen en vereniging van eigenaars ook bekend is
          type: string
        links:
          description: URI naar API Vestigingsprofiel voor het huidige vestigingsnummer
          type: object
          required:
            - vestigingsprofiel
          properties:
            vestigingsprofiel:
              $ref: '#/components/schemas/Link'
          example:
            - title: Vestigingsprofiel
              href: https://api.kvk.nl/api/v1/vestigingsprofielen/000015063097
    Handelsnaam:
      description: Een handelsnaam is een naam waaronder een vestiging van een onderneming handelt.
      type: object
      properties:
        naam:
          description: De handelsnaam van de vestiging
          example: "Kamer van Koophandel"
          type: string
        volgorde:
          description: Het volgorde nummer van een handelsnaam
          example: 0
          type: integer
    Datum:
      description: |
        In het handelsregister hebben we voor verschillende dossiers niet de exacte datums kunnen vastleggen.
        We volgen hier de Handels Register datum vastlegging voor.
        Hierdoor kan bij een onbekend deel van een datum nullen bevatten.
        Bij een volledig bekende datum is het formaat YYYYMMDD ( Jaar maand dag),
        waarbij alleen cijfers zijn toegestaan, inclusief de 0 voor onbekende delen van de datum.

        __Mogelijke formaten van waarden__

        | Type            | Formaat   |
        | --------------- | --------- |
        | Volledige datum | 20150622  |
        | Dag onbekend    | 20150600  |
        | Maand onbekend  | 20150012  |
        | Datum onbekend  | 00000000  |
      example: 20220421
      type: string
    Link:
      required:
        - href
      type: object
      properties:
        rel:
          type: string
        href:
          type: string
        title:
          type: string
          description: Omschrijving van de link
    Error:
      type: object
      properties:
        fout:
          type: array
          items:
            $ref: '#/components/schemas/Fout'
    Fout:
      type: object
      properties:
        code:
          description: Foutcode
          type: string
        omschrijving:
          description: Omschrijving van de foutmelding
          type: string
  responses:
    BadRequest:
      description: Een opgegeven parameter is niet valide
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Geen of onjuiste apikey aangeleverd
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Niet geautoriseerd voor deze operatie
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Er zijn geen resultaten gevonden aan de hand van de opgegeven parameter(s)
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAcceptable:
      description: Opgegeven Accept header wordt niet ondersteund
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Er is een interne fout opgetreden
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    api_version:
      schema:
        type: string
        description: Geeft een specifieke API-versie aan in de context van een specifieke
          aanroep.
        example: 1.0.0
    warning:
      schema:
        type: string
        description: zie RFC 7234. In het geval een major versie wordt uitgefaseerd,
          gebruiken we warn-code 299 ("Miscellaneous Persistent Warning") en het API
          end-point (inclusief versienummer) als de warn-agent van de warning, gevolgd
          door de warn-text met de human-readable waarschuwing
        example: '299 https://api.kvk.nl/api/v1/naamgevingen/ "Deze versie van de API is verouderd
          en zal uit dienst worden genomen op 2025-02-01. Raadpleeg voor meer informatie
          hier de documentatie: https://developers.kvk.nl/nl/apis/naamgeving".'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: De API-key die je hebt gekregen dient bij elke request via de `apikey`
        request header meegestuurd te worden. Indien deze niet juist wordt meegestuurd,
        of het een ongeldige key betreft, zul je de foutmelding `401 Unauthorized` terugkrijgen.
      name: apikey
      in: header