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.
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:
{ "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.
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 fileEl 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.
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.
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.
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. |