왜 Acumatica의 API는 REST 스위트에서 RPA처럼 느껴지는가 (그리고 이를 해결하는 방법)
Source: Dev.to
Acumatica의 Contract‑Based REST API와 통합해 본 적이 있다면, JSON을 처음 봤을 때 “잠깐, 뭐지?” 하는 순간을 겪었을 겁니다.
왜 모든 필드가 객체인가요? 2026년에 쿠키를 관리해야 하는 이유가 뭔가요?
“Value Wrapper Tax”, “Stateful REST” 아이러니, 그리고 정규화된 게이트웨이가 어떻게 여러분의 정신적 안정을 지켜줄 수 있는지 살펴보겠습니다.
1. “Value Wrapper” Tax 💸
일반적인 API에서는 Sales Order가 다음과 같이 보일 수 있습니다:
{
"CustomerID": "C01",
"OrderType": "SO"
}Acumatica에서는 이렇게 나옵니다:
{
"CustomerID": { "value": "C01" },
"OrderType": { "value": "SO" }
}왜 이런 구조가 존재하나요?
Acumatica의 API는 데이터베이스에 직접 연결되는 것이 아니라 UI 화면을 매핑한 것입니다. ERP에서 “Null”은 위험한 단어입니다. 래퍼는 시스템이 다음을 구분하도록 해줍니다:
- 생략: “이 필드는 건드리지 마세요.”
- 값 제공: “이 값을 X로 바꾸세요.”
- Null 값: “이 필드를 명시적으로 비우세요.”
문제점: 개발자 입장에서는 보일러플레이트 코드가 크게 늘어납니다. 모든 매핑에 .value 접근자를 추가해야 하므로 변환 로직의 복잡도가 두 배가 됩니다.
2. OAuth2 환상 🍪
Acumatica는 OAuth2를 지원합니다. 드디어 무상태(stateless)인가요?
아닙니다. Bearer 토큰을 사용하더라도 기본 아키텍처는 상태를 유지합니다. API를 호출하면 세션이 초기화되고 ASP.NET_SessionId 쿠키가 반환됩니다.
미들웨어가 그 쿠키를 캡처해 다시 보내지 않으면, 이후의 모든 요청은 새로운 세션을 생성합니다.
결과: 몇 초 만에 라이선스의 API 로그인 제한에 도달합니다.
해결책: 기본적인 CRUD 작업을 수행하기 위해 “쿠키 관리” 로직을 직접 작성하게 됩니다.
3. 더 나은 방법: 정규화된 게이트웨이 🛡️
“Acumatica‑logic”을 쓰는 대신 “product‑logic”을 쓸 수 있다면 어떨까요?
래퍼와 세션 쿠키 문제를 피하고 Canonical Model을 사용하려면 Aurinko의 Dynamic API 같은 게이트웨이를 활용하면 됩니다.
워크플로우
- 귀하의 앱이 표준, 무상태 REST 호출로 Aurinko Dynamic Gateway에 요청합니다.
- Aurinko가 요청을 Canonical SalesOrder 모델에 매핑합니다.
- 게이트웨이가 “지저분한 작업”을 처리합니다:
{"value": …}래퍼를 평탄화.- 상태 유지 세션 쿠키와 로그아웃 관리.
- 화면 기반 스키마를 예측 가능한 데이터 객체로 변환.
SyncHub에 적용하기
우리의 YoxelSync SyncHub for Salesforce에서는 이 게이트웨이 방식을 사용해 실제로 읽기 쉬운 동기화 레시피를 만들 수 있습니다. 중첩된 JSON 참조 대신, 레시피는 깔끔한 필드‑대‑필드 매핑처럼 보입니다.
직접 매핑 전:
Target.Customer = Source.CustomerID.value;정규화 후:
Target.Customer = Source.CustomerId;작은 변화처럼 보이지만, 50개 이상의 필드를 여러 ERP(Acumatica, NetSuite, FishBowl)와 매핑할 때 인지 부하 감소가 엄청납니다.
결론
Acumatica는 강력한 ERP이지만, API는 UI‑우선 철학을 반영합니다. “Wrapper Tax”와 “Cookie Dance”에 지쳤다면, 게이트웨이 레이어를 도입할 때일지도 모릅니다.
Tags: acumatica, api, erp, integration, javascript, webdev, aurinko