# Listar declarações de imposto de renda

## ▶️ Uso

Com o método List Tax Returns, você pode:

1. Listar declarações de imposto relacionadas a um link.id específico (usando o parâmetro de consulta link).
2. Obter os detalhes de um tax-return.id específico (usando o parâmetro de consulta id).
3. [Não Recomendado] Listar todas as declarações de imposto relacionadas à sua conta Belvo (sem usar nenhum parâmetro de consulta).

## 📖 Paginação

Este método retorna uma resposta paginada (padrão: 100 itens por página). Você pode usar o parâmetro de consulta page_size para aumentar o número de itens retornados até um máximo de 1000 itens. Você pode usar o parâmetro de consulta page para navegar pelos resultados. Para mais detalhes sobre como navegar pelas respostas paginadas da Belvo, consulte nosso artigo Dicas de Paginação.

## 🔦 Filtrando Respostas

Consulte a lista de consultas abaixo para ver uma lista de campos pelos quais você pode filtrar suas respostas. Para mais informações sobre como usar filtros, veja nosso artigo Filtrando respostas.

## 🔔 Múltiplos Esquemas

Como um link pode ter declarações de imposto anuais e mensais, a resposta incluirá uma mistura desses dois tipos de declarações de imposto (e, portanto, diferentes esquemas).

Endpoint: GET /api/tax-returns/
Version: 1.223.0
Security: basicAuth

## Query parameters:

  - `link` (string)
    O link.id pelo qual você deseja filtrar.

ℹ️ Recomendamos fortemente adicionar o filtro link.id para melhorar seu desempenho.
    Example: "8848bd0c-9c7e-4f53-a732-ec896b11d4c4"

  - `page_size` (integer)
    Indica quantos resultados retornar por página. Por padrão, retornamos 100 resultados por página.

ℹ️ O número mínimo de resultados retornados por página é 1 e o máximo é 1000. Se você inserir um valor maior que 1000, nossa API usará o valor máximo por padrão (1000).
    Example: 100

  - `page` (integer)
    Um número de página dentro do conjunto de resultados paginados.
    Example: 1

  - `omit` (string)
    Omitir certos campos de serem retornados na resposta. Para mais informações, consulte nosso artigo Filtrando respostas no DevPortal.

  - `fields` (string)
    Retorne apenas os campos especificados na resposta. Para mais informações, consulte nosso artigo no DevPortal Filtrando respostas.

  - `link__in` (array)
    Retorne resultados apenas para esses link.ids.
    Example: ["5722d0ba-69d7-42dc-8ff5-33767b83c5d6"]

  - `id` (string)
    Retorne informações apenas para este recurso id.
    Example: "24ccab1d-3a86-4136-a6eb-e04bf52b356f"

  - `id__in` (array)
    Retorne informações para esses ids de recurso.
    Example: ["6b3dea0f-be29-49d1-aabe-1a6d588642e6"]

  - `created_at` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo nesta data (no formato YYYY-MM-DD).
    Example: "2022-05-05"

  - `created_at__gt` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após esta data (no formato YYYY-MM-DD).
    Example: "2022-05-05"

  - `created_at__gte` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo após ou nesta data (no formato YYYY-MM-DD).
    Example: "2022-05-04"

  - `created_at__lt` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes desta data (no formato YYYY-MM-DD).
    Example: "2022-04-01"

  - `created_at__lte` (string)
    Retorne itens que foram atualizados pela última vez no banco de dados da Belvo antes ou na data especificada (no formato YYYY-MM-DD).
    Example: "2022-03-30"

  - `created_at__range` (array)
    Retorne contas que foram atualizadas pela última vez no banco de dados do Belvo entre duas datas (no formato YYYY-MM-DD). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.
    Example: ["2022-01-01","2022-12-31"]

  - `ejercicio` (integer)
    Retorne declarações de imposto exatamente para este ano (YYYY).
    Example: 2017

  - `ejercicio__lt` (integer)
    Retorne declarações de imposto de anos anteriores a este ano (YYYY).
    Example: 2017

  - `ejercicio__lte` (integer)
    Retorne declarações de imposto para este ano e anteriores (YYYY).
    Example: 2017

  - `ejercicio__gt` (integer)
    Retornar declarações de imposto para depois deste ano (YYYY).
    Example: 2017

  - `ejercicio__gte` (integer)
    Retorne declarações de imposto para este ano ou posterior (YYYY).
    Example: 2017

  - `ejercicio__range` (array)
    Retorne declarações de imposto para este intervalo de anos (YYYY). O primeiro valor indica o início do intervalo e o segundo valor indica o final do intervalo.
    Example: [2015,2021]

  - `tipo_declaracion` (string)
    Retorne declarações de impostos com este tipo de declaração.
    Example: "Normal"

  - `tipo_declaracion__in` (array)
    Retorne declarações de imposto com esses tipos de declaração.
    Example: ["Commercial"]

