> For the complete documentation index, see [llms.txt](https://devcenter.unico.io/unico-sign/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-envelopes/listar-documentos.md).

# Listar documentos

## Sobre este guia[​](https://developers.unico.io/docs/sign/api-guides/managing-evelopes/list-documents#sobre-este-guia) <a href="#sobre-este-guia" id="sobre-este-guia"></a>

Através deste guia, demonstraremos como listar os documentos pertencentes a um envelope através de nossa API REST. Ao seguir os passos deste guia, em poucos minutos você será capaz de obter todos os documentos de um envelope (assim como alguns de seus detalhes), de forma estruturada em uma resposta JSON.

## O que você vai precisar[​](https://developers.unico.io/docs/sign/api-guides/managing-evelopes/list-documents#o-que-voc%C3%AA-vai-precisar) <a href="#o-que-voce-vai-precisar" id="o-que-voce-vai-precisar"></a>

Antes de iniciar sua integração:

1. Certifique-se que você possui credenciais válidas para utilizar o **Unico Sign**. Se você ainda não possui suas credenciais, siga nosso [<mark style="color:blue;">guia de Primeiros Passos</mark>](https://devcenter.unico.io/unico-sign/primeiros-passos) para configurar sua conta de teste e obter suas chaves de API.
2. Entenda os conceitos básicos sobre nosso produto. É extremamente importante que você entenda estes conceitos para fazer uma boa utilização das APIs do **Unico Sign**. Você pode encontrar nossos conceitos básicos [<mark style="color:blue;">neste guia</mark>](https://devcenter.unico.io/unico-sign/conceitos-basicos).

## Funcionamento básico[​](https://developers.unico.io/docs/sign/api-guides/managing-evelopes/list-documents#funcionamento-b%C3%A1sico) <a href="#funcionamento-basico" id="funcionamento-basico"></a>

Como explicamos em nosso [<mark style="color:blue;">guia de conceitos básicos</mark>](https://devcenter.unico.io/unico-sign/conceitos-basicos), nossa entidade **Envelope** (`envelope`) é a representação virtual de um envelope com documentos na vida real. Ele é o objeto que agrupa todos os documentos (`document`) e seus assinantes (`subscriber`), sendo que um envelope pode conter mais de documento, que por sua vez pode conter um ou mais assinantes.

Entenda, a seguir, como chamar nossa API REST para obter todos os documentos de um envelope.

{% stepper %}
{% step %}

### Obtenha um token OAuth válido <a href="#obtenha-um-token-oauth-valido" id="obtenha-um-token-oauth-valido"></a>

Para efetuar requisições à nossa API REST você necessitará de um token de acesso OAuth válido. Caso não esteja familiarizado com o modelo de autenticação OAuth, entenda como gerar um token válido [<mark style="color:blue;">neste artigo</mark>](https://devcenter.unico.io/unico-sign/guia-das-apis/autenticacao).  Após sua geração, o token de acesso deverá ser enviado no `header` de sua requisição,  junto ao parâmetro `Authorization`.

{% hint style="info" %}
**Ambientes**

Ao iniciar sua integração você receberá credenciais a nosso ambiente de homologação. Somente após o processo de testes e certificação você receberá credenciais de produção.

Você deverá apontar suas requisições às URLs corretas em cada estágio de sua integração. Abaixo listamos as URLs de homologação e produção:

* Ambiente de homologação: `https://signhom.acesso.io`;
* Ambiente de produção: `https://sign.acesso.io`.
  {% endhint %}

{% endstep %}

{% step %}

### Configure os filtros de sua pesquisa <a href="#configure-os-filtros-de-sua-pesquisa" id="configure-os-filtros-de-sua-pesquisa"></a>

Opcionalmente, você pode configurar alguns critérios para sua busca. Para isto, os campos de filtro devem ser enviados no `body` de sua requisição.

{% hint style="info" %}
**Obrigatoriedade dos filtros**

Nenhum dos filtros é obrigatório. Caso não informados, por padrão, retornaremos 30 envelopes em nossa resposta JSON.
{% endhint %}

O schema abaixo contêm os parâmetros e domínios permitidos para a configuração dos filtros:

<table data-header-hidden><thead><tr><th width="202">Parâmetro</th><th width="140">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td>CPF</td><td>string or null </td><td><p>Default: <code>null</code></p><p></p><p>Número de cadastro de pessoa física do assinante.</p><p></p><p>Se fornecido valor para <code>EnvelopeUUID</code> o valor de <code>CPF</code> será ignorado</p><ul><li>sem formatação, apenas os 11 números</li></ul></td></tr><tr><td>EnvelopeUUID</td><td>string or null &#x3C;uuid></td><td><p>Default: <code>null</code></p><p></p><p>Identificador único do envelope</p></td></tr><tr><td>Status</td><td>integer &#x3C;int32></td><td><p>(EnvelopeStatusEnum)</p><p>Enum: <code>0</code> <code>1</code> <code>2</code> <code>3</code> <code>4</code> <code>5</code> <code>6</code></p><p>Estado do envelope, que pode ser:</p><ul><li><code>0</code> - Expirado</li><li><code>1</code> - Pendente</li><li><code>2</code> - Concluído</li><li><code>3</code> - Cancelado</li><li><code>4</code> - Processando</li><li><code>5</code> - Recusado</li><li><code>6</code> - Agendado</li></ul></td></tr><tr><td>Page</td><td>integer or null &#x3C;int32></td><td><p>Default: <code>1</code></p><p></p><p>Número da página da busca Ops, estamos corrigindo! Paginação não suportada da página 334 em diante. Por favor utilizar mais filtros para fazer uma busca mais precisa de acordo com seu objetivo</p></td></tr><tr><td>StartDate</td><td>string or null &#x3C;date></td><td><p>Data inicial para busca sob a data de criação do envelope</p><ul><li>Se esta data for definida, também deve ser definida a data em <code>EndDate</code></li><li>A data deve ser após 01/01/2018</li><li>A data deve ser anterior a data definida em <code>EndDate</code></li></ul></td></tr><tr><td>EndDate</td><td>string or null &#x3C;date></td><td><p>Data final para busca sob a data de criação do envelope</p><ul><li>Se esta data for definida, também deve ser definida a data em <code>StartDate</code></li><li>A data deve ser após 01/01/2018</li></ul></td></tr><tr><td>Order</td><td>string (Orders)</td><td><p>Enum: <code>"ASC"</code> <code>"DESC"</code></p><p></p><p>Ordenação dos elementos da lista, que pode ser:</p><ul><li><code>ASC</code> - Crescente</li><li><code>DESC</code> - Decrescente</li></ul></td></tr><tr><td>EnvelopeTags</td><td>Array of strings or null</td><td>Lista de tags do envelope Ao passar mais de uma tag, a busca retornará apenas envelope que contenha todas as tags informadas</td></tr></tbody></table>

O exemplo abaixo solicita em ordem **ascendente**, envelopes cujos assinantes possuam o **CPF 100.000.000-19**, criados de **01/08/2022 a 31/08/2022**, com status **pendente**.

```json
{
  "CPF": "10000000019",  
  "StartDate": "01/08/2022",
  "EndDate": "31/08/2022",
  "Status": 1,
  "Order": "ASC"
}
```

{% endstep %}

{% step %}

### Faça uma requisição POST para o endpoint `/envelopes/` <a href="#faca-uma-requisicao-post-para-o-endpoint-envelopes" id="faca-uma-requisicao-post-para-o-endpoint-envelopes"></a>

Após gerar um token de acesso válido e, opcionalmente, montar o `body` com os filtros, faça uma requisição para o endpoint de obtenção de lista de documentos da nossa API REST (`POST/service/envelopes`). Serão obtidos os dados de todos envelopes atrelados ao usuário do token utilizado.

{% hint style="warning" %}
**Permissão para Visualizar Documentos**

Para utilizar esta rota é necessário que o usuário tenha permissão de **Visualizar Documentos.**
{% endhint %}

Exemplo solicitando em ordem **ascendente**, envelopes cujos assinantes possuam o **CPF 100.000.000-19**, criados de **01/08/2022 a 31/08/2022**, com status **pendente**:

```json
curl -X 'POST' \
  'https://signhom.acesso.io/api/v1/service/envelopes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'
  -d '{
  "CPF": "10000000019",  
  "StartDate": "01/08/2022",
  "EndDate": "31/08/2022",
  "Status": 1,
  "Order": "ASC"
}'
```

Se tudo der certo em sua requisição, você receberá como resposta um JSON contendo uma lista todos os envelopes associados a sua consulta:

{% hint style="warning" %}
**Limite de páginas**

Atualmente não é possível listar documentos da página 334 em diante. Caso seja necessário acessar uma dessas páginas, recomendamos utilizar os filtros para uma busca mais precisa.
{% endhint %}

```json
{
  "Success": true,
  "Message": "",
  "Data": {
    "Page": 1,
    "MaxPage": 5,
    "Count": 50,
    "Envelopes": [
      {
        "CreatedDate": "09/04/2022 20:09",
        "ID_EnvelopeStatus": 2,
        "EnvelopeStatus": "Concluído",
        "UUID": "00000000-0000-0000-0000-000000000000",
        "HasFrame": false,
        "Documents": [
          {
            "Url": "https://sign.unico.io/path",
            "UrlVoucher": "https://sign.unico.io/path",
            "DocumentType": "admissao",
            "CreatedDate": "09/04/2022 20:09",
            "EmitterUserName": "Carlos Eduardo",
            "EmitterUserUUID": "00000000-0000-0000-0000-000000000000",
            "EmitterUserEmail": "test@test.com",
            "CompanySocialName": "unico",
            "UUID": "00000000-0000-0000-0000-000000000000",
            "HasFile": false,
            "Subscribers": [
              {
                "SubscriberName": "Flavia dos Santos",
                "SubscriberCPF": "10000000019",
                "SubscriberEmail": "test@test.com",
                "SubscriberPhone": "551192345678",
                "SubscriberOrder": 1,
                "SubscriberRole": 1,
                "URLFrameFull": "https://unico.io/path",
                "IsUser": false
              }
            ],
            "IsTemplate": false,
            "DocumentSubcategoryUUID": "00000000-0000-0000-0000-000000000000",
            "DocumentSubcategoryName": "Abertura de conta bancária",
            "DocumentCategoryUUID": "00000000-0000-0000-0000-000000000000",
            "DocumentCategoryName": "Admissão"
          }
        ]
      }
    ],
    "Rows": 0
  }
}
```

Cada elemento do objeto `Envelopes` representa um envelope com seus respectivos documentos, contidos no objeto `Documents`.
{% endstep %}
{% endstepper %}

## Próximos passos[​](https://developers.unico.io/docs/sign/fundamentals#pr%C3%B3ximos-passos) <a href="#proximos-passos" id="proximos-passos"></a>

* Conheça as funcionalidades disponíveis para o [<mark style="color:blue;">Gerenciamento de documentos</mark>](https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-documentos).
* Conheça as funcionalidades disponíveis para o [<mark style="color:blue;">Gerenciamento de envelopes</mark>](https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-envelopes).
* Tendo problemas em nossa integração? Acesse nossa seção de [<mark style="color:blue;">FAQ e problemas comuns</mark>](https://devcenter.unico.io/unico-sign/recursos-adicionais/faq).

***

**Dúvidas?**[**​**](https://developers.unico.io/docs/IDunico/Integracao/primeirosPassos#d%C3%BAvidas)

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da [<mark style="color:blue;">Central de Ajuda</mark>](https://empresas.unico.io/hc/pt-br/p/atendimentoparaempresas).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://devcenter.unico.io/unico-sign/guia-das-apis/gerenciando-envelopes/listar-documentos.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.