MYOB Advanced API: REST API에서 회사(Companies) 및 회계 기간(Financial Periods)이 나타나지 않을

이 문제는 처음 접하면 혼란스러워 보일 수 있는 MYOB Advanced API 이슈 중 하나입니다.
MYOB Advanced 내부에서는 데이터를 확인할 수 있습니다. 회사(Companies)도 있고, 회계 기간(Financial Periods)도 있습니다. UI 상에서도 해당 화면들을 사용할 수 있습니다.
하지만 REST API를 통해 동일한 데이터에 접근하려고 하면, 기본 엔드포인트(default endpoint)를 통해서는 사용할 수 없습니다.
그렇다고 해서 항상 데이터에 접근할 수 없다는 뜻은 아닙니다.

이는 대개 기본 웹 서비스 엔드포인트(Web Service Endpoint)가 해당 데이터를 노출(exposing)하고 있지 않음을 의미합니다.
MYOB Advanced는 웹 서비스 엔드포인트를 사용하여 어떤 화면, 엔티티(entities), 필드(fields), 액션(actions)이 REST API를 통해 사용 가능한지를 결정합니다. 표준 엔드포인트는 고객(customers), 공급업체(vendors), 재고 항목(inventory items), 판매 주문(sales orders)과 같은 일반적인 레코드(records)를 다루지만, 기본적으로 모든 화면이나 모든 필드를 노출하지는 않습니다.

따라서 통합(integration) 과정에서 회사(Companies), 회계 기간(Financial Periods) 또는 사용자 정의 화면(custom screen) 데이터가 필요하다면, 엔드포인트를 확장(extend)해야 할 수도 있습니다.

개발자들이 자주 하는 실수

기본 REST API에서 데이터가 누락되었을 때, 개발자들의 첫 번째 반응은 대개 올바른 객체 이름(object name)을 찾는 것입니다.
아마 이름이 Company일지도 모릅니다.
아마 이름이 Companies일지도 모릅니다.
아마 재무 설정(financial setup) 아래에 있을지도 모릅니다.
아마 $expand가 필요할지도 모릅니다.
하지만 때로는 쿼리(query) 때문에 객체가 누락되는 것이 아닙니다.
엔드포인트에서 아예 노출되지 않았기 때문에 누락된 것입니다.
이것이 핵심입니다.
MYOB Advanced에서 엔드포인트는 거의 API 계약(API contract)처럼 작동합니다. 만약 특정 엔티티나 필드가 해당 계약의 일부가 아니라면, 시스템 내부에 데이터가 존재하더라도 API는 이를 반환하지 않습니다.

기본 엔드포인트 vs 사용자 정의 엔드포인트

간단한 차이점은 다음과 같습니다:
기본 엔드포인트 (Default endpoint)
고객, 공급업체, 재고, 판매 주문과 같은 표준 레코드
사용자 정의 / 확장 엔드포인트 (Custom / extended endpoint)
누락된 화면, 사용자 정의 필드(custom fields), 회사(Companies), 회계 기간(Financial Periods), 회사별 재무 데이터

통합(integration)에 표준 비즈니스 객체(standard business objects)만 필요하다면 기본 엔드포인트(default endpoint)로 충분할 수 있습니다.
하지만 워크플로(workflow)에 설정 수준의 데이터(setup-level data)나 회계 기간(financial period) 상세 정보가 필요하다면, 임시방편(workarounds)을 만들기보다는 엔드포인트를 확장(extend)하는 것이 대개 더 나은 선택입니다.

API를 통한 회사(Companies) 노출
회사의 경우, 웹 서비스 엔드포인트(Web Service Endpoints) 화면에서 엔드포인트를 확장해야 합니다.
기존 Satva 가이드에서는 회사를 위해 다음 화면을 사용합니다:
CS101500

대략적인 흐름은 다음과 같습니다:

1. 웹 서비스 엔드포인트(Web Service Endpoints)를 엽니다.
2. 기존 엔드포인트를 확장(Extend)합니다.
3. 회사(Companies)를 위한 새로운 엔티티(entity)를 추가합니다.
4. 이를 화면 CS101500에 매핑(Map)합니다.
5. 필드(fields)를 채웁니다.
6. 엔드포인트를 저장합니다.
7. API를 테스트합니다.

설정 후, 테스트 호출은 다음과 같은 형태가 될 수 있습니다:
GET {{baseURL}}/{{endpoint}}/Companies

모든 것이 적절하게 매핑되었다면, API가 회사(Companies) 데이터를 반환하기 시작할 것입니다.
참고: 만약 엔티티(entity)가 나타나지 않는다면, 엔드포인트 이름, 버전, 화면 매핑(screen mapping), 그리고 엔티티를 추가한 후 엔드포인트를 저장했는지 여부를 확인하십시오.

