Referencia de la API REST

Convierta extractos bancarios OFX, QFX, QBO y PDF a JSON, Excel o CSV mediante programación.

Descripción general

La API REST de OFXConverter le permite convertir archivos de extractos bancarios desde sus propias aplicaciones. Envíe un archivo y reciba las transacciones extraídas en JSON estructurado o como un archivo Excel o CSV codificado en Base64. La API está disponible para cuentas con un plan de pago.

La API requiere un plan premium activo. Genere su clave de API desde la página de perfil de su panel.

URL base

Todos los endpoints son relativos a la siguiente URL base. Todas las solicitudes deben realizarse mediante HTTPS.

https://www.ofxconverter.com/api/v1

Autenticación

Autentique cada solicitud enviando su clave de API en el encabezado Authorization. Use el valor de la clave tal cual, sin prefijo Bearer ni esquema.

Authorization: YOUR_API_KEY

Una solicitud sin clave devuelve NO_API_KEY; una clave inválida, o una clave de una cuenta sin plan premium, devuelve UNAUTHORISED. Ambas se envían con HTTP 401.

Límites y cuotas

El uso está limitado por la cuota mensual de conversiones de su plan: Start 500, Pro 1.500, Enterprise 5.000 conversiones al mes. El tamaño máximo de archivo es de 10 MB. Los archivos subidos y generados se eliminan automáticamente después de unos 30 minutos.

Plan	Conversiones mensuales	Tamaño máximo de archivo
Start	500	10 MB
Pro	1,500	10 MB
Enterprise	5,000	10 MB

Endpoints

Las solicitudes que envían un archivo usan multipart/form-data. El campo opcional output selecciona el formato de respuesta: csv o excel devuelven el archivo convertido como una cadena Base64, mientras que cualquier otro valor (u omitirlo) devuelve las transacciones extraídas como JSON.

post /api/v1/conversion

Convierte un archivo OFX, QFX o QBO en una sola solicitud.

Parámetros de la solicitud

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Authorization`	header	string	Sí	Su clave de API.
`file`	form-data	file	Sí	`.ofx`, `.qfx` o `.qbo`, hasta 10 MB.
`output`	form-data	string	No	`csv`, `excel`, u omítalo para JSON.

Ejemplo de solicitud

curl -X POST "https://www.ofxconverter.com/api/v1/conversion" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.ofx" \
  -F "output=excel"

Ejemplo de respuesta (excel / csv)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement.ofx",
  "convertedFile": "UEsDBBQABgAIAAAAIQ...=="
}

Ejemplo de respuesta (json)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement.ofx",
  "convertedFile": {
    "header": {
      "status": "OK",
      "language": "ENG",
      "serverDate": "2024-01-31T00:00:00",
      "bankName": "Bank of Example",
      "currency": "USD",
      "hasInvestiment": false
    },
    "bankAccount": {
      "type": "CHECKING",
      "agencyCode": "0001",
      "bank": { "code": 1, "name": "Bank of Example" },
      "accountCode": "1234567"
    },
    "status": "OK",
    "initialDate": "2024-01-01T00:00:00",
    "finalDate": "2024-01-31T00:00:00",
    "transactions": [
      {
        "type": "DEBIT",
        "date": "2024-01-05T00:00:00",
        "value": -42.5,
        "id": "202401050001",
        "uniqueID": "202401050001",
        "description": "Coffee Shop",
        "checksum": 849302145,
        "units": null,
        "price": null,
        "comission": null,
        "secName": null,
        "ticker": null
      }
    ]
  }
}

post /api/v1/upload

Almacena un archivo para su conversión posterior. Devuelve un fileID que puede pasar a GET /api/v1/download. No se realiza ninguna conversión en este paso.

Parámetros de la solicitud

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Authorization`	header	string	Sí	Su clave de API.
`file`	form-data	file	Sí	`.ofx`, `.qfx` o `.qbo`, hasta 10 MB.

Ejemplo de solicitud

curl -X POST "https://www.ofxconverter.com/api/v1/upload" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.ofx"

Ejemplo de respuesta

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "ofx",
  "filename": "statement"
}

get /api/v1/download

Convierte un archivo almacenado previamente con POST /api/v1/upload. El archivo debe pertenecer a la cuenta autenticada.

