قالب‌های CSV

قاعده‌های مشترک#

• همه فایل‌ها UTF-8 هستند. جداکننده ویرگول است و نقل‌قول‌گذاری استاندارد CSV.
• ستون تاریخ روزانه YYYY-MM-DD است. ستون زمان‌دار RFC3339 است، مثل 2026-07-30T09:12:44Z.
• بعضی خروجی‌ها با BOM شروع می‌شوند تا اکسل فارسی را درست باز کند؛ در جدول هر خروجی مشخص شده است.
• هر خروجی به دارایی انتخاب‌شده و بازه تاریخ بالای صفحه محدود است و مثل هر خواندن دیگری اختیار می‌خواهد.

وارد کردن هزینه تبلیغات#

تنها فایلی که ادپیکس می‌خواند. از «مدیریت» ← «تنظیمات دارایی» ← «وارد کردن هزینه و ROAS»، یا مستقیم:

POST /api/v1/cost-import
Content-Type: text/csv

قالب خالی و یک نمونه واقعی هم آماده است: GET /api/v1/cost-import/template و همان با ?example=1. فایل نمونه دوازده هفته در سه کانال است و بدون هیچ هشداری وارد می‌شود.

ستون‌ها#

سرستون بر اساس نام تطبیق داده می‌شود، پس ترتیب ستون‌ها مهم نیست و ستون‌های اضافی نادیده گرفته می‌شوند. دو نام مستعار پذیرفته است: spend به جای cost و week یا week_ending به جای date.

خطی که با # شروع شود کامنت است و اصلا خوانده نمی‌شود — به همین دلیل قالب دانلودی با بلوک راهنمای خودش بدون دست‌کاری دوباره وارد می‌شود. سطر کاملا خالی هم رد می‌شود.

اگر ردیف اول سرستون شناخته‌شده‌ای نداشته باشد (نه نامی برای تاریخ، نه نامی برای هزینه)، فایل به ترتیب موضعی خوانده می‌شود:

date,channel,source,campaign,cost,currency,revenue

چه چیزی سطر را رد می‌کند و چه چیزی فقط هشدار است#

پاسخ، گزارش ساختاریافته کامل است:

{
  "ok": true, "total": 4983, "inserted": 4900, "updated": 80, "skipped": 3,
  "imported_from": "2025-01-05", "imported_to": "2026-07-26",
  "errors":   [ { "line": 12, "field": "cost", "code": "invalid_cost", "message": "…" } ],
  "warnings": [ { "line": 40, "field": "channel", "code": "unknown_channel", "message": "…" } ]
}

line شماره رکورد از دید تجزیه‌کننده است: خط‌های کامنت اصلا شمرده نمی‌شوند و سرستون خط شماره یک است. هر دو فهرست خطا و هشدار در هزار عضو بریده می‌شوند تا یک فایل زباله پاسخ را باد نکند.

به‌روزرسانی به جای تکرار#

کلید یکتایی ترکیب دارایی، تاریخ، کانال، منبع و کمپین است. ورود دوباره همان ترکیب، مقدارهای cost و currency و revenue را در جای خودش به‌روز می‌کند؛ سطر تکراری ساخته نمی‌شود. اگر همین ترکیب دو بار در یک فایل بیاید، آخرین سطر برنده است.

سقف اندازه#

فایل خالی پاسخ 400 می‌گیرد. مهلت واردات همگام پنج دقیقه و ناهمگام سی دقیقه است.

همین اعتبارسنجی یک مسیر JSON هم دارد: همان اندپوینت با {"rows":[…]} و همان کلیدهای ستون. رفتارش با مسیر CSV یکسان است.

خروجی گزارش‌ها#

خروجی عمومی#

GET /api/v1/export/<report>.csv

<report> یکی از channels، sources، geo، tech، overview و users است؛ نام دیگری 404 می‌گیرد. هر گزارش حداکثر ۵۰۰۰ سطر برمی‌گرداند.

users استثناست و از پایگاه تراکنشی خوانده می‌شود، با ستون‌های ثابت و حداکثر ۵۰۰۰۰ سطر:

global_user_id,email,phone,crm_client_id,first_seen_at,identified_at

خروجی پیشرفته کانال‌ها#

GET /api/v1/export/channels[?format=json]

این یکی قالب کاملی دارد: BOM، یک بلوک فراداده با #، سرستون‌های خوانا و یک سطر جمع در پایان.

# AdPix export — Channels
# Property: …
# Date range: 2026-07-01 .. 2026-07-30
# Timezone: UTC
# Generated: 2026-07-30T09:12:44Z
Channel,Channel Type,Source,Medium,Campaign,Users,Sessions,Pageviews
…
Total,,,,,128402,164991,402877

با ?format=json همان داده به‌همراه metadata، columns و totals به شکل JSON برمی‌گردد.

رویدادهای خام#

GET /api/v1/events/raw?format=csv

