# Como funciona a API de relatórios Acesse automaticamente os relatórios financeiros da Stripe para automatizar seu fluxo 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 A Stripe publica eventos `reporting.report_type.updated` com o objeto `ReportType` atualizado duas vezes por dia (a 0h00 e 12h00 UTC). Para acessar esses eventos, você precisa ter um [webhook configurado](https://docs.stripe.com/webhooks.md#register-webhook) que receba explicitamente eventos `reporting.report_type.updated`. Webhooks que escutam “todos os eventos” não os recebem. Como os dados do relatório podem ser atualizados com mais frequência do que os eventos do Webhook são enviados, o valor `data_available_end` no `ReportType` pode ser posterior ao valor na carga útil do evento mais recente. Para verificar os últimos dados disponíveis entre as notificações do Webhook, execute uma solicitação GET no tipo de relatório. 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. # 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.