# Mantenerse sincronizado
> Recoger cada archivo cambiado con una sola llamada: GET /public/v1/files con updated_since, un cursor y un filtro de estado.
>
> Antes: [Enviar un archivo y leerlo](https://ocost.io/docs/es/files.md)

Recoge cada archivo que cambió desde tu última consulta, en lugar de consultar cada archivo. `GET /public/v1/files` lista los archivos por su último cambio, el más antiguo primero. Un cursor le dice a Ocost dónde te quedaste. La clave necesita el permiso [`documents:read`](https://ocost.io/docs/es/authentication.md).

## Pide la primera página

Pasa `updated_since` para empezar en un momento. Omítelo para empezar desde el primer archivo.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "updated_since=2026-11-09T08:00:00Z" \
  --data-urlencode "limit=100"
```

La respuesta contiene los archivos, el cursor y si siguen más:

```json
{
  "files": [
    {
      "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
      "name": "invoice.pdf",
      "status": "read",
      "external_ref": "account.move,42",
      "external_refs": ["account.move,42"],
      "documents": [
        { "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11", "kind": "invoice", "number": "RE-2026-1187", "pages": [1] }
      ],
      "updated_at": "2026-11-09T08:02:41Z"
    }
  ],
  "next_cursor": "MjAyNi0xMS0wOVQwODowMjo0MVo",
  "more": false
}
```

Una página contiene hasta `limit` archivos, de 1 a 100, 50 por defecto. Un archivo aparece una vez por cada cambio.

## Sigue el cursor

Mientras `more` sea `true`, pide otra vez enseguida con `cursor` igual a `next_cursor`. Cuando `more` sea `false`, guarda el último `next_cursor`. Pide con él en tu próxima consulta y recibes solo lo que cambió desde entonces.

```python
def changed_since(session, cursor=None):
    """Cada archivo cambiado desde el cursor guardado en la última consulta (None: todos)."""
    files = []
    while True:
        params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
        page = session.get(f"{API}/files", params=params, timeout=15).json()
        files += page["files"]
        cursor = page["next_cursor"] or cursor
        if not page["more"]:
            return files, cursor  # guarda el cursor para la próxima consulta
```

```javascript
async function changedSince(cursor) {
  const files = [];
  for (;;) {
    const params = new URLSearchParams({ limit: '100', ...(cursor ? { cursor } : {}) });
    const page = await fetch(`${API}/files?${params}`, { headers: auth }).then((r) => r.json());
    files.push(...page.files);
    cursor = page.next_cursor ?? cursor;
    if (!page.more) return { files, cursor }; // guarda el cursor para la próxima consulta
  }
}
```

## Solo los archivos terminados

Pide con `status` para listar solo los archivos en esos estados. Repítelo para varios.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "cursor=$CURSOR" \
  --data-urlencode "status=read" --data-urlencode "status=not_read" \
  --data-urlencode "status=failed"
```

`status` filtra después de paginar. Por eso una página puede contener menos archivos que `limit`, o ninguno. Sigue `more`, no la cuenta.

Después trata cada archivo según su estado. [Estados y motivos](https://ocost.io/docs/es/statuses.md) dice qué significa cada uno.

## Encuentra un archivo por tu id

Pide con `external_ref` para listar solo los archivos que llevan ese id entre sus `external_refs`, con coincidencia exacta. Se combina con `status`, `updated_since` y `cursor`.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "external_ref=account.move,42"
```

## Véase también

- [Enviar un archivo y leerlo](https://ocost.io/docs/es/files.md): Enviar un archivo, reenviarlo sin riesgo, esperar hasta que esté leído, leer sus documentos, obtener el original, borrarlo.
- [Estados y motivos](https://ocost.io/docs/es/statuses.md): Los estados de un archivo y los motivos por los que no se leyó, y qué hacer en cada caso.
- [Búsqueda](https://ocost.io/docs/es/search.md): Buscar en todos los documentos por palabras y por significado: parámetros, filtros, resultados, ejemplos.
