Отчеты по платежам

Обзор

В этом документе содержится подробная информация о содержании таких отчетов, их формате и API для их запроса.

• Скачивание ежедневных отчетов
• Содержание отчетов
• Когда следует запрашивать отчеты
• Скачивание ежедневных отчетов с помощью API
• Формат ежедневных отчетов
• Заголовок отчета
• Заголовок раздела
• Заголовок колонки
• Данные раздела
• Нижний колонтитул раздела
• Нижний колонтитул отчета
• Примеры отчетов

Скачивание ежедневных отчетов

Чтобы скачать ежедневный отчет для ваших приложений, администратора компании может перейти на страницу настроек компании, выбрать нужную компанию и открыть вкладку "Отчеты". На этой странице можно выбрать дату отчета в календаре, а также тип отчета в раскрывающемся меню.

Кроме того, перейти в настройки компании можно следующими способами:

• игры для Холста — Веб-платежи > Веб-платежи > Компания > Просмотреть/редактировать;
• моментальные игры — Покупки в приложении > Аккаунт > Перейти в настройки компании.

Выберите нужные параметры и нажмите Скачать, чтобы скачать ежедневный отчет для своей компании.

Содержание отчетов

Каждый отчет охватывает одни сутки с 00:00 до 23:59:59 по американскому тихоокеанскому времени (UTC-8/UTC-7) и содержит информацию о транзакциях с выплатой одной и той же компании, проведенных во всех приложениях в этот день.

Для каждого дня можно запросить отчеты двух разных типов:

• Отчет detail содержит одну запись для каждой отдельной транзакции, т. е. для каждой продажи, возврата и т. п. В подробных отчетах учитывается оплата с точки зрения Facebook.
• Отчет digest представляет собой сводку всех транзакций определенного типа в том или ином приложении.

Отчеты для моментальных игр аналогичны, но называются иначе:

• Отчет ig_detail содержит одну запись для каждой отдельной транзакции, т. е. для каждой продажи, возврата и т. п.
• Отчет ig_digest представляет собой сводку всех транзакций определенного типа в той или иной моментальной игре.

В настоящее время отчеты по платежам состоят из двух разделов, однако при написании синтаксического анализатора учитывайте, что формат отчетов может расширяться.

• Один раздел, credits_digest или credits_detail (в зависимости от того, какой отчет вы читаете), содержит все транзакции с использованием функции купонов Facebook, а также все внутриигровые покупки, сделанные через действие buy_item в диалоге платежа. Этот раздел упразднен, поскольку разработчики больше не получают платежи в купонах Facebook.

• Другой раздел, payment_digest или payment_detail, содержит транзакции с использованием функции платежей на Facebook, а именно Подписки и Платежи.

Когда следует запрашивать отчеты

Мы создаем новые отчеты раз в день. Они становятся доступны в 12 часов дня по тихоокеанскому времени (UTC-8/UTC-7), поэтому самый последний отчет из доступных на момент запроса, как правило, содержит информацию за предыдущий день. Для моментальных игр действует задержка в два дня.

Скачивание ежедневных отчетов с помощью API

Отчеты по платежам доступны через сетевой API, поэтому можно запросить как сводный, так и очень подробный отчет по транзакциям за выбранный день.

Получение отчетов происходит в 3 этапа:

1. Получение ID и секрета компании.
2. Получение Company access_token.
3. Скачивание файлов отчетов.

Получение ID и секрета компании

Прежде чем продолжить, убедитесь, что вы включили функцию платежей в приложении, а также настроили получение платежей для компании.

Если это так, вы увидите ID и секрет своей компании на странице настроек компании (вкладка Идентификационные данные).

Для одной компании требуется всего одна пара из ID и секрета. Она используется во всех приложениях этой компании. Эти идентификационные данные потребуются, чтобы получить access_token, необходимый для скачивания ежедневных отчетов по вашим приложениям.

Получение Company Access Token

Company Access Token позволяет получить доступ к отчетам для всех приложений, связанных с компанией, от имени которой выдан маркер. Чтобы получить его, отправьте запрос GET к конечной точке

https://graph.facebook.com/oauth/access_token?

и укажите следующие параметры:

Срок действия этого маркера истекает только в случае сброса секрета компании, поэтому его нужно хранить и использовать повторно, а не генерировать заново при каждом запросе отчетов.

Пример запроса access_token компании

Пример запроса:

https://graph.facebook.com/oauth/access_token?
                                 client_id=COMPANY_ID&
                                 client_secret=COMPANY_SECRET&
                                 grant_type=client_credentials

Образец ответа от Facebook:

access_token=230001349987723|aBc_dEFaEUZberrtkrp8pbtwXyZ

Скачивание ежедневных файлов

Получив access_token компании, вы можете использовать его для запроса файлов ежедневных отчетов по всем приложениям вашей компании. Как упоминалось выше, можно сгенерировать отчеты двух типов:

• Отчет digest содержит по строке данных для каждой пары "транзакция — тип приложения" и представляет собой сводку продаж, возвратов и других событий, связанных с транзакциями, для каждого приложения.
• Отчет detail, как можно понять из его названия, содержит по строке для каждой отдельной транзакции.

Чтобы скачать файлы отчетов за определенный день, отправьте запрос GET к конечной точке

https://paymentreports.facebook.com/COMPANY_ID/report?

и укажите следующие параметры:

Как упоминалось выше, запросить отчет date за текущий день нельзя. Отчеты за текущий день становятся доступны на следующий день после 8:00 по американскому тихоокеанскому времени (UTC-7/UTC-8).

Примеры запросов ежедневных отчетов

Пример запроса ежедневного отчета detail от разработчика:

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&
                                          type=detail&                                     access_token=234599349987627|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

В ответ на такой запрос вы получите файл с именем 23459934998762_detail_2012-05-15.csv.zip.

Пример запроса отчета digest от разработчика:

wget "https://paymentreports.facebook.com/23459934998762/report?
                                          date=2012-05-15&
                                          type=digest&
                                          access_token=23459934998762|aBc_dEFaEUZbqpatkrp8pbtwXyZ"

В ответ на такой запрос вы получите файл с именем 23459934998762_digest_2012-05-15.csv.zip.

Формат отчетов

Все отчеты имеют единую структуру:

• текстовые файлы со значениями, разделенными запятой (CSV);
• разделители строк в формате Unix "\n" (новая строка);
• поля, содержащие запятые, заключаются в двойные кавычки для удобства импорта в Excel;
• первая колонка каждой строки содержит код типа строки, который определяет, как будут интерпретироваться остальные колонки;
• отчеты содержат строки 6 типов, со следующей структурой:
• один заголовок отчета (код типа RH);
• один или несколько разделов, каждый из которых содержит:
• один заголовок раздела (SH);
• один заголовок колонки (CH);
• некоторое (в том числе нулевое) количество строк данных раздела (SD);
• один нижний колонтитул раздела (SF);
• один нижний колонтитул отчета (RF).

Эту структуру можно визуализировать следующим образом:

RH,     ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  SH,   ...
    CH, ...
    SD, ...
    [More section data rows]
  SF,   ...

  [Possibly more sections]

RF,     ...

Примечание. Отступы и пробелы в примере выше добавлены исключительно для удобства чтения. В настоящих отчетах отступов нет, а пробелы употребляются, только когда они содержатся в данных полей.

Примеры с заполненными полями можно найти в разделе с примерами файлов в конце этого документа.

Заголовок отчета (RH)

Первая строка — это заголовок отчета. Она содержит данные, которые относятся ко всем последующим строкам вплоть до нижнего колонтитула отчета, обозначающего конец отчета. Строки RH содержат следующие поля:

Пример заголовка отчета

Пример строки:

RH,213030545409781,daily_detail,2011-11-21 00:00:00 PST,2011-11-21 23:59:59 PST,1

Как следует читать этот пример строки:

Заголовок раздела (SH)

Все строки между заголовком и нижним колонтитулом отчета являются частями раздела. Каждый раздел в отчете начинается с заголовка и заканчивается нижним колонтитулом раздела. Строки SH содержат следующие поля:

Пример заголовка раздела

Пример строки:

SH,213030545409781,payment_detail

Как следует читать этот пример строки:

Заголовок колонки (CH)

После каждого заголовка раздела следует заголовок колонки с именами полей для строк данных этого раздела. Разделы разных типов содержат разные поля. Важно ознакомиться со строками заголовков колонок, чтобы знать названия полей в каждом разделе. Формат отчета можно легко расширить. Для этого достаточно обновить его описание, изменив порядок колонок или спецификацию разделов таким образом. По этой причине любое решение для синтаксического анализа с жестко закодированной структурой отчетов может стать недействительным.

Примеры заголовков колонок

Пример строки CH из раздела payment_detail:

CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country

Пример строки CH из раздела payment_digest:

CH,app_id,app_name,payment_type,product_type,recv_currency,
,fx_batch_id,fx_rate,settle_currency,settle_amount

Данные раздела (SD)

За заголовком колонки раздела следует некоторое (может быть нулевое) количество строк section data, названия полей которых берутся из строки CH. Содержание строк зависит от типа раздела: в разделах detail каждая строка представляет собой отдельную транзакцию, а в разделах digest каждая строка содержит сумму всех транзакций определенного типа в том или ином приложении (например, "все продажи для ID приложения 276999562313463", "все возвраты в японских иенах за отмену подписки для ID приложения 276899562313544"). В настоящее время существует 4 типа разделов. Они описаны ниже.

Примеры данных разделов

