# Enviar un archivo y leerlo
> Enviar un archivo, reenviarlo sin riesgo, esperar hasta que esté leído, leer sus documentos, obtener el original, borrarlo.
>
> Antes: [Claves y permisos](https://ocost.io/docs/es/authentication.md)

Envía un PDF, una imagen o una factura electrónica, espera hasta que Ocost lo haya leído y luego lee sus documentos. Un archivo puede contener varios documentos. Un escaneo de tres facturas es un archivo con tres documentos.

## Envía el archivo

Envía el archivo como `multipart/form-data` a `POST /public/v1/files`. La clave necesita el permiso [`documents:write`](https://ocost.io/docs/es/authentication.md).

```bash
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@scan.pdf" -F "name=scan.pdf" -F "external_ref=account.move,42"
```

| Campo | Significado |
| --- | --- |
| `file` | Obligatorio. Un PDF, una imagen (JPEG, PNG, TIFF, WebP), un archivo de Word (.docx, .doc) o el XML de una factura electrónica (XRechnung, UBL, CII), hasta 25 MB. |
| `name` | El nombre del archivo. Sin él, Ocost toma el de la subida. |
| `external_ref` | Tu propio id, hasta 200 caracteres, devuelto con el archivo. |

La API rechaza las hojas de cálculo (.xls, .xlsx) y los archivos comprimidos (.zip, .7z) con `415`. Súbelos en Ocost. Allí Ocost lee una factura en una hoja de cálculo de una sola hoja, hasta 200 filas y 30 columnas. Descomprime un archivo comprimido una vez, en la sociedad a la que llega. Los demás XML y HTML se guardan, pero terminan en `not_read` con `nothing_found`.

Un archivo nuevo responde `202 Accepted` con `"status": "received"`, y la lectura empieza enseguida:

```json
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }
```

Cada respuesta lleva `X-Ocost-Documents-Left`, los documentos que le quedan a tu plan este mes. [Límites y errores](https://ocost.io/docs/es/limits.md) lista los rechazos.

## Reenvíalo sin riesgo

Ocost reconoce un archivo por el SHA-256 de sus bytes, no por su nombre. Los mismos bytes otra vez responden `200 OK` con ese archivo tal como está ahora. Ocost no lo vuelve a leer ni a contar. Así que, tras un timeout, envía el archivo otra vez.

Un archivo conserva cada `external_ref` enviado con sus bytes. `external_ref` sigue siendo el primero, y `external_refs` los lista todos, el primero en primer lugar, cada uno una vez, hasta 50. Así que, cuando dos de tus registros llevan el mismo PDF, envíalo para cada uno: ambos ids vuelven con el mismo archivo. Un id nuevo número 51 se rechaza con `422`.

## Espera hasta que esté leído

Pide el archivo con `GET /public/v1/files/{file_id}`, permiso `documents:read`. Consulta cada 2 o 3 segundos durante medio minuto y después cada 10 a 30 segundos. La mayoría de los PDF tardan menos de un minuto, los largos unos pocos.

```python
def wait_for(session, file_id, timeout=300):
    started = time.monotonic()
    while time.monotonic() - started < timeout:
        file = session.get(f"{API}/files/{file_id}", timeout=15).json()
        if file["status"] not in ("received", "reading"):
            return file
        time.sleep(3 if time.monotonic() - started < 30 else 15)
    return file
```

El archivo está listo cuando su `status` es `read`, `not_read` o `failed`. [Estados y motivos](https://ocost.io/docs/es/statuses.md) explica cada uno. Para muchos archivos a la vez, [mantente sincronizado](https://ocost.io/docs/es/sync.md) en lugar de consultar cada uno.

## Lee sus documentos

Un archivo `read` lista sus documentos en `documents`, cada uno con su `id`, `kind`, `number` y `pages`. `GET /public/v1/files/{file_id}/document` responde el primero. `GET /public/v1/documents/{document_id}` responde cualquiera de ellos.

```bash
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
  -H "Authorization: Bearer $OCOST_KEY"
```

La respuesta es el documento como `ocost.document.v1`. [El documento](https://ocost.io/docs/es/document.md) muestra uno completo y explica cada campo.

## Obtén el original

`GET /public/v1/files/{file_id}/content` responde los bytes tal como los enviaste.

```bash
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
  -H "Authorization: Bearer $OCOST_KEY"
```

## Borra un archivo

`DELETE /public/v1/files/{file_id}` borra el archivo enseguida y para siempre. Eso incluye sus documentos, lo leído, su índice de búsqueda y el original. La clave necesita `documents:write`.

```bash
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"
```

Ocost responde `204`, y `404` a partir de entonces. Se niega en dos casos:

| Respuesta | Qué hacer |
| --- | --- |
| `409 urn:ocost:file:reading` | El archivo se está leyendo. Inténtalo más tarde. |
| `409 urn:ocost:file:linked` | Ocost aún necesita el archivo, para una factura contabilizada, un extracto bancario, una pregunta abierta o un proyecto. `detail` dice para qué. Bórralo en Ocost cuando nada lo necesite. |

## Véase también

- [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.
- [El documento](https://ocost.io/docs/es/document.md): El esquema ocost.document.v1 en términos de EN 16931 (se corresponde con UBL y CII): un ejemplo, tipo y dirección, fuentes, comprobaciones, versiones, y cada campo y valor.
- [Mantenerse sincronizado](https://ocost.io/docs/es/sync.md): Recoger cada archivo cambiado con una sola llamada: GET /public/v1/files con updated_since, un cursor y un filtro de estado.
- [Grupos de empresas](https://ocost.io/docs/es/groups.md): Grupos de empresas: a qué sociedades llega una clave, la cabecera Ocost-Business, el enrutado por los identificadores del documento, needs_company y los archivos del grupo.
- En ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