회계 기간(Financial Periods)도 동일한 처리가 필요합니다
회계 기간(Financial Period) 데이터 또한 일반적인 설정에서는 표준 REST 엔드포인트(standard REST endpoint)를 통해 사용할 수 없습니다.
따라서 통합(integration)에 기간 상세 정보, 마감 기간 로직(closing period logic), 보고 기간(reporting periods) 또는 회사별 캘린더 데이터가 필요하다면, 회계 기간(Financial Period)을 사용자 정의 엔티티(custom entity)로 추가해야 합니다.
호출은 다음과 같을 수 있습니다:

`GET {{baseURL}}/{{endpoint}}/FinancialPeriod?$expand=Details

중요한 부분은 단순히 API URL만이 아닙니다.
엔티티(entity)가 먼저 사용자 정의 엔드포인트(custom endpoint)에 추가되어야 합니다. 그렇지 않으면 API 호출이 마법처럼 데이터를 반환하지는 않습니다.

결과를 바꿀 수 있는 한 가지 설정

회계 기간(Financial Period) 응답을 디버깅(debugging)하는 데 너무 많은 시간을 쓰기 전에, 중앙 집중식 기간 관리(Centralized Period Management)를 확인하십시오.
이 설정은 MYOB Advanced에서 회계 기간이 작동하는 방식을 변경합니다.

중앙 집중식 기간 관리(Centralized Period Management) ON
모든 회사가 동일한 회계 기간을 공유합니다.

중앙 집중식 기간 관리(Centralized Period Management) OFF
각 회사가 자체적인 회계 기간을 관리할 수 있습니다.

중앙 집중식 기간 관리(Centralized Period Management)가 활성화된 경우, 기간(Periods)이 전역적으로 처리되기 때문에 회사 수준의 필터링(Filtering)이 예상대로 작동하지 않을 수 있습니다. 이 기능이 비활성화되면 회사별 회계 기간(Financial Period) 작업이 가능해집니다.

따라서 API 응답이 회사별로 필터링되지 않는다면, 엔드포인트(Endpoint)만이 유일한 문제 아닐 수 있습니다. 시스템 설정(Configuration)이 동작에 영향을 미치고 있을 수 있습니다.

빠른 문제 해결 노트 (Quick troubleshooting notes)

• 엔티티(Entity)가 API에서 보이지 않음 - 엔드포인트(Endpoint)가 저장되었는지 확인
• API URL에서 오류 반환 - 엔드포인트 이름, 버전, 엔티티 이름 확인
• 필드(Fields)가 누락됨 - Fields 탭 아래의 Populate 사용
• 사용자 정의 필드(Custom field)가 반환되지 않음 - 커스터마이징 패키지(Customization package)가 게시(Published)되었는지 확인
• 회계 기간(Financial Period)이 회사별로 필터링되지 않음 - 중앙 집중식 기간 관리(Centralized Period Management) 확인
• 빈 응답(Empty response) - 화면 매핑(Screen mapping) 및 사용자 권한(User access) 확인

이러한 문제의 대부분은 API 버그가 아닙니다. 대개 엔드포인트 설정, 필드 매핑, 권한 또는 구성에서 발생합니다.

사용자 정의 엔드포인트(Custom endpoints)가 가치 있는 경우
기본 REST API가 통합 요구 사항(Integration requirement)과 일치하지 않을 때 사용자 정의 엔드포인트가 유용합니다.

예시:

• 회사의 데이터가 필요한 경우
• 회계 기간(Financial Period) 데이터가 필요한 경우
• 사용자 정의 필드(Custom fields)가 필요한 경우
• 기본적으로 노출되지 않는 화면의 데이터가 필요한 경우
• 회사별 회계 달력(Financial calendar) 동작이 필요한 경우
• API 응답이 외부 시스템의 워크플로(Workflow)와 일치하기를 원하는 경우

단순한 통합의 경우 사용자 정의 엔드포인트가 필요하지 않을 수 있습니다. 하지만 필요한 데이터가 기본 엔드포인트 범위를 벗어난다면, 복잡한 우회 방법(Workarounds)을 만드는 것보다 엔드포인트를 확장(Extending)하는 것이 대개 더 깔끔합니다.

기억해야 할 사항
MYOB Advanced 내부에서는 회사(Companies) 또는 회계 기간(Financial Periods)이 보이지만 REST API에서 누락된 경우, 데이터가 사용할 수 없다고 가정하지 마십시오.

먼저 엔드포인트가 해당 데이터를 노출하는지 확인하십시오.

• 회사(Companies)의 경우, Companies 화면을 매핑하십시오.
• 회계 기간(Financial Periods)의 경우, Financial Period를 사용자 정의 엔티티(Custom entity)로 추가하십시오.
• 회사별 기간 동작의 경우, 중앙 집중식 기간 관리(Centralized Period Management)를 확인하십시오.

요약하자면:
데이터가 이미 MYOB Advanced에 존재할 수 있습니다.
단지 API에 해당 데이터를 노출하도록 알려주기만 하면 됩니다.

Satva Solutions에 최초 게시됨:
MYOB Advanced API 커스텀 엔드포인트(Custom Endpoints) 가이드
https://satvasolutions.com/blog/myob-advanced-expose-custom-web-service-endpoints