Enviar un archivo y leerlo

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.

Shell
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"
CampoSignificado
fileObligatorio. 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.
nameEl nombre del archivo. Sin él, Ocost toma el de la subida.
external_refTu 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 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 explica cada uno. Para muchos archivos a la vez, mantente sincronizado 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.

Shell
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 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.

Shell
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.

Shell
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:

RespuestaQué hacer
409 urn:ocost:file:readingEl archivo se está leyendo. Inténtalo más tarde.
409 urn:ocost:file:linkedOcost 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