Xero에 연결

PlaidCloud를 Xero의 Accounting API에 연결하면 쿼리를 직접 작성하지 않고도 계정과목표, 연락처, 송장, 대변 메모, 결제, 수동 분개 등을 가져오고 문서를 다시 전기할 수 있습니다. 이 가이드에서는 연결, 가져오기 단계, 전기 단계를 설명합니다.

주의

모든 가져오기는 먼저 데모 조직에서 실행하고, 실제 전기 전에 모든 전기 배치에 대해 아래의 Test Only Mode 절차를 거치십시오.

사전 요구 사항

Xero에서 다음이 필요합니다.

• 읽고 전기하려는 조직에 액세스할 수 있는 Xero 로그인.
• 해당 조직에 연결된 앱을 승인할 수 있는 권한. Xero는 설정 중에 권한 부여를 승인하도록 요청합니다.

이것이 전부입니다. PlaidCloud가 OAuth 앱을 등록하므로 개발자 계정, 클라이언트 ID, 클라이언트 시크릿을 따로 얻을 필요가 없습니다.

연결 만들기

1. Tools > Connections를 열고 New Connection을 클릭합니다.

2. 메뉴에서 REST - Xero를 선택합니다.

3. 연결 이름을 지정합니다(예: Xero Prod).

4. Xero에 연결을 클릭하고 Xero에 로그인한 다음, PlaidCloud가 접근할 조직에 대한 액세스를 승인합니다.

5. 이제 연결 상태에 권한이 포함하는 조직 수가 표시됩니다. 조직에서 이 연결이 대상으로 하는 조직을 선택합니다.

6. Create를 클릭합니다.

참고

PlaidCloud는 Xero 토큰을 대신 새로 고치고 교체된 각 새로 고침 토큰을 저장하므로, 몇 주 동안 사용하지 않은 연결도 계속 작동합니다. 하나의 권한 부여가 여러 조직을 포함할 수 있지만 연결은 항상 정확히 하나의 조직을 대상으로 합니다. 두 번째 조직에 접근하려면 두 번째 Xero 연결을 만드십시오. Xero의 Demo Company도 다른 조직과 같은 조직이므로, 샌드박스 연결은 조직이 Demo Company를 가리키는 연결입니다.

연결 스모크 테스트

1. 워크플로에 Xero: 엔터티 가져오기 단계를 추가합니다.

2. Xero 연결을 사용할 연결로, 엔터티 유형을 Chart of Accounts로, 대상 테이블을 임시 테이블로 설정합니다.

3. 단계를 실행합니다(워크플로에서 단일 단계 실행 참조).

대상 테이블에 데이터가 채워지면 권한 부여와 조직 선택이 모두 올바른 것입니다. 오류가 발생하면 문제의 원인이 표시됩니다. 예를 들어 만료된 권한 부여, 또는 로그인이 더 이상 액세스할 수 없는 조직입니다.

데이터 가져오기

1. Xero: 엔터티 가져오기 단계를 추가하고 Xero 연결과 대상 테이블을 설정합니다.

2. 엔터티 유형을 원하는 레코드로 설정합니다. 계정과목표, 연락처, 송장, 대변 메모, 결제, 수동 분개, 은행 거래, 품목, 추적 범주, 세율, 통화 중에서 선택할 수 있습니다.

3. 선택적 필터로 가져올 범위를 좁힙니다. 상태(AUTHORISED나 PAID 같은 단일 Xero 상태), 시작 날짜와 종료 날짜(엔터티 날짜에 대한 YYYY-MM-DD 경계), 업데이트 기준일(수정 시점 기준 컷오프)이 있습니다.

4. 단계를 실행하고 대상 테이블을 확인합니다.

참고

업데이트 기준일에는 저장된 워터마크가 없습니다. PlaidCloud는 마지막 실행이 중단된 위치를 기억하지 않으므로, 증분 방식으로 가져오려면 실행할 때마다 컷오프를 직접 제공해야 합니다. 품목과 통화는 문서화된 필터가 전혀 없고, 계정과목표와 연락처는 상태는 받지만 날짜 범위는 받지 않습니다. Xero는 엔터티가 지원하지 않는 필터를 거부하므로, 단계는 잘못된 결과 집합을 반환하는 대신 오류를 보고합니다.

문서 전기

Xero: 문서 전기 단계는 모든 ERP 전기 단계가 사용하는 것과 동일한 공유 쓰기 파이프라인을 통해 ManualJournal, Invoice, Bill, Payment, CreditNote의 다섯 가지 문서 유형을 전기합니다.

