Como funciona a API de relatórios

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
• Tipo de relatório de tarifas
• 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 umReportType com um parâmetro de fuso horário. Para isso, crie um objeto ReportRun e forneça o nome desejado do fuso horário do banco de dados TZ. O parâmetro fuso horário é opcional e usa como padrão UTC se não for fornecido. Veja o Banco de Dados de Fuso Horário IANA para uma lista de valores válidos de fusos horários.
• 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 determinar automaticamente o intervalo de tempo dos dados disponíveis para um dado tipo de relatório,recuperar o objeto ReportType de interesse. Por exemplo, o relatório de Resumo de Saldo tem o IDbalance.summary.1, então você pode recuperar o objeto da seguinte forma:

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

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

Quando um tipo de relatório tem novos dados disponíveis, a Stripe publica um evento reporting.report_type.updated com o objeto ReportType. Para acessar esses eventos, você deve ter umWebhook configurado que seleciona explicitamente para receber eventos reporting.report_type.updated; webhooks configurados para ‘todos os eventos’ não os recebem.

Para reduzir o tráfego de Webhook, a Stripe não envia esses eventos para osendpoints do webhook Connect. Depois de receber o evento, você pode executar o relatório. Para obter detalhes, consulte opadrão de integração recomendado.

Crie e acesse execuções de relatórios

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_VePHdqKTYQjKNInc7u56JBrQ
: \
  -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_VePHdqKTYQjKNInc7u56JBrQ
:

Notificações de execução de relatórios

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ões automatizados de integração de relatórios

Configure um webhook que receba explicitamente eventos reporting.report_type.atualizado. Webhooks configurados para ouvir todos os eventos 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.

O Stripe acompanha a execução paralela de relatórios por conta de usuário. Para manter a estabilidade da infraestrutura e oferecer desempenho consistente a todos os clientes, podemos restringir novas solicitações quando muitos relatórios estiverem em execução simultaneamente. Caso receba uma resposta de erro indicando limitação de taxa (HTTP 429), aguarde a finalização de algumas tarefas antes de submeter novas requisições.