## Response 200 fields (application/json):

  - `count` (integer)
    O número total de resultados na sua conta Belvo.
    Example: 130

  - `next` (string,null)
    A URL para a próxima página de resultados. Cada página consiste em até 100 itens. Se não houver resultados suficientes para uma página adicional, o valor será null.

Em nosso exemplo de documentação, usamos {endpoint} como um valor de espaço reservado. Em produção, esse valor será substituído pelo endpoint real que você está usando atualmente (por exemplo, accounts ou owners).
    Example: "https://sandbox.belvo.com/api/{endpoint}/?link=1bd948f7-245d-4313-b604-34d1044cb908page=2"

  - `previous` (string,null)
    A URL para a página anterior de resultados. Se não houver uma página anterior, o valor será null.

  - `results` (array) — one of:
    Um array de:

  - objetos Tax Return Personal (Yearly)
  - objetos Tax Return Personal (Monthly)
  - objetos Tax Return Business (Yearly)
  - objetos Tax Return Business (Monthly)
  
  > 🚧 Múltiplos Schemas
  >
  > Como um link pode ter declarações de imposto tanto anuais quanto mensais, a resposta incluirá uma mistura desses dois tipos de declarações de imposto (e, portanto, diferentes schemas).
    - Declaração de Imposto de Renda Pessoal (Anual):
      - `id` (string)
        Identificador único da Belvo para o item atual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `link` (string,null)
        O link.id ao qual os dados pertencem.
        Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"
      - `collected_at` (string, required)
        O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        Informações gerais sobre a declaração de imposto (ano, RFC, tipo de declaração, nome da pessoa/empresa, etc.).
      - `sueldos_salarios` (object,null, required)
        Detalhes sobre as informações de renda juntamente com os impostos retidos.
      - `servicios_profesionales` (object,null, required)
        Detalhes sobre a renda e informações fiscais provenientes de serviços profissionais prestados.
      - `deducciones_personales` (object,null, required)
        Lista de todas as deduções fiscais pessoais.
      - `determinacion_impuesto` (object,null, required)
        Detalhes sobre a declaração de imposto final.
      - `retenciones` (object,null, required)
        Detalhes sobre os impostos já retidos.
      - `dividendos` (object,null, required)
        Detalhes sobre dividendos.
      - `datos_informativos` (object,null)
        Dados informativos adicionais na declaração de imposto.
      - `pdf` (string,null, required)
        Declaração de imposto em PDF como binário.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null, required)
        O recibo de confirmação da instituição fiscal confirmando que eles receberam a declaração de imposto.
        Example: "=PDF-STRING="
    - Declaração de Imposto de Renda Pessoal (Mensal):
      - `id` (string)
        Identificador único da Belvo para o item atual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        Informações gerais sobre a declaração de imposto (ano, RFC, tipo de declaração, nome da pessoa/empresa, etc.).
      - `isr` (object,null, required)
        Informações utilizadas para calcular os pagamentos mensais provisórios do imposto de renda.
      - `iva` (object,null, required)
        Informações usadas para calcular os pagamentos provisórios mensais do imposto sobre o IVA.
      - `pdf` (string,null, required)
        Declaração de imposto em PDF como binário.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null)
        O recibo de confirmação da instituição fiscal confirmando que eles receberam a declaração de imposto.
        Example: "=PDF-STRING="
      - `type` (string, required)
        O tipo de declaração de imposto. Pode ser mensal ou anual.
        Example: "monthly"
    - Declaração de Imposto de Renda Empresarial (Anual):
      - `id` (string, required)
        Identificador único da Belvo para o item atual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string, required)
        O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        Informações gerais sobre a declaração de imposto (ano, RFC, tipo de declaração, nome da pessoa/empresa, etc.).
      - `datos_adicionales` (object,null, required)
        Dados adicionais sobre a declaração de imposto de renda.
      - `estado_resultados` (object,null, required)
        Informações detalhadas sobre o lucro e perda anual da entidade legal.

