> ## Documentation Index
> Fetch the complete documentation index at: https://docs.banka.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Müşteri firması ekler

> VKN veya TCKN ile yeni müşteri firması oluşturur. Firma eklemek kredi düşmez; kredi banka bağlandığında kullanılır. Aynı entegratörde aynı VKN ikinci kez eklenirse 409 COMPANY_EXISTS döner.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/companies
openapi: 3.0.3
info:
  title: BankaPro API
  version: 1.0.0
  description: >-
    BankaPro'nun sunucudan sunucuya kullanılan REST API'sidir. Kimlik doğrulama
    HTTP Basic ile yapılır: kullanıcı adı anahtar kimliği, parola secret key
    değeridir. İki tür anahtar vardır. Firma anahtarı tek firmaya bağlıdır;
    firma anahtarın kendisinden belirlenir ve veri uçları /v1/... adresiyle
    çağrılır. Entegratör anahtarı yazılım firmaları içindir: birden çok müşteri
    firmasını (VKN) ve bu firmaların banka bağlantılarını yönetir, firma
    verisine /v1/companies/{companyId}/... adresiyle erişir; entegratör anahtarı
    firma adresi olmadan bir veri ucunu çağırırsa 400 COMPANY_REQUIRED döner,
    firma anahtarı entegratör uçlarını çağırırsa 403 FORBIDDEN döner.
    Entegratörde her müşteri firmasında bağlı her banka bir kredidir; dönemin
    herhangi bir anında aktif olan her firma-banka ikilisi o dönem için sayılır
    ve kota dolunca yeni bağlantı 403 CREDIT_LIMIT_REACHED ile reddedilir. Her
    iki anahtarda da companies, companiesId, companyIds veya scope adlı sorgu
    parametresi ya da başlık kabul edilmez. Tarayıcı kaynaklı (Origin başlığı
    taşıyan) istekler reddedilir. Anahtarın IP kısıtı doluysa istek yalnız
    listedeki adreslerden kabul edilir. Veri uçları baAccounts, baTransactions,
    baOperations veya baSync yetkisiyle, entegratör uçları baCompanies veya
    baConnections yetkisiyle korunur; karşı taraf IBAN ve TCKN/VKN değerlerini
    açık görmek için baPii ayrıca atanmalıdır. Başarı yanıtı success/data/meta,
    hata yanıtı success:false/error/traceId biçimindedir. Tüm yanıtlarda
    x-request-id ve Cache-Control: no-store bulunur. Zamanlar UTC ISO-8601,
    parasal değerler iki ondalıklı metindir; farklı para birimleri tek toplamda
    birleştirilmez. Bilinmeyen bakiye null, bankanın bildirdiği gerçek sıfır
    0.00 olarak döner. Bu sözleşme banka hesabı, banka hareketi, manuel banka
    sorgusu ve entegratör (müşteri firması, banka bağlantısı, kredi) uçlarını
    kapsar.
servers:
  - url: https://api.banka.pro
    description: BankaPro canlı API
security:
  - BasicAuth: []
tags:
  - name: Accounts
    description: >-
      Credential firmasının banka hesapları, bakiye özetleri ve doğrulanmış
      bakiye geçmişi
  - name: Transactions
    description: Credential firmasının banka hareketleri, özetleri ve izinli operasyonları
  - name: Queries
    description: >-
      Credential firmasının banka hesaplarında mevcut sorgu motoruyla manuel
      yenileme
  - name: Integrator
    description: 'Entegratör anahtarı: müşteri firmaları (VKN) ve kredi özeti'
  - name: Bank connections
    description: >-
      Entegratör anahtarı: müşteri firmalarının banka bağlantıları ve banka
      kataloğu
paths:
  /v1/companies:
    parameters:
      - $ref: '#/components/parameters/RequestIdInput'
    post:
      tags:
        - Integrator
      summary: Müşteri firması ekler
      description: >-
        VKN veya TCKN ile yeni müşteri firması oluşturur. Firma eklemek kredi
        düşmez; kredi banka bağlandığında kullanılır. Aynı entegratörde aynı VKN
        ikinci kez eklenirse 409 COMPANY_EXISTS döner.
      operationId: createIntegratorCompany
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegratorCompanyCreateRequestEnvelope'
            examples:
              company:
                summary: Şirket
                value:
                  data:
                    taxId: '1234567890'
                    title: Örnek Ticaret A.Ş.
      responses:
        '201':
          description: Oluşturulan firma
          headers:
            x-request-id:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/NoStore'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegratorCompanyResponse'
              examples:
                created:
                  summary: Yeni firma (henüz banka bağlı değil)
                  value:
                    success: true
                    data:
                      id: 64f000000000000000000001
                      taxId: '1234567890'
                      title: Örnek Ticaret A.Ş.
                      status: active
                      bankCodes: []
                      creditCount: 0
                      createdAt: '2026-10-17T09:00:00.000Z'
                      updatedAt: '2026-10-17T09:00:00.000Z'
                    meta:
                      requestId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
                      timestamp: '2026-10-17T09:00:00.000Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    RequestIdInput:
      name: x-request-id
      in: header
      required: false
      description: >-
        Opsiyonel izleme kimliği. Değer 1-100 karakter ve yalnız harf, rakam,
        nokta, alt çizgi, iki nokta veya tire içeriyorsa korunur; aksi halde
        sunucu yeni bir UUID üretir.
      schema:
        type: string
        minLength: 1
        maxLength: 100
        pattern: ^[A-Za-z0-9._:-]{1,100}$
      example: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
  schemas:
    IntegratorCompanyCreateRequestEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/IntegratorCompanyCreateInput'
    IntegratorCompanyResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessBase'
        - type: object
          required:
            - data
          properties:
            data:
              $ref: '#/components/schemas/IntegratorCompany'
    IntegratorCompanyCreateInput:
      type: object
      additionalProperties: false
      required:
        - taxId
        - title
      properties:
        taxId:
          type: string
          pattern: ^\d{10,11}$
          description: >-
            VKN (10 hane) veya şahıs işletmesi için TCKN (11 hane); kontrol
            hanesi doğrulanır. Aynı entegratörde tekildir.
          example: '1234567890'
        title:
          type: string
          minLength: 2
          maxLength: 200
          example: Örnek Ticaret A.Ş.
    SuccessBase:
      type: object
      required:
        - success
        - meta
      properties:
        success:
          type: boolean
          enum:
            - true
        meta:
          $ref: '#/components/schemas/ResponseMeta'
    IntegratorCompany:
      type: object
      required:
        - id
        - taxId
        - title
        - status
        - bankCodes
        - creditCount
        - createdAt
        - updatedAt
      properties:
        id:
          $ref: '#/components/schemas/ObjectId'
        taxId:
          type: string
          nullable: true
          example: '1234567890'
        title:
          type: string
          nullable: true
          example: Örnek Ticaret A.Ş.
        status:
          type: string
          enum:
            - active
            - passive
        bankCodes:
          type: array
          description: Firmada o an aktif bağlı bankaların kodları; pasif firmada boştur.
          items:
            type: string
          example:
            - akbank
            - garanti
        creditCount:
          type: integer
          description: Firmanın o an kullandığı kredi (aktif bağlı banka sayısı).
          example: 2
        createdAt:
          allOf:
            - $ref: '#/components/schemas/UtcTimestamp'
          nullable: true
        updatedAt:
          allOf:
            - $ref: '#/components/schemas/UtcTimestamp'
          nullable: true
    ErrorEnvelope:
      type: object
      required:
        - success
        - error
        - traceId
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              example: VALIDATION_FAILED
            message:
              type: string
              example: İstek doğrulanamadı.
            details:
              type: array
              items:
                $ref: '#/components/schemas/ValidationDetail'
        traceId:
          type: string
          nullable: true
          example: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    ResponseMeta:
      type: object
      required:
        - requestId
        - timestamp
      properties:
        requestId:
          type: string
          example: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
        timestamp:
          $ref: '#/components/schemas/UtcTimestamp'
        partial:
          type: boolean
          description: Yanıtın kontrollü fallback veya eksik veri içerdiğini belirtir.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/ApiWarning'
    ObjectId:
      type: string
      pattern: ^[a-fA-F0-9]{24}$
      example: 64f000000000000000000001
    UtcTimestamp:
      type: string
      format: date-time
      description: UTC ISO-8601 zamanı.
      example: '2026-09-08T20:00:00.000Z'
    ValidationDetail:
      type: object
      required:
        - field
        - rule
      properties:
        field:
          type: string
          example: pageSize
        rule:
          type: string
          example: min:1,max:100
    ApiWarning:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - TODAY_BALANCE_SNAPSHOT_FALLBACK
            - BALANCE_HISTORY_MISSING
            - BALANCE_HISTORY_PARTIAL
            - BALANCE_CURRENCY_MISMATCH
            - BALANCE_VALUE_UNKNOWN
            - BALANCE_VALUE_STALE
            - INVALID_ACCOUNT_CURRENCY
        message:
          type: string
        date:
          type: string
          format: date
          example: '2026-09-07'
        accountCount:
          type: integer
          minimum: 0
  headers:
    RequestId:
      description: >-
        İsteğin izleme kimliği. İstemcinin gönderdiği değer 1-100 karakter ve
        yalnız harf, rakam, nokta, alt çizgi, iki nokta veya tire içeriyorsa
        korunur; aksi halde sunucu tarafından UUID üretilir.
      schema:
        type: string
        maxLength: 100
        pattern: ^[A-Za-z0-9._:-]{1,100}$
        example: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    NoStore:
      description: Banka verisinin istemci veya ara katmanda saklanmamasını belirtir.
      schema:
        type: string
        enum:
          - no-store
    WwwAuthenticate:
      description: HTTP Basic kimlik doğrulama challenge değeri.
      schema:
        type: string
        example: Basic realm="BankaPro API", charset="UTF-8"
    RetryAfter:
      description: İsteğin kaç saniye sonra yeniden denenebileceğini belirtir.
      schema:
        type: integer
        minimum: 0
    RateLimit:
      description: >-
        Geçerli oran sınırı ve kalan kota bilgisini standart RateLimit biçiminde
        taşır.
      schema:
        type: string
  responses:
    BadRequest:
      description: İstek doğrulama hatası
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: VALIDATION_FAILED
              message: pageSize 1-100 araliginda olmalidir.
              details:
                - field: pageSize
                  rule: min:1,max:100
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    Unauthorized:
      description: HTTP Basic credential yok, geçersiz, iptal edilmiş veya süresi geçmiş
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        WWW-Authenticate:
          $ref: '#/components/headers/WwwAuthenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: >-
        Anahtarın firması veya entegratör sözleşmesi uygun değil, zorunlu
        ürün/uç yetkisi yok, uç bu anahtar türüne kapalı, kredi kotası dolu veya
        IP kısıtı bağlantının güvenilir istemci IP'siyle eşleşmiyor
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: FORBIDDEN
              message: Bu islem icin yetkiniz bulunmuyor.
              details: []
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    NotFound:
      description: Yetkili kapsamda kaynak bulunamadı
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: RESOURCE_NOT_FOUND
              message: Banka hareketi bulunamadi.
              details: []
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    Conflict:
      description: Kayıt zaten var veya aynı anda süren başka bir işlem var
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: COMPANY_EXISTS
              message: Bu VKN ile kayitli bir firma zaten var.
              details:
                - field: taxId
                  rule: unique
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    PayloadTooLarge:
      description: İstek gövdesi izin verilen boyutu aşıyor
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: PAYLOAD_TOO_LARGE
              message: Istek govdesi izin verilen boyutu asiyor.
              details: []
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    TooManyRequests:
      description: İstek limiti aşıldı
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            error:
              code: RATE_LIMITED
              message: Istek limiti asildi. Daha sonra tekrar deneyin.
              details: []
            traceId: 9cc0d3d1-1e63-4c90-b08f-90b6332e70ca
    InternalError:
      description: Beklenmeyen sunucu hatası
      headers:
        x-request-id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/NoStore'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: >-
        Kullanıcı adı anahtar kimliği, parola secret key değeridir. Anahtar
        aktif olmalı, erişim bitiş tarihi geçmemiş olmalı ve BankaPro erişimine
        sahip olmalıdır. Firma anahtarında firma anahtardan sunucu tarafında
        belirlenir; istemciden firma kimliği alınmaz. Entegratör anahtarı
        firmayı yalnız /v1/companies/{companyId} adresinden alır ve yalnız kendi
        müşteri firmalarına erişir. Anahtarın IP kısıtı doluysa istek yalnız
        listedeki adreslerden kabul edilir. Kimlik bilgileri yalnız HTTPS
        üzerinden gönderilmelidir.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.