Executar um relatório da API

Os relatórios financeiros no Dashboard fornecem relatórios que podem ser baixados em formato CSV para uma variedade de tarefas de contabilidade e reconciliação. Esses relatórios também estão disponíveis pela API, para que você possa agendar a execução automática de relatórios ou executá-los sempre que precisar dos arquivos de relatório para finalidades contábeis.

Tipos de relatório

Cada relatório financeiro no Dashboard fornece vários downloads de CSV diferentes. Todos os downloads disponíveis para os relatórios a seguir também estão disponíveis pela API:

• Saldo
• Reconciliação de repasses
• Tax
• Plataformas Connect

Parâmetros de execução

Cada relatório tem parâmetros obrigatórios e opcionais que você informa quando cria uma execução de relatório. Considere o seguinte ao executar relatórios:

• Praticamente todos os tipos de relatório exigem os parâmetros de execução interval_start (inclusive) e interval_end (exclusive) como carimbos de data e hora Unix.
• Cada recurso de tipo de relatório correspondente tem os campos data_available_start e data_available_end. A API retorna um erro de solicitação inválida (código de status 400) se a execução não cumprir as seguintes restrições:
  • Os valores interval_start e interval_end precisam estar entre data_available_start e data_available_end (inclusive).
  • O valor interval_start deve ser anterior (e não igual a) interval_end.
• Você só pode baixar um relatório em um fuso horário para um ReportType com um parâmetro timezone. Para fazer isso, crie um objeto ReportRun e informe o nome do fuso horário desejado do banco de dados TZ. O parâmetro timezone é opcional e se não for informado, UTC será definido como padrão. Consulte uma lista de valores de fuso horário Banco de dados de fuso horário IANA para obter uma lista de valores de fuso horário válidos.
• Os parâmetros opcionais currency e report_category filtram resultados para apenas essas linhas correspondentes aos valores informados.
• Os relatórios retornam um conjunto padrão de colunas, mas a maioria dos relatórios permite personalizar a seleção e a ordem das colunas na saída ao incluir o parâmetro opcional columns com uma lista de nomes de colunas.

Disponibilidade de dados

A Stripe prepara os dados para os relatórios duas vezes por dia. A página Opções de relatórios mostra detalhes sobre o tempo de processamento e a disponibilidade de dados para cada relatório.

Para saber automaticamente o período de dados disponíveis para um tipo de relatório, acesse o objeto ReportType em questão. Por exemplo, o relatório Resumo do saldo tem o ID balance.summary.1, de forma que você pode acessar o objeto assim:

curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

No exemplo de resposta abaixo, os campos data_available_start e data_available_end refletem todoo intervalo de horários válidos para esse tipo de relatório. No entanto, é mais comum solicitar relatórios de um intervalo menor desse período:

{
  "id": "balance.summary.1",
  "name": "Balance summary",
  "version": "1",
  "object": "reporting.report_type",
  "data_available_start": 1519862400,
  "data_available_end": 1517356800,
  "updated": 1517382720,
}

Carimbos de data e hora, como date_available_start, são medidos em segundos desde a época do Unix. Por exemplo, 1519862400 representa o carimbo de data e 2018-03-01 00:00.

Novas notificações de dados

Assim que um tipo de relatório tem novos dados disponíveis, a Stripe publica um evento reporting.report_type.updated com o objeto ReportType atualizado. Para acessar esses eventos, você precisa ter um webhook configurado que opte explicitamente por receber eventos reporting.report_type.updated; webhooks que escutam “all events” não os receberão. Após receber esse evento, você poderá executar o relatório. Para obter mais informações, consulte o padrão de integração recomendado.

Criar e acessar relatórios executados

O objeto de API ReportRun representa uma instância de um ReportType gerado com parâmetros específicos. Revise a documentação do tipo de relatório para ver a lista de parâmetros obrigatórios e opcionais para esse tipo. Por exemplo, você pode criar um relatório de Variação do saldo a partir de resumo de atividade para abril de 2020 da seguinte forma:

