# Listar formularios

Para obtener un listado de los formularios para un rango de fechas particular, se debe enviar un GET con los siguientes parámetros.

<mark style="color:blue;">`GET`</mark> `https://api.persat.com.ar/v1/digital-forms`

#### Query Parameters

| Name                                     | Type   | Description                                                                                                                                                                                                                                            |
| ---------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| from<mark style="color:red;">\*</mark>   | String | Fecha desde en formato yyyy-MM-ddT00:00:00.000Z. En caso de enviar horas minutos, segundos o milisegundos, seran ignorados. La busqueda es realizada por dias completos en horario local                                                               |
| to<mark style="color:red;">\*</mark>     | String | Fecha hasta en formato yyyy-MM-ddT00:00:00.000Z. En caso de enviar horas minutos, segundos o milisegundos, seran ignorados. La busqueda es realizada por dias completos en horario local, incluyendo este mismo dia. Ver ejemplo en esta misma seccion |
| offset<mark style="color:red;">\*</mark> | number | Mismo concepto de SQL para la paginación.                                                                                                                                                                                                              |
| limit<mark style="color:red;">\*</mark>  | number | Mismo concepto de SQL para la paginación. Valor máx: 100                                                                                                                                                                                               |
| uid\_client                              | String | Identificador del cliente, en caso que solo quiera obtener los formularios en este cliente                                                                                                                                                             |
| form\_id                                 | number | schema\_id representando el tipo de formulario a buscar                                                                                                                                                                                                |

#### Headers

| Name                                            | Type   | Description     |
| ----------------------------------------------- | ------ | --------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer API\_KEY |

{% tabs %}
{% tab title="200: OK La consulta se ejecutó con éxito" %}

