# Como funciona a API de relatórios Programe seu acesso aos relatórios financeiros da Stripe para automatizar o trabalho de reconciliação. > Agora você pode enviar automaticamente seus dados da Stripe e relatórios para Snowflake ou Amazon Redshift em alguns cliques com o Stripe Data Pipeline. [Saiba mais](https://stripe.com/data-pipeline). Os [relatórios financeiros](https://dashboard.stripe.com/reports) 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](https://docs.stripe.com/reports/report-types/balance.md) - [Reconciliação de repasses](https://docs.stripe.com/reports/report-types/payout-reconciliation.md) - [Tipo de relatório de tarifas](https://docs.stripe.com/reports/report-types/fees.md) - [Tax](https://docs.stripe.com/reports/report-types/tax.md) - [Plataformas Connect](https://docs.stripe.com/reports/report-types/connect.md) > #### Os formatos monetários do CSV e da API são diferentes > > Os relatórios CSV formatam valores monetários usando as *maiores* unidades monetárias como número decimal. Por exemplo, o CSV formata 10 USD como dólares e centavos (`10.00`). Na API da Stripe, isso é diferente: você especifica valores na *menor* unidade (centavos de dólar) como um número inteiro. Na API, você formata 10 USD como centavos (`1000`). ### 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 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](https://www.iana.org/time-zones) 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](https://docs.stripe.com/reports/options.md#data-availability) 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](https://docs.stripe.com/api.md#retrieve_reporting_report_type) o objeto `ReportType` de interesse. Por exemplo, o relatório de **Resumo de Saldo** tem o ID`balance.summary.1`, então você pode recuperar o objeto da seguinte forma: #### curl ```bash curl https://api.stripe.com/v1/reporting/report_types/balance.summary.1 \ -u <>: ``` 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: ```json { "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 um[Webhook configurado](https://docs.stripe.com/webhooks.md#register-webhook) 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 os[endpoints do webhook Connect](https://docs.stripe.com/connect/webhooks.md). Depois de receber o evento, você pode executar o relatório. Para obter detalhes, consulte o[padrão de integração recomendado](https://docs.stripe.com/reports/api.md#integration-pattern). ## 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](https://docs.stripe.com/reports/api.md#report-types) para ver a lista de parâmetros obrigatórios e opcionais para esse tipo. Por exemplo, você pode [criar](https://docs.stripe.com/api/reporting/report_run/create.md) um relatório de **Variação do saldo a partir de resumo de atividade** para abril de 2020 da seguinte forma: #### curl ```bash curl https://api.stripe.com/v1/reporting/report_runs \ -u <>: \ -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"`: ```json { "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](https://docs.stripe.com/api/reporting/report_run/retrieve.md) a execução do relatório acima após a conclusão, a resposta seria: ```json { "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 ```bash curl https://files.stripe.com/v1/files/file_xs8vrJzC/contents \ -u <>: ``` ### 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. > Os relatórios executados no Dashboard não acionam os eventos de webhook de relatórios. ## 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. > Se você usar [sandboxes](https://docs.stripe.com/sandboxes.md), não receberá eventos `reporting.report_type.updated`. 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). 1. 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](https://docs.stripe.com/api/reporting/report_run/create.md). A resposta conterá um novo objeto `ReportRun`, inicializado com `status=pending`. 1. 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`.) 1. 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.