ComposioHQ/QuickBooks-Automation

QuickBooks 자동화

청구서 생성, 고객 관리, 계정 조회, 청구서 목록 조회 등 QuickBooks Online 작업을 자동화하여 재무 보고를 간소화합니다.

툴킷 문서: composio.dev/toolkits/quickbooks

---

설정

이 스킬은 https://rube.app/mcp에 연결된 Rube MCP 서버가 필요합니다.

도구를 실행하기 전에 quickbooks 툴킷에 대한 활성 연결이 있는지 확인하세요. 활성 연결이 없으면 RUBE_MANAGE_CONNECTIONS를 통해 연결을 시작하세요.

---

핵심 워크플로우

1. 청구서 생성

고객에 대한 새 청구서를 라인 항목과 함께 생성합니다.

도구: QUICKBOOKS_CREATE_INVOICE

주요 파라미터:

• customer_id (필수) -- 고객 ID (CustomerRef.value)
• lines (필수) -- 라인 항목 객체 배열. 각 항목은 다음을 포함해야 함:
  • DetailType -- 예: "SalesItemLineDetail"
  • Amount -- 라인 항목 합계
  • SalesItemLineDetail -- ItemRef를 포함하는 객체 (value는 항목 ID)
• minorversion -- 선택적 API 버전 파라미터

예제:

도구: QUICKBOOKS_CREATE_INVOICE
인수:
  customer_id: "21"
  lines: [
    {
      "DetailType": "SalesItemLineDetail",
      "Amount": 150.00,
      "SalesItemLineDetail": {
        "ItemRef": {"value": "1", "name": "서비스"}
      }
    }
  ]

전제 조건: QUICKBOOKS_READ_CUSTOMER를 사용하여 고객 ID를 확인하거나 QUICKBOOKS_CREATE_CUSTOMER로 새 고객을 생성하세요. QUICKBOOKS_QUERY_ACCOUNT를 사용하여 항목/계정 ID를 확인하세요.

---

2. 고객 관리

고객 레코드를 생성하고 읽습니다.

도구:

• QUICKBOOKS_CREATE_CUSTOMER -- 새 고객 생성
• QUICKBOOKS_READ_CUSTOMER -- ID로 고객 읽기

QUICKBOOKS_CREATE_CUSTOMER 주요 파라미터:

• display_name -- 표시 이름 (고객, 판매업자, 직원 간 고유해야 함, 최대 500자)
• given_name -- 이름 (최대 100자)
• family_name -- 성 (최대 100자)
• middle_name -- 중간 이름 (최대 100자)
• title -- 호칭, 예: "Mr.", "Dr." (최대 16자)
• suffix -- 이름 접미사, 예: "Jr." (최대 16자)

display_name, title, given_name, middle_name, family_name 또는 suffix 중 하나 이상이 필수입니다.

QUICKBOOKS_READ_CUSTOMER 주요 파라미터:

• customer_id (필수) -- 읽을 고객의 ID

예제:

도구: QUICKBOOKS_CREATE_CUSTOMER
인수:
  display_name: "에이크미 코퍼레이션"
  given_name: "존"
  family_name: "도"

---

3. 계정 조회 및 읽기

청구서 라인 항목 및 재무 보고에 사용할 계정 정보를 검색합니다.

도구:

• QUICKBOOKS_QUERY_ACCOUNT -- 계정에 대한 쿼리 실행
• QUICKBOOKS_READ_ACCOUNT -- ID로 특정 계정 읽기

QUICKBOOKS_QUERY_ACCOUNT 주요 파라미터:

• query (필수) -- SQL과 유사한 쿼리 문자열, 예: "SELECT * FROM Account WHERE AccountType = 'Income'"

예제:

도구: QUICKBOOKS_QUERY_ACCOUNT
인수:
  query: "SELECT * FROM Account WHERE AccountType = 'Income' MAXRESULTS 10"

---

4. 청구서 목록 및 필터링

선택적 페이지네이션 및 필터링을 사용하여 청구서를 검색합니다.

도구: QUICKBOOKS_LIST_INVOICES

단계:

1. 페이지네이션 파라미터와 함께 QUICKBOOKS_LIST_INVOICES 호출
2. start_position 및 max_results를 사용하여 결과를 페이지 단위로 나누기
3. 필요에 따라 특정 기준으로 필터링

---

권장 실행 계획

1. 고객 확인 -- QUICKBOOKS_READ_CUSTOMER 사용 (고객 ID가 있는 경우) 또는 QUICKBOOKS_CREATE_CUSTOMER로 새 고객 생성
2. 항목/수익 계정 확인 -- QUICKBOOKS_QUERY_ACCOUNT 및 QUICKBOOKS_READ_ACCOUNT를 사용하여 청구서 라인 항목에 사용할 계정 또는 항목 ID 확보
3. 청구서 생성 -- 확인된 customer_id와 올바른 라인 항목으로 QUICKBOOKS_CREATE_INVOICE 사용
4. 생성 확인 -- QUICKBOOKS_LIST_INVOICES를 사용하여 ID 또는 DocNumber로 새 청구서 위치 확인

---

알려진 문제점

문제점	설명
유효하지 않은 참조	customer_id 또는 ItemRef.value가 존재하지 않거나 비활성화된 레코드를 가리키면 QUICKBOOKS_CREATE_INVOICE가 실패합니다. 항상 먼저 ID를 확인하세요.
라인 항목 검증	잘못된 DetailType 또는 누락된 SalesItemLineDetail 필드는 청구서 생성 중 스키마/검증 오류를 유발합니다.
페이지네이션	QUICKBOOKS_LIST_INVOICES는 start_position과 max_results를 사용합니다. 페이지네이션 설정이 부적절하면 규모가 큰 장부에서 청구서를 놓칠 수 있습니다.
동기화 토큰	이후 수정하려면 최신 청구서 읽기에서 받은 최신 SyncToken이 필요합니다. 오래된 동기화 토큰은 업데이트 거부를 초래합니다.
속도 제한	QuickBooks는 분당 및 일일 API 한도를 적용합니다. 대량 실행 시 제한 오류를 피하기 위해 백오프를 포함해야 합니다.
DisplayName 고유성	고객 display_name은 모든 Customer, Vendor, Employee 객체 간에 고유해야 합니다. 중복 시 생성 실패가 발생합니다.

---

빠른 참조

도구 이름	설명
QUICKBOOKS_CREATE_INVOICE	라인 항목으로 새 청구서 생성
QUICKBOOKS_READ_CUSTOMER	ID로 고객 레코드 읽기
QUICKBOOKS_CREATE_CUSTOMER	새 고객 레코드 생성
QUICKBOOKS_QUERY_ACCOUNT	SQL과 유사한 구문으로 계정 조회
QUICKBOOKS_READ_ACCOUNT	ID로 특정 계정 읽기
QUICKBOOKS_LIST_INVOICES	페이지네이션으로 청구서 목록 조회

---

Composio 제공