```json
{
    "success": true,
    "paging": {
        "offset": 0,
        "limit": 2,
        "result": 2,
        "total": 350
    },
    "data": [
        {
            "_id": "197",
            "created": "2022-05-03T16:17:21.000Z",
            "created_by_user_name": "eandino@persat.com.ar",
            "created_by_user_id": 28,
            "client": {
                "id": 12596,
                "name": "Logistica Hnos.",
                "uid_client": "klk321MM"
            },
            "df_data": {
                "schema_id": 170,
                "results": {
                    "last_updated": "2022-05-03T16:17:21.000Z",
                    "formvalues": {
                        "FWA3VCpeS": "Texto 1",
                        "FWNDBKSIr": "Texto 2",
                        "FW27yy7bk": 5
                    }
                }
            },
            "state": {
                "color": "RED",
                "deleted": false,
                "id": 27,
                "name": "Cancelado"
            }
        },
        {
            "_id": "198",
            "created": "2022-05-03T16:20:50.000Z",
            "created_by_user_name": "eandino@persat.com.ar",
            "created_by_user_id": 28,
            "client": {
                "id": 12597,
                "name": "Distribuidora de alimentos",
                "uid_client": "AKKJDS23"
            },
            "df_data": {
                "schema_id": 170,
                "results": {
                    "last_updated": "2022-05-03T16:20:50.000Z",
                    "formvalues": {
                        "FWA3VCpeS": "Otro texto 1",
                        "FWNDBKSIr": "Otro texto 2",
                        "FW27yy7bk": 6
                }
            },
            "state": {
                "color": "RED",
                "deleted": false,
                "id": 27,
                "name": "Cancelado"
            }
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Error en alguno de los campos enviados. userMessage contiene informacipon adicional." %}

```json
{
    "success": false,
    "error": {
        "status": 400,
        "type": "BAD_REQUEST",
        "userMessage": "'limit' debe ser un numero mayor que 0 y menor que 100"
    }
}
```

{% endtab %}

{% tab title="404: Not Found En caso de enviar uid\_client y el cliente mencionado no existe" %}

```javascript
{
    "success": false,
    "error": {
        "status": 404,
        "type": "NOT_FOUND",
        "userMessage": "No existe un cliente con este número."
    }
}
```

{% endtab %}
{% endtabs %}

### Ejemplo 1

\*\*<https://api.persat.com.ar/v1/digital-forms**?from=2022-05-03T00:00:00.000Z\\&to=2022-05-03T00:00:00.000Z\\&offset=0\\&limit=2>

La consulta se realiza por día, es decir que si bien tanto **from** como **to** son fechas en formato ISO, no importa si se envian las horas minutos segundos del dia. Ya que no se tomarán en cuenta para la consulta.

Tampoco importa la zona horaria, o sea que si estoy en Argentina, México o Perú, y quiero obtener los formularios creados el día 3 de Mayo de 2022, entonces tanto **from** como **to** deben ser "2022-05-03T00:00:00.000Z" como se muestra en la consulta.

{% hint style="success" %}
No hay un límite máximo en el rango a consultar, pero si en la cantidad de formularios a obtener por página. Ese valor se controla con el parametro **limit** en la misma query. Valor máx: 100.
{% endhint %}

### Analizando la Respuesta

En caso que no haya ningun error, obtenemos una respuesta de este estilo. El field "data" es un array con cada uno de los formularios. La explicación de cada uno de los campos del formulario se puede ver en la sección [Obtener Formulario](/modulos/formularios-digitales/obtener-formulario.md)

El paging nos da información sobre la página obtenida. En este ejemplo

**paging.offset:** El mismo valor de offset que se envio en el query

**paging.limit:** El mismo valor de limit que se envio en el query

**paging.result:** Se devolvieron 2 formularios

**paging.total:** Se encontraron 350 formularios creados para este rango de fechas

```json
{
    "success": true,
    "paging": {
        "offset": 0,
        "limit": 2,
        "result": 2,
        "total": 350
    },
    "data": [
        {
            "_id": "197",
            "created": "2022-05-03T16:17:21.000Z",
            "created_by_user_name": "eandino@persat.com.ar",
            "created_by_user_id": 28,
            "client": {
                "id": 12596,
                "name": "Logistica Hnos.",
                "uid_client": "klk321MM"
            },
            "df_data": {
                "schema_id": 170,
                "results": {
                    "last_updated": "2022-05-03T16:17:21.000Z",
                    "formvalues": {
                        "FWA3VCpeS": "Texto 1",
                        "FWNDBKSIr": "Texto 2",
                        "FW27yy7bk": 5
                    }
                }
            },
            "state": {
                "color": "RED",
                "deleted": false,
                "id": 27,
                "name": "Cancelado"
            }
        },
        {
            "_id": "198",
            "created": "2022-05-03T16:20:50.000Z",
            "created_by_user_name": "eandino@persat.com.ar",
            "created_by_user_id": 28,
            "client": {
                "id": 12597,
                "name": "Distribuidora de alimentos",
                "uid_client": "AKKJDS23"
            },
            "df_data": {
                "schema_id": 170,
                "results": {
                    "last_updated": "2022-05-03T16:20:50.000Z",
                    "formvalues": {
                        "FWA3VCpeS": "Otro texto 1",
                        "FWNDBKSIr": "Otro texto 2",
                        "FW27yy7bk": 6
                }
            },
            "state": {
                "color": "RED",
                "deleted": false,
                "id": 27,
                "name": "Cancelado"
            }
        }
    ]
}
```

{% hint style="danger" %}
Para este caso particular, los dos formularios pertenecen al mismo **schema\_id**, es decir que es la misma plantilla. Con lo cual ambos tienen los mismos widgets con los mismos ids (FW *. . . . . . .*)

Es importante entender que estamos recibiendo para poder asi hacer una lectura correcta de los datos.
{% endhint %}

### Ejemplo 2

Ahora solo quiero obtener los formularios de un cliente particular, entonces tengo que agregar a la consulta el uid\_client

\*\*<https://api.persat.com.ar/v1/digital-forms**?from=2022-05-03T00:00:00.000Z\\&to=2022-05-03T00:00:00.000Z\\&offset=0\\&limit=2\\&uid\\_client=AKKJDS23>

{% hint style="danger" %}
En caso que el uid\_client contenga caracteres especiales, recordá realizar un url encode para hacer la consulta
{% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.api.persat.com.ar/modulos/formularios-digitales/listar-formularios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.