> Nota: Para declarações de imposto submetidas para o ano fiscal de 2022 e posteriores, este campo retornará nulo, pois não é mais um campo obrigatório ao enviar sua declaração de imposto.
      - `estado_posicion_financiera_balance` (object,null, required)
        Detalhes sobre o balanço patrimonial da entidade legal.

> Nota: Para declarações de imposto apresentadas para o ano fiscal de 2022 e posteriores, este campo retornará nulo, pois não é mais um campo obrigatório ao enviar sua declaração de imposto.
      - `conciliacion_entre_resultado_contable_fiscal` (object,null, required)
        Detalhes sobre a reconciliação contábil.

> Nota: Para declarações de imposto submetidas para o ano fiscal de 2022 e posteriores, este campo retornará nulo, pois não é mais um campo obrigatório ao enviar sua declaração de imposto.
      - `deducciones_autorizadas` (object,null, required)
        Detalhes sobre as deduções da entidade legal.
      - `cifras_cierre_ejercicio` (object,null, required)
        Detalhes sobre os números-chave no final do exercício fiscal.
      - `determinacion_del_impuesto_sobre_la_renta` (object,null, required)
        Detalhes sobre a declaração de imposto final.
      - `dividendos_o_utilidades_distribuidos` (object,null, required)
        Detalhes sobre dividendos distribuídos.
      - `detalle_pago_r1_isr_personas_morales` (object,null, required)
        Detalhes do pagamento de impostos.
      - `ingressos` (object,null)
        > Nota: Aplicável apenas para declarações de imposto apresentadas em ou após 2022. Para declarações de imposto apresentadas antes de 2022, este campo retornará null.

Detalhes sobre os valores totais ganhos no ano fiscal.
      - `determinacion` (object,null)
        > Nota: Aplicável apenas para declarações de imposto apresentadas em ou após 2022. Para declarações de imposto apresentadas antes de 2022, este campo retornará null.

Detalhes sobre o imposto devido ou crédito fiscal.
      - `pdf` (string,null, required)
        Declaração de imposto em PDF como binário.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null, required)
        O recibo de confirmação da instituição fiscal confirmando que eles receberam a declaração de imposto.
        Example: "=PDF-STRING="
    - Declaração de Imposto de Renda Empresarial (Mensal):
      - `id` (string)
        Identificador único da Belvo para o item atual.
        Example: "0d3ffb69-f83b-456e-ad8e-208d0998d71d"
      - `collected_at` (string, required)
        O carimbo de data/hora ISO-8601 quando o ponto de dados foi coletado.
        Example: "2022-02-09T08:45:50.406032Z"
      - `created_at` (string)
        O carimbo de data e hora ISO-8601 de quando o ponto de dados foi criado no banco de dados da Belvo.
        Example: "2022-02-09T08:45:50.406032Z"
      - `informacion_general` (object,null, required)
        Informações gerais sobre a declaração de imposto (ano, RFC, tipo de declaração, nome da pessoa/empresa, etc.).
      - `determinacion_isr` (object,null, required)
        Informações utilizadas para calcular o imposto de renda provisório para o período.
      - `detalle_pago_isr` (object,null, required)
        Informações sobre os pagamentos mensais provisórios para o imposto de renda.
      - `determinacion_iva` (object,null, required)
        Informações usadas para calcular o imposto provisório de IVA para o período.
      - `detalle_pago_iva` (object,null, required)
        Informações sobre os pagamentos mensais provisórios para o imposto sobre o valor agregado (IVA).
      - `pdf` (string,null, required)
        Declaração de imposto em PDF como binário.
        Example: "=PDF-STRING="
      - `receipt_pdf` (string,null)
        O recibo de confirmação da instituição fiscal confirmando que eles receberam a declaração de imposto.
        Example: "=PDF-STRING="
      - `type` (string,null, required)
        O tipo de declaração de imposto. Pode ser mensal ou anual.
        Example: "monthly"

