QuickBooks TimeActivity API: ID가 존재함에도 Invalid ProjectRef가 발생하는 이유

우리는 TimeActivity를 생성해야 하는 QuickBooks Online API 연동 작업을 진행하고 있었습니다.
페이로드(Payload)는 문제가 없어 보였습니다.
프로젝트 ID(Project ID)는 QuickBooks에 존재했습니다.
직원 참조(Employee reference)도 정확했습니다.

하지만 API는 여전히 다음과 같은 응답을 반환했습니다:

Invalid ProjectRef

처음에는 단순히 잘못된 ID 문제처럼 보입니다.
하지만 이 경우, ID가 문제는 아니었습니다.
진짜 문제는 QuickBooks가 해당 레코드를 유효한 프로젝트로 간주하지 않았다는 점이었습니다.

놓치기 쉬운 부분:
QuickBooks에서 프로젝트는 고객(Customer) 레코드와 연결되어 있지만, 모든 고객 레코드가 프로젝트인 것은 아닙니다.

놓치기 쉬운 부분:

• QuickBooks에서 프로젝트는 고객(Customer) 레코드와 연결됩니다.
• 하지만 모든 고객 레코드가 프로젝트로 취급되는 것은 아닙니다.
• 일반적인 고객은 CustomerRef를 통해 작동하지만, ProjectRef를 사용하지는 않습니다.
• 하위 고객(Sub-customer)은 때때로 작동할 수 있지만, 항상 그런 것은 아닙니다.
• 적절한 QuickBooks 프로젝트는 CustomerRef와 ProjectRef를 모두 사용합니다.

따라서 ID가 존재하더라도, QuickBooks는 ProjectRef 내부에서 이를 거부할 수 있습니다.
이것이 이 에러가 혼란스러울 수 있는 이유입니다.

CustomerRef와 ProjectRef는 서로 대체될 수 없습니다

• 시간 입력(Time entry)이 고객에게만 연결되면 되는 경우에는 CustomerRef를 사용하십시오.
• 시간 입력이 실제 QuickBooks 프로젝트 아래에서 추적되어야 하는 경우에는 ProjectRef를 사용하십시오.
• 이는 사소해 보일 수 있지만, QuickBooks가 요청을 검증하는 방식을 바꿉니다.
• 일반적인 고객 수준의 시간 추적(Time tracking)에는 보통 CustomerRef로 충분합니다.
• 프로젝트 수준의 청구(Billing), 보고(Reporting) 또는 작업 추적(Job tracking)을 위해서는 ProjectRef를 사용하되, 해당 레코드가 실제로 프로젝트로 표시되어 있는지 확인한 후에 사용하십시오.

가장 먼저 수행해야 할 확인 사항
페이로드를 여러 번 수정하기 전에, 해당 프로젝트 ID에 대한 고객(Customer) 레코드를 확인하십시오.

다음 쿼리를 사용하십시오:
SELECT * FROM Customer WHERE Id = 'PROJECT_ID'

그런 다음 다음 값들을 확인하십시오:
Active = true
Job = true
IsProject = true

만약 Job 또는 IsProject가 false라면, 레코드가 존재할 수는 있지만 ProjectRef용으로는 유효하지 않은 것입니다.
보통 에러는 바로 그 지점에서 발생합니다.

빠른 디버깅 노트

실수는 보통 TimeActivity 필드 자체에 있지 않습니다.
대개 문제는 바로 이 지점에서 발생합니다:
ID는 존재하지만, 해당 레코드가 프로젝트(Project) 기능이 활성화되어 있지 않은 경우입니다.
따라서 단순히 ID가 존재하는지만 확인할 것이 아니라, QuickBooks가 해당 레코드를 어떤 유형으로 인식하고 있는지 확인해야 합니다.

Invalid ProjectRef의 일반적인 원인:

• ID가 일반 고객(Customer)에 속해 있으므로, 대신 CustomerRef를 사용해야 합니다.
• ID가 하위 고객(Sub-customer)에 속해 있지만, 프로젝트로 표시되지 않았을 수 있습니다.
• 프로젝트가 비활성(Inactive) 상태이므로, Active 값을 확인하십시오.
• 프로젝트가 임포트(Import)된 경우, 프로젝트 관련 플래그(Flag)가 누락되었을 수 있습니다.
• Job이 false라면, 해당 레코드는 ProjectRef로 유효하지 않습니다.
• IsProject가 false라면, 해당 레코드는 ProjectRef로 유효하지 않습니다.
• 잘못된 참조 필드가 사용되었을 수 있으므로, CustomerRef가 올바른 옵션일 수 있습니다.

간단한 해결 방법

프로젝트 수준의 추적(Tracking)이 필요하지 않은 경우에는 ProjectRef를 CustomerRef로 교체하십시오.
많은 경우 이 방법으로 문제가 해결됩니다.
프로젝트 수준의 추적이 필요한 경우에는 프로젝트를 먼저 검증하십시오. 만약 레코드가 손상된 것처럼 보이거나 잘못 임포트되었다면, QuickBooks UI에서 프로젝트를 다시 생성하고 새로운 참조(Reference)를 사용하십시오.

최종 요약

Invalid ProjectRef가 항상 ID가 틀렸음을 의미하는 것은 아닙니다.
많은 경우, 이는 QuickBooks가 해당 레코드를 유효한 프로젝트로 인식하지 못함을 의미합니다.
따라서 페이로드(Payload)를 계속해서 수정하기 전에, 다음 세 가지 값을 확인하십시오:
Active
Job
IsProject

이 한 번의 확인이 많은 디버깅 시간을 절약해 줄 수 있습니다.

Satva Solutions에 원문 게시됨:
QuickBooks TimeActivity API Error: Fix Invalid ProjectRef