Per sviluppatori

Documentazione API

Riferimento per caricare, elaborare e scaricare un estratto conto in Excel in modo programmatico.

Prossimamente

Chiavi API

Creerai le chiavi dalla tua dashboard e chiamerai gli endpoint qui sotto dal tuo server. Questa pagina mostra l'API come funzionerà al lancio.

Richiedi l'accesso anticipato

Autenticazione

Invia la tua chiave API nell'intestazione Authorization di ogni richiesta. Conservala sul tuo server, mai in un browser o in un'app mobile.

Authorization: Bearer <your_api_key>

URL di base

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

POST/upload/preview

Anteprima prima del caricamento

Classifica ogni pagina (digitale o scansionata) e calcola il costo esatto in pagine. Non viene addebitato nulla.

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

Risposta

{
  "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

Caricare un estratto conto

Carica un PDF per avviare l'estrazione. L'estratto conto parte dallo stato pending e passa automaticamente per processing.

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

Risposta

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

GET/statements/{id}

Ottenere un estratto conto e le sue transazioni

Usalo per sapere quando termina l'elaborazione e per ottenere le transazioni e i saldi estratti.

Nota: Interroga questo endpoint ogni pochi secondi finché lo stato passa da processing a completed (o failed).

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

Risposta

{
  "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
    }
  ]
}

Campi della transazione

datestring

Data della transazione, AAAA-MM-GG.

descriptionstring

Di che transazione si tratta, senza i numeri di riferimento.

debitnumber

Denaro in uscita. Sempre positivo, 0 se assente.

creditnumber

Denaro in entrata. Sempre positivo, 0 se assente.

balancenumber

Saldo progressivo stampato su quella riga. Negativo in caso di scoperto.

categorystring

Categoria di spesa, ad esempio grocery, transfer o fuel.

referencestring | null

Il riferimento della banca, se stampato.

page_numberinteger

La pagina del PDF da cui proviene la riga.

GET/statements

Elencare i tuoi estratti conto

Restituisce tutti gli estratti conto collegati al tuo account, dal più recente.

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

Risposta

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

GET/download/{id}/{format}

Scaricare il file

Disponibile solo quando lo stato è completed. I formati inclusi nel tuo piano sono elencati in available_exports.

excelcsvqboquickbooksxmlodoozohomt940camt053iif

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

Risposta

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

DELETE/statements/{id}

Eliminare un estratto conto

Elimina l'estratto conto, le sue transazioni e i suoi file. L'operazione non può essere annullata.

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

Risposta

HTTP/1.1 204 No Content

Valori di stato possibili

StatoSignificato

pending

Ricevuto, sta per iniziare.

queued

In attesa di uno slot libero.

processing

Estrazione in corso.

completed

Transazioni e file sono pronti.

failed

Impossibile elaborare. Il motivo è in error_message.

Domande sull'integrazione?

Contattaci