## Response 403 fields (application/json):

  - `code` (string)
    Um código de erro único (access_to_resource_denied) que permite classificar e tratar o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com 403 access_to_resource_denied.
    Example: "access_to_resource_denied"

  - `message` (string)
    Uma breve descrição do erro.

Para erros access_to_resource_denied, a descrição é:

  - You don't have access to this resource..
    Example: "You don't have access to this resource."

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 404 fields (application/json):

  - `code` (string)
    Um código de erro único (not_found) que permite classificar e lidar com o erro programaticamente.
    Example: "not_found"

  - `message` (string)
    Uma breve descrição do erro.

Para erros not_found, a descrição é:

  - Not found
    Example: "Not found"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 408 fields (application/json):

  - `code` (string)
    Um código de erro único (request_timeout) que permite classificar e lidar com o erro programaticamente.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 408 request_timeout.
    Example: "request_timeout"

  - `message` (string)
    Uma breve descrição do erro.

Para erros de request_timeout, a descrição é:

  - The request timed out, you can retry asking for less data by changing your query parameters.
    Example: "The request timed out, you can retry asking for less data by changing your query parameters"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

## Response 428 fields (application/json):

  - `code` (string)
    Um código de erro único (token_required) que permite classificar e lidar com o erro programaticamente.
ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 428 token_required.
    Example: "token_required"

  - `message` (string)
    Uma breve descrição do erro. Para erros token_required, a descrição é:

- A instituição requer um token MFA para fazer login.
    Example: "A MFA token is required by the institution to login"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"

  - `session` (string)
    Um ID único de 32 caracteres da sessão de login (correspondente a um padrão regex de: [a-f0-9]{32}).
    Example: "2675b703b9d4451f8d4861a3eee54449"

  - `expiry` (integer)
    Tempo de duração da sessão em segundos.
    Example: 9600

  - `link` (string)
    Identificador único criado pela Belvo, usado para referenciar o Link atual.
    Example: "30cb4806-6e00-48a4-91c9-ca55968576c8"

  - `token_generation_data` (object)
    Detalhes sobre como gerar o token.

  - `token_generation_data.instructions` (string)
    Instruções para geração de token.
    Example: "Use this code to generate the token"

  - `token_generation_data.type` (string)
    Tipo de dados para gerar o token (QR code, desafio numérico).
    Example: "numeric"

  - `token_generation_data.value` (string)
    Valor a ser usado para gerar o token.
    Example: "12345"

  - `token_generation_data.expects_user_input` (boolean)
    Indica se o usuário precisa fornecer entrada para concluir a autenticação. Quando definido como false, seu usuário pode precisar:
- confirmar o login em outro dispositivo
- escanear um código QR
Você ainda precisará fazer uma chamada PATCH para concluir a solicitação.
    Example: true

## Response 500 fields (application/json):

  - `code` (string)
    Um código de erro único (unexpected_error) que permite classificar e tratar o erro de forma programática.

ℹ️ Consulte nosso DevPortal para mais informações sobre como lidar com erros 500 unexpected_error.
    Example: "unexpected_error"

  - `message` (string)
    Uma breve descrição do erro.

Para erros unexpected_error, a descrição é:

  - Belvo não consegue processar a solicitação devido a um problema interno do sistema ou a uma resposta não suportada de uma instituição.
    Example: "Belvo is unable to process the request due to an internal system issue or to an unsupported response from an institution"

  - `request_id` (string)
    Um ID único de 32 caracteres da solicitação (correspondente a um padrão regex de: [a-f0-9]{32}). Forneça este ID ao entrar em contato com a equipe de suporte da Belvo para acelerar as investigações.
    Example: "9e7b283c6efa449c9c028a16b5c249fb"