فایل raw-events.csv با شانزده ستون ثابت:

event_time,event_type,event_name,distinct_id,global_user_id,page_host,page_path,
ft_channel,ft_source,lt_channel,ip,geo_country,geo_region,geo_city,ua_browser,ua_os

این خروجی داده در سطح تک‌رویداد است و پشت محدودیت «داده خام» عضویت قرار دارد.

سند رضایت#

GET /api/v1/consent/export[?format=json]

فایل consent-records.csv، حداکثر ۵۰۰۰۰ رکورد:

consent_id,consent_at,action,accepted,rejected,mode,revision,config_version,locale

accepted و rejected فهرست دسته‌ها با فاصله‌اند، مثل necessary statistics. آدرس IP در این فایل نیست — فقط شکل درهم‌سازی‌شده‌اش ذخیره می‌شود و صادر نمی‌گردد.

خروجی مدل‌های بازاریابی#

مارکتینگ میکس#

GET /api/v1/mmm/runs/{id}/export.csv

فایل mmm-<هشت کاراکتر اول شناسه>.csv با BOM. اول یک بلوک خلاصه به شکل کلید و مقدار، بعد یک سطر خالی، بعد جدول کانال‌ها:

AdPix — Marketing Mix Model
run_id,…
target,revenue
trust_tier,directional
n_weeks,104
n_channels,5
generated,2026-07-30T09:12:44Z

channel,family,identified,contribution,contribution_share,roi,roi_lo,roi_hi,mroi,cpa

اعداد با چهار رقم اعشار نوشته می‌شوند و مقدار نامعلوم سلول خالی می‌ماند.

لیفت#

GET /api/v1/lift/tests/{id}/export.csv

فایل lift-<هشت کاراکتر اول شناسه>.csv. چند سطر خلاصه کلید و مقدار، یک سطر خالی، و بعد سری روزانه:

day,observed,counterfactual,cf_lo,cf_hi,lift,organic

اعداد با دو رقم اعشار نوشته می‌شوند.

خروجی محافظت در برابر تقلب#

پرونده اعتراض یک موجودیت#

GET /api/v1/integrity/entities/{entity_id}/export.csv

فایل integrity-<موجودیت>.csv با BOM و بلوک فراداده #. ساختارش سه بلوک پشت سر هم است، جدا شده با سطر خالی: خلاصه به شکل Field,Value، بعد فهرست Reasons، بعد جدول Detector,Score.

ادعای بازپرداخت#

GET /api/v1/integrity/evidence/refund.csv

فایل adpix-fraud-refund-claim.csv — همان چیزی که به پلتفرم تبلیغاتی می‌دهید:

asn,asn_org,network_type,channel,severity,flagged_sessions,window_from,window_to,
estimated_wasted,currency,reasons,sample_ips,evidence_hash,chain_verified

reasons با ; و sample_ips با فاصله جدا می‌شوند. estimated_wasted با دو رقم اعشار است. evidence_hash و chain_verified از دفتر شواهد زنجیره‌ای می‌آیند و همان چیزی هستند که ادعا را قابل راستی‌آزمایی می‌کنند.

فهرست‌های مسدودسازی#

سه خروجی، برای سه مقصد متفاوت. هر سه فقط شبکه‌هایی را می‌آورند که در بازه انتخاب‌شده «تاییدشده» یا «محتمل» علامت خورده‌اند.

فایل گوگل دقیقا قالبی است که «حذف آدرس IP» در گوگل ادز می‌پذیرد: هر سطر یک a.b.c.*، پرترافیک‌ترین‌ها اول، و حداکثر ۵۰۰ سطر — چون خود گوگل ادز بیشتر از ۵۰۰ حذف در هر کمپین نمی‌پذیرد. اگر شبکه‌های علامت‌خورده بیشتر از این باشند، هدر پاسخ X-AdPix-Blocklist-Truncated تعداد جامانده را می‌گوید.

فایل عمومی برای فایروال، Cloudflare یا CDN است و به‌جای فقط IP، شبکه و شماره سیستم خودگردان را هم می‌آورد. سقفش با ?cap= تنظیم می‌شود، پیش‌فرض ۱۰۰۰ و بین ۱ تا ۵۰۰۰ محدود می‌شود.

فایل متا فهرست IP نیست: متا حذف IP ندارد، پس این خروجی در سطح شبکه توصیه می‌دهد — همان چیزی که با کنترل‌های جایگاه و مخاطب، یا با فیلتر سمت سرور روی Conversions API اعمال می‌کنید. ستون recommendation همین را در هر سطر تکرار می‌کند.

قالب‌های دانلودی#

قالب خالی را می‌شود بدون هیچ ویرایشی دوباره وارد کرد؛ بلوک راهنمایش با # شروع می‌شود و تجزیه‌کننده آن را نمی‌بیند.

پرسش‌های پرتکرار#

مطالب مرتبط#