Parámetros de la solicitud

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Authorization`	header	string	Sí	Su clave de API.
`fileID`	query	string (GUID)	Sí	ID devuelto por `/upload`.
`output`	query	string	No	`csv`, `excel`, u omítalo para JSON.

Ejemplo de solicitud

curl "https://www.ofxconverter.com/api/v1/download?fileID=3f2504e0-4f89-41d3-9a0c-0305e82c3301&output=csv" \
  -H "Authorization: YOUR_API_KEY"

Ejemplo de respuesta

El cuerpo de la respuesta tiene la misma forma que POST /api/v1/conversion. Además de los errores de autenticación, download devuelve NO_FILE_ID cuando falta fileID y FILE_NOT_FOUND cuando no existe un archivo coincidente para su cuenta (ambos con HTTP 401).

post /api/v1/pdf/conversion beta

Convierte un extracto bancario en PDF. Los extractos de bancos compatibles se analizan directamente; los demás recurren a OCR y extracción con IA, por lo que los resultados pueden variar. Este endpoint es experimental y puede cambiar.

Parámetros de la solicitud

Nombre	Ubicación	Tipo	Obligatorio	Descripción
`Authorization`	header	string	Sí	Su clave de API.
`file`	form-data	file	Sí	`.pdf`, hasta 10 MB.
`output`	form-data	string	No	`csv`, `excel`, u omítalo para JSON.

Ejemplo de solicitud

curl -X POST "https://www.ofxconverter.com/api/v1/pdf/conversion" \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@statement.pdf"

Ejemplo de respuesta (json)

{
  "error": false,
  "message": "SUCCESS",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "pdf",
  "filename": "statement.pdf",
  "convertedFile": {
    "transactions": [
      {
        "date": "2024-01-05T00:00:00",
        "value": -42.5,
        "description": "Coffee Shop",
        "type": "DEBIT"
      }
    ]
  }
}

Esquema de respuesta

Para la salida JSON, los endpoints de conversión OFX y de descarga devuelven el extracto extraído en convertedFile con la siguiente estructura.

Campo	Tipo	Descripción
`header.bankName`	string	Nombre del banco según el extracto.
`header.currency`	string	Moneda del extracto (p. ej. `USD`).
`header.serverDate`	datetime	Fecha reportada por el servidor del banco.
`header.hasInvestiment`	boolean	`true` cuando el extracto contiene transacciones de inversión.
`bankAccount.type`	string	Tipo de cuenta (p. ej. `CHECKING`).
`bankAccount.bank.code`	integer	Código del banco.
`bankAccount.accountCode`	string	Número de cuenta.
`initialDate` / `finalDate`	datetime	Período del extracto.
`transactions[]`	array	Lista de transacciones (ver más abajo).
`transactions[].date`	datetime	Fecha de la transacción.
`transactions[].value`	number	Importe (negativo para débitos).
`transactions[].type`	string	Tipo de transacción.
`transactions[].description`	string	Descripción de la transacción.
`transactions[].id`	string	Identificador de la transacción en el archivo.
`transactions[].checksum`	integer	Checksum usado para detectar duplicados.
`transactions[].units` / `price` / `comission`	number	Campos de inversión; `null` para transacciones normales.
`transactions[].secName` / `ticker`	string	Nombre del valor y ticker para transacciones de inversión.

El endpoint de PDF devuelve una forma más simple: convertedFile.transactions[] con date, value, description y type.

Respuestas de error

Los errores devuelven un cuerpo JSON con "error": true y un código message. Los errores relacionados con archivos también repiten fileID, extension y filename.

{
  "error": true,
  "message": "FILE_NOT_SUPPORTED",
  "fileID": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "extension": "txt",
  "filename": "statement.txt"
}

Mensaje	Estado HTTP	Significado
`NO_API_KEY`	401	Falta el encabezado `Authorization`.
`UNAUTHORISED`	401	Clave inválida, o la cuenta no es premium.
`NO_FILE_ID`	401	`download` se llamó sin un `fileID`.
`FILE_NOT_FOUND`	401	No existe ningún archivo con ese `fileID` para su cuenta.
`FILE_NOT_UPLOADED`	400	No se incluyó ningún archivo en la solicitud.
`FILE_NOT_SUPPORTED`	400	La extensión del archivo no es aceptada por este endpoint.
`FILE_TOO_BIG`	400	El archivo supera el límite de 10 MB.
`BAD_FILE_FORMAT`	400	El archivo no pudo procesarse (p. ej. un archivo OFX inválido).
`SERVER_ERROR`	400	Se produjo un error inesperado al procesar el archivo.