从PayPal SFTP切换至API获取争议数据的技术适配问询

一、API字段与CSV列的映射方案 #

直接对照PayPal Disputes API的返回结构，结合你提到的CSV列，整理核心映射关系（基于v1/disputes端点返回数据）：

• buyer_comments: 从dispute.messages数组中筛选role=BUYER的message.content字段
• buyer_email_address: dispute.buyer.email_address
• buyer_first_name: dispute.buyer.name.given_name
• buyer_last_name: dispute.buyer.name.surname
• case_filing_date: dispute.create_time（需转换为CSV对应的日期格式）
• case_id: dispute.dispute_id
• case_reason: dispute.reason.category
• case_status: dispute.status
• case_type: dispute.type
• chargeback_reason_code: dispute.reason.code
• disputed_amount: dispute.amount.value
• disputed_currency: dispute.amount.currency_code
• disputed_transaction_id: dispute.transaction_id
• final_outcome_reason: dispute.outcome.reason（仅争议结案时存在）
• invoice_id: dispute.invoice_id
• money_movement: dispute.money_movement_status
• response_due_date: dispute.response_deadline
• seller_protection: dispute.seller_protection.eligible（转换为CSV中对应的"Yes"/"No"格式）
• seller_protection_currency: dispute.seller_protection.amount.currency_code（仅符合卖家保护时存在）
• seller_protection_payout_amount: dispute.seller_protection.amount.value（仅符合卖家保护时存在）
• settlement_type: dispute.settlement.type（仅争议已结算时存在）
• transaction_id: dispute.transaction_id（若CSV中该字段与disputed_transaction_id有差异，需检查related_transactions关联字段）
• transaction_initiation_date: 关联交易的transaction.create_time（需通过/v1/payments/transactions/{transaction_id}接口补充获取）
• outcome: dispute.outcome.status

若部分字段在disputes端点无法找到，可结合disputes/{dispute_id}/info端点补充数据，比如更详细的卖家保护细则或交易关联信息。

二、还原SFTP报告的数据转换逻辑 #

1. 样本数据对比法：
   选取几个已知case_id的争议，同时导出SFTP CSV数据和API原始返回值，逐字段对比差异：

   • 日期格式：SFTP通常用MM/DD/YYYY HH:MM格式，API返回ISO 8601标准格式（YYYY-MM-DDTHH:MM:SSZ），需做格式转换
   • 枚举值映射：比如SFTP中case_status的"Resolved"对应API的"RESOLVED"，seller_protection的"Yes"对应API的true，整理这类映射表统一转换
   • 金额处理：API返回金额为纯数字字符串（如"100.00"），SFTP可能带货币符号或千分位，需统一格式化
   • 内容截取：比如buyer_comments，SFTP可能仅保留买家第一条评论，而API返回所有买家消息，需按时间取第一条或按需合并

2. 查阅官方报告文档：
   PayPal的Merchant SFTP报告文档中会明确标注每个字段的生成规则，包括原始数据来源、枚举值转换规则、日期格式化逻辑等，这些文档可直接帮你还原SFTP报告的转换逻辑。

3. 特殊字段处理：

   • 空值统一：比如final_outcome_reason仅在争议结案时存在，若CSV中该字段为空，需对应处理API无此值的场景
   • 关联数据补充：transaction_initiation_date这类依赖交易详情的字段，需额外调用交易接口获取并匹配

内容的提问来源于stack exchange，提问作者RokasMMM