Para desarrolladores

Documentación de la API

Referencia para subir, procesar y descargar un extracto bancario en Excel de forma programática.

Próximamente

Claves de API

Crearás claves desde tu panel y llamarás a los endpoints de abajo desde tu servidor. Esta página muestra la API tal como funcionará en el lanzamiento.

Solicitar acceso anticipado

Autenticación

Envía tu clave de API en el encabezado Authorization de cada solicitud. Guárdala en tu servidor, nunca en un navegador ni en una aplicación móvil.

Authorization: Bearer <your_api_key>

URL base

https://api.bayainy.com/api/v1

POST/upload/preview

Vista previa antes de subir

Clasifica cada página (digital o escaneada) y calcula el coste exacto en páginas. No se cobra nada.

POST /upload/preview HTTP/1.1
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data
 
file: statement.pdf

Respuesta

{
  "page_count": 3,
  "digital_pages": 2,
  "scanned_pages": 1,
  "credit_cost": 4,
  "pages": [
    { "page": 1, "type": "digital" },
    { "page": 2, "type": "digital" },
    { "page": 3, "type": "scanned" }
  ]
}

POST/upload

Subir un extracto

Sube un PDF para iniciar la extracción. El extracto empieza en estado pending y pasa por processing automáticamente.

POST /upload HTTP/1.1
Authorization: Bearer <your_api_key>
Content-Type: multipart/form-data
 
file: statement.pdf

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "statement.pdf",
  "status": "pending",
  "page_count": 3,
  "estimated_seconds": 6
}

GET/statements/{id}

Obtener un extracto y sus transacciones

Úsalo para saber cuándo termina el procesamiento y para recuperar las transacciones y los saldos extraídos.

Nota: Consulta este endpoint cada pocos segundos hasta que el estado pase de processing a completed (o failed).

GET /statements/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Authorization: Bearer <your_api_key>

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "bank_name": "Al Rajhi Bank",
  "transaction_count": 42,
  "opening_balance": 12480.00,
  "closing_balance": 24755.00,
  "available_exports": ["excel", "csv", "qbo", "xml"],
  "transactions": [
    {
      "date": "2026-09-01",
      "description": "Card purchase, Panda",
      "debit": 184.50,
      "credit": 0.00,
      "balance": 12295.50,
      "category": "grocery",
      "reference": "FT26244S1K7Q",
      "page_number": 1
    }
  ]
}

Campos de la transacción

datestring

Fecha de la transacción, AAAA-MM-DD.

descriptionstring

Qué fue la transacción, sin los números de referencia.

debitnumber

Dinero que sale. Siempre positivo; 0 si no hay.

creditnumber

Dinero que entra. Siempre positivo; 0 si no hay.

balancenumber

Saldo corriente impreso en esa fila. Negativo si la cuenta está en descubierto.

categorystring

Categoría del gasto, por ejemplo grocery, transfer o fuel.

referencestring | null

La referencia propia del banco, cuando aparece impresa.

page_numberinteger

La página del PDF de la que procede la fila.

GET/statements

Listar tus extractos

Devuelve todos los extractos vinculados a tu cuenta, del más reciente al más antiguo.

GET /statements HTTP/1.1
Authorization: Bearer <your_api_key>

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "filename": "statement.pdf",
    "status": "completed",
    "transaction_count": 42
  }
]

GET/download/{id}/{format}

Descargar el archivo

Solo disponible cuando el estado es completed. Los formatos que incluye tu plan aparecen en available_exports.

excelcsvqboquickbooksxmlodoozohomt940camt053iif

GET /download/550e8400-e29b-41d4-a716-446655440000/excel HTTP/1.1
Authorization: Bearer <your_api_key>

Respuesta

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
 
<binary .xlsx file>

DELETE/statements/{id}

Eliminar un extracto

Elimina el extracto, sus transacciones y sus archivos. No se puede deshacer.

DELETE /statements/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Authorization: Bearer <your_api_key>

Respuesta

HTTP/1.1 204 No Content

Valores de estado posibles

EstadoSignificado

pending

Recibido, a punto de empezar.

queued

Esperando un hueco libre.

processing

La extracción está en curso.

completed

Las transacciones y los archivos están listos.

failed

No se pudo procesar. El motivo está en error_message.

¿Preguntas sobre la integración?

Contáctanos