curl https://api.stripe.com/v1/reporting/report_runs \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "report_type"="balance_change_from_activity.itemized.3" \
  -d "parameters[interval_start]"=1577865600 \
  -d "parameters[interval_end]"=1580544000 \
  -d "parameters[timezone]"="America/Los_Angeles" \
  -d "parameters[columns][]"="created" \
  -d "parameters[columns][]"="reporting_category" \
  -d "parameters[columns][]"="net"

# Timestamps are for 2020-01-01 00:00 PST and 2020-02-01 00:00 PST.
# The columns parameter is optional. A default set of columns will be provided if you don't specify a value.
# Note that a live-mode API key is required.

Quando for criado pela primeira vez, o objeto aparece com status="pending":

{
  "id": "frr_123",
  "object": "reporting.report_run",
  "livemode": true,
  "report_type": "balance_change_from_activity.itemized.3",
  "parameters": {
    "columns": [ "created", "reporting_category", "net" ],
    "interval_start": 1577865600,
    "interval_end": 1580544000,
    "timezone": "America/Los_Angeles"
  },
  "created": 1580832900,
  "status": "pending",
  "result": null
}

Quando a execução é concluída, a Stripe atualiza o objeto, e o status passa a ser succeeded. Além disso, o objeto tem um objeto result aninhado com um URL que pode ser usado para acessar o arquivo com a chave de API. Por exemplo, se você desejasse recuperar a execução do relatório acima após a conclusão, a resposta seria:

{
  "id": "frr_123",
  "object": "reporting.report_run",
  "livemode": true,
  "report_type": "balance_change_from_activity.itemized.3",
  "parameters": {
    "columns": [ "created", "reporting_category", "net" ],
    "interval_start": 1577865600,
    "interval_end": 1580544000,
    "timezone": "America/Los_Angeles"
  },
  "created": 1580832900,
  "status": "succeeded",
  "succeeded_at": 1580832960,
  "result": {
    "id": "file_xs8vrJzC",
    "object": "file",
    "url": "https://files.stripe.com/v1/files/file_xs8vrJzC/contents",
    "created": 1580832960,
    "purpose": "report_run",
    "size": 53075,
    "type": "csv"
  }
}

Para recuperar os conteúdos do arquivo, use sua chave de API para acessar o arquivo especificado por result.url:

curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

Notificação de conclusão de execução do relatório

A maioria das execuções é concluída em alguns minutos. No entanto, algumas execuções podem demorar, dependendo do tamanho do seu conjunto de dados total e do intervalo de tempo abrangido pelo seu relatório.

Quando a execução de um relatório solicitada for concluída, a Stripe enviará um destes dois webhooks:

• Um webhook reporting.report_run.succeeded será enviado se a execução for concluída com êxito.
• Um webhook reporting.report_run.failed será enviado se a execução falhar. (Isso deve ser raro, mas recomendamos que as integrações sejam preparadas para tratar esse caso da mesma maneira que obter uma resposta 500.)

Em ambos os casos, o conteúdo do webhook inclui o objeto ReportRun atualizado, que inclui o status succeeded ou failed, respectivamente.

Padrão de integração recomendado para relatórios automatizados

Configure um webhook que explicitamente opte por receber eventos reporting.report_type.updated; webhooks que escutam ‘all events’ não os receberão.

1. Um webhook reporting.report_type.updated é enviado assim que os dados de um novo dia são disponibilizados para um determinado tipo de relatório. O conteúdo inclui o objeto ReportType atualizado. Normalmente, você receberá 20 a 30 webhooks por dia, dois para cada tipo de relatório (diferentes usuários são qualificados para relatórios diferentes).
2. Quando receber o webhook reporting.report_type.updated para o tipo de relatório e o intervalo de disponibilidade de dados desejados, crie uma execução de relatório. A resposta conterá um novo objeto ReportRun, inicializado com status=pending.
3. Quando a execução for concluída, um webhook reporting.report_run.succeeded é enviado. Este webhook inclui o campo aninhado result.url. (Como mencionado acima, no raro caso de uma falha, enviaremos um evento reporting.report_run.failed.)
4. Acesse os conteúdos do arquivo em result.url, usando sua chave de API.