Строка SDpayment_detail

Поля:

Пример строки для подписки:

SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US,0.99

Как читать пример строки для подписки:

Пример строки для платежей:

SD,480369938658210,S,P,362736900505327,2013-06-12 16:33:52 PDT,USD,1,6E5D989082A04A68AA801DB17A30721A,1,USD,QQ6C7XaxeMyCW4RdZXFGwKTQM1IkMBIOpeWtFFJelHUdSC9NaeYlBXEMJd3LO17k,US,0.09

Как следует читать пример строки для платежа:

Строка SDpayment_digest

Поля:

Пример строки для подписки:

SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

Как читать пример строки для подписки:

Пример строки для платежей:

SD,900000000000009,Game9,S,P,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0,9.99

Как следует читать пример строки для платежа:

Нижний колонтитул раздела (SF)

Каждый раздел заканчивается строкой нижнего колонтитула раздела, за которым может следовать новый раздел со строкой SH или строка нижнего колонтитула отчета, обозначающего конец отчета. Единственная колонка данных, идущая за полем типа, содержит:

Пример нижнего колонтитула раздела

Пример строки:

SF,7

Как следует читать этот пример строки:

Нижний колонтитул отчета (RF)

Отчет заканчивается строкой нижнего колонтитула отчета. Она должна быть последней в файле. Эта строка содержит 2 части сводных данных, следующих после колонки ее типа:

Пример нижнего колонтитула отчета

Пример строки:

RF,2,7

Как следует читать этот пример строки:

Примеры отчетов

Эти примеры следует читать в соответствии с инструкциями выше. Кроме того, учтите следующее:

• строки вверху каждого примера отчета — это обычные заголовки отчетов;
• следующий блок текста содержит разделы credits_detail или _digest;
• блок текста после него (непосредственно над нижним колонтитулом) содержит разделы payment_detail или payment_digest;
• строки внизу примера — это обычные нижние колонтитулы отчетов.

Пример отчета detail

RH,10808080808080808,daily_detail,2012-04-24 00:00:00 PDT,2012-04-24 23:59:59 PDT,1

SH,10808080808080808,credits_detail
CH,app_id,txn_type,txn_id,order_id,txn_time,value,credits

SH,10808080808080808,payment_detail
CH,app_id,payment_type,product_type,payment_id,time_completed,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,reference_id,tax_country
SD,266989143414,S,S,267668373345994,2012-07-22 00:07:23 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000007,US
SD,266989143414,S,S,272014936246430,2012-07-22 00:08:18 PDT,USD,21.09,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000008,US
SD,266989143414,S,S,272990136150221,2012-07-22 00:09:18  PDT,USD,22.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000009,CY
SD,266989143414,S,S,278092248972451,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US 
SD,266989143414,S,P,376727629107629,2012-07-22 00:08:34 PDT,USD,19.99,123456789ABCDEF00123456789ABCDEF,1.0000000000,USD,20000000010,US 
SF,4 

RF,2,13

Пример отчета digest

RH,108080808080808,daily_digest,2012-04-25 00:00:00 PDT,2012-04-25 23:59:59 PDT,1

SH,108080808080808,credits_digest
CH,app_id,app_name,txn_type,value,credits

SH,108080808080808,payment_digest
CH,app_id,app_name,payment_type,product_type,recv_currency,recv_amount,fx_batch_id,fx_rate,settle_currency,settle_amount
SD,200000000000002,Game2,S,S,CNY,5000.0,FXBATCHID1,0.2,USD,1000.0
SD,200000000000002,Game2,R,S,CNY,2000.0,FXBATCHID1,0.2,USD,400.0
SD,200000000000002,Game2,S,P,CNY,1000.0,FXBATCHID1,0.2,USD,200.0
SF,2

RF,2,5

Расчеты

Для расчета чистого дохода разработчика используйте следующую информацию.

Покупки через Facebook Pay

Они соответствуют транзакциям в отчете ig_detail, параметр platform которых имеет значение "F", или всем транзакциям в отчете detail.

Предположим, что значение tax_country, равное "US", означает, что покупка не облагается налогом, и расчет производится по следующей формуле:
net_developer_revenue = (recv_amount - tax_amount) * fx_rate * rev_share

В противном случае предположим, что покупка делается с учетом налогов и расчет производится по следующей формуле:
net_developer_revenue = (recv_amount * fx_rate) * rev_share - (tax_amount * fx_rate)

Покупки через Google Play

Они соответствуют транзакциям в отчете ig_detail, параметр platform которых имеет значение "G".

Расчет производится по следующей формуле:
net_developer_revenue = recv_amount * fx_rate

Примечание: это лишь приблизительная оценка, основанная на данных о выплатах. До выплаты могут взиматься дополнительные сборы. В будущем обновлении отчетов этот расчет станет более точным и простым.