1. 문서 한 건당 한 행으로 구성된 헤더 테이블을 만듭니다. 열은 ref(문서 식별자), doc_type(ManualJournal, Invoice, Bill, Payment 또는 CreditNote), posting_date와, 문서 유형에 필요한 경우 currency_id, party_id(Xero 연락처), memo, due_date입니다. Payment에는 total_amt, deposit_account_id, bank_account_id, linked_invoice_id도 필요하고, CreditNote에는 credit_note_type(판매는 기본값인 ACCRECCREDIT, 구매는 ACCPAYCREDIT)이 필요합니다. 하나의 배치에 여러 문서 유형을 섞을 수 있으며, PlaidCloud는 전기 전에 doc_type별로 분할합니다.

2. 문서 유형에 맞는 라인 테이블을 만듭니다. ref당 하나 이상의 행이 필요하며, 각 행에는 해당 ref가 있어야 합니다.

   문서 유형	라인 열
   ManualJournal	account_id, debit, credit, 추적용으로 선택적으로 class_id / department_id
   Invoice	item_id, qty, unit_price, amount
   Bill	account_id, amount
   CreditNote	item_id, qty, unit_price, amount
   Payment	linked_txn_id(라인이 적용되는 송장), amount

   tax_type과 memo는 모든 라인에서 선택 사항입니다.

3. Xero: 문서 전기 단계를 추가하고 Xero 연결, 환경(연결의 PlaidCloud 환경 중 전기에 사용할 환경), 헤더 테이블, 라인 테이블, 결과 테이블을 설정합니다.

4. 헤더 필드 및 라인 필드 탭에서 사용 중인 열 이름을 해당 필드에 매핑합니다.

5. Test Only Mode를 선택한 상태로 두고 단계를 실행합니다. PlaidCloud는 원장 클레임 없이, 아무것도 전기하지 않은 채 모든 문서를 구성하고 검사합니다.

6. 결과 테이블(문서당 한 행: ref, doc_type, natural_key, xero_id, status, message)을 검토합니다. error 행이 있으면 수정한 후 다시 검증합니다.

7. Test Only Mode 선택을 해제하고 다시 실행하여 실제로 전기합니다. 첫 번째 문서가 실패했을 때 배치를 즉시 중단하려는 경우가 아니라면 Continue posting remaining documents if one document fails를 선택한 상태로 두십시오.

전기 방식

각 문서는 제출되기 전에 PlaidCloud의 멱등성 원장에서 클레임되므로, 다시 실행해도 이미 posted에 도달한 문서는 전기되지 않습니다. 원장 키에는 문서 유형이 접두사로 붙으므로, Xero가 송장과 청구서를 같은 엔드포인트로 전기하더라도 같은 ref를 공유하는 송장과 청구서가 충돌하지 않습니다.

시간 초과나 응답 누락처럼 결과가 모호한 경우 PlaidCloud는 스탬프를 찍은 문서 번호로 Xero에 다시 조회하며, 문서가 전기 완료 상태일 때만 일치 항목을 증거로 취급합니다. Xero의 송장 및 대변 메모 번호는 고유함이 보장되지 않으므로, 초안, 무효화됨 또는 번호가 중복된 일치 항목은 이 쓰기의 결과로 기록되지 않고 격리됩니다.

기능 제한 - 실제 전기 전에 읽어 보십시오

주의

• 수동 분개와 결제는 조회할 수 없습니다. Xero에서는 수동 분개의 적요와 결제의 참조를 쿼리할 수 없으므로, 결과가 불확실한 쓰기를 PlaidCloud의 요청과 대조할 필드가 없습니다. 이러한 항목은 추측하지 않고 격리되며, Xero에서 직접 해결해야 합니다.
• 되돌리기는 수동 분개와 송장에만 적용됩니다. 수동 분개는 차변과 대변을 맞바꾼 분개로 되돌리고, 송장은 이를 반영하는 대변 메모로 되돌립니다. 청구서, 결제, 대변 메모는 Xero API에 문서화된 취소 페이로드가 없으므로 PlaidCloud는 임의로 만들지 않고 되돌리기를 거부합니다. 이러한 항목은 Xero에서 직접 수정하십시오.
• 속도 제한은 조직별로 적용됩니다. Xero는 조직당 분당 60회, 하루 5,000회 호출과 동시 호출 5건을 허용합니다. PlaidCloud는 연결별로 분당 및 동시 호출 제한을 관리하고 제한 응답이 오면 대기 후 재시도하므로, 매우 큰 배치는 그에 비례해 더 오래 걸립니다. 같은 조직에 대해 여러 Xero 단계를 한꺼번에 실행하지 말고 대규모 가져오기는 일정을 설정해 실행하십시오.

관련 문서

• Xero REST 커넥터 - 필드 참조.
• Xero: 엔터티 가져오기
• Xero: 문서 전기
• ERP 전기 이력 검토 - 모든 Xero 전기 시도와 현재 상태에 대한 상시 기록.
• 연결 만들기 및 관리