.. _intro_03_broker:

============================
Broker API 호출하기
============================

이 튜토리얼에서는 PyQQQ에서 지원하는 증권 중개인(Broker) 중 하나인 한국투자증권을 이용합니다. 한국투자증권에서 제공하는 API(Broker API)를 사용하여 삼성전자의 종가를 조회하는 방법을 알아보겠습니다.

Broker API
----------------

Broker API란? 증권사에서 제공하는 API 서비스로 이를 통해 주가 조회, 거래 등 주식거래에 필요한 다양한 기능을 이용할 수 있다. PyQQQ SDK에서는 모든 Broker API를 지원하고 있지는 않으며 자주 사용하는 Broker API를 선별하여 지원하고 있다.
이번 튜토리얼에서 사용할 API는 ``한국투자증권의 주식현재가 일자별[v1_국내주식-010]`` 로 다음과 같습니다. 자세한 내용은 `API 페이지 <https://apiportal.koreainvestment.com/apiservice/apiservice-domestic-stock-quotations2#L_011d4de2-a4a0-47c0-aa47-20c65a26a763>`_ 에서 확인할 수 있습니다.

.. image:: ../../_static/images/kis_open_api.png
    :class: focus-box
    :width: 600
    :align: center

API 페이지를 참고하여 Query Parameter를 설정하고, Response를 분석해야 합니다.
삼성전자의 일자별 주식 정보를 조회하기 위해 다음의 Query Parameter를 사용합니다.

1. FID_COND_MRKT_DIV_CODE: 삼성전자의 주식을 조회하려면 **J** 로 설정합니다.
2. FID_INPUT_ISCD: 단축코드 **005930** 을 사용하여 삼성전자를 지정합니다.
3. FID_PERIOD_DIV_CODE: 최근 30거래일의 데이터를 조회하려면 **D** 로 설정합니다.
4. FID_ORG_ADJ_PRC: 수정 주가를 반영하지 않으려면 **1** 로 설정합니다.

이제 PyQQQ SDK를 통해 Broker API를 호출해보도록 하겠습니다.

.. note::
    Broker API에 대한 정보는 각 증권사의 페이지를 참고합니다.

    * `한국투자 Open API <https://apiportal.koreainvestment.com/apiservice>`_
    * `LS증권 Open API <https://openapi.ls-sec.co.kr/apiservice>`_


PyQQQ Broker API
-----------------------------

.. literalinclude:: ../../../../examples/tutorials/03_broker.py
    :language: python
    :caption: kis.py

한국투자증권의 Broker API를 사용하기 위해서는 :ref:`한국투자증권의 API Key<brokers_kis>` 정보를 가지고 있어야 합니다.
``app_key`` 와 ``app_secret`` 을 수정한 후 코드를 실행하면 최근 30거래일의 삼성전자 정보를 얻어올 수 있습니다.

.. code-block:: console

    2025-01-20 | 종가 53600
    2025-01-17 | 종가 53700
    2025-01-16 | 종가 54300
    2025-01-15 | 종가 53700
    2025-01-14 | 종가 53900
    2025-01-13 | 종가 54100
    2025-01-10 | 종가 55300
    ...

증권사마다 제공하는 API와 요청, 응답결과가 상이하므로 Broker API 사용 시 유의해야 합니다. 예를 들어, A 증권사에서 제공하는 기능이 B 증권사에서는 없을 수 있습니다.