VerifikaDocs
ReferenciaConciliación bancaria

Subir un extracto

Sube el extracto del banco y lo cruza contra el libro. La petición espera la lectura hasta 20 s: si alcanza, 201 con el extracto leído y cruzado; si no (un PDF escaneado, por ejemplo), 202 con status: processing, Location y Retry-After: 10, y la lectura sigue. Al terminar sale el webhook bank_statement.processed (o bank_statement.failed). async: true contesta 202 de una vez.

«No cuadra con el resumen del banco» no es un error: el extracto se guarda con verdict: MISMATCH, difference y checks.

No funciona con llaves de prueba (403 TEST_MODE_UNAVAILABLE).

POST
/bank-statements

Autorización

apiKey reconciliation.write
AutorizaciónBearer <token>

La llave del negocio, creada en el panel: Integraciones → API pública. vk_live_… es una llave real; vk_test_…, una llave de modo prueba (verificaciones simuladas, nada toca el libro real). Ver la guía «Modo de prueba».

Va en: header

Permiso: reconciliation.write

Parámetros de consulta

companyId?string

Sobre qué negocio actúa la petición. Obligatorio solo si la llave entra a varios negocios; con uno solo, se deduce.

Parámetros de cabecera

Idempotency-Key?string

Llave única de la operación. Un reintento con la misma llave y el mismo cuerpo devuelve la respuesta original en vez de volver a ejecutar. Ver la guía de idempotencia.

Longitudlength <= 255

Cuerpo de la petición

Tipos de TypeScript

Usa el tipo request body en TypeScript.

Una sola forma por petición: multipart/form-data con el campo file, fileBase64 + fileName, o fileUrl. Tope: 15 MB.

Elige una de dos formas (o usa multipart con file). Lo obligatorio va con asterisco (*).

Obligatorio: fileUrl (https pública). Lo demás es opcional.

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/bank-statements" \  -H "Content-Type: application/json" \  -d '{    "fileUrl": "https://drive.tuerp.com/extractos/2026-09.pdf",    "paymentAccountId": "cmt7xbfs10005q3w1u8k2c9va"  }'
{  "object": "bankStatement",  "id": "cmuh8q2r70044x8w1b6n3m1kd",  "status": "processed",  "fileName": "extracto-bancolombia-septiembre.pdf",  "format": "PDF",  "kind": "ACCOUNT",  "bank": {    "key": "bancolombia",    "name": "Bancolombia"  },  "accountLast4": "8300",  "accountType": "AHORROS",  "paymentAccount": {    "id": "cmt7xbfs10005q3w1u8k2c9va",    "provider": "BANCOLOMBIA",    "alias": "Ahorros principal",    "last4": "8300"  },  "currency": "COP",  "periodStart": "2026-09-01",  "periodEnd": "2026-09-30",  "pages": 3,  "verdict": "VERIFIED",  "balances": {    "opening": 1250000,    "closing": 3184520.37  },  "totals": {    "credits": 4872300,    "debits": 2937779.63,    "lineCount": 64  },  "bankSummary": {    "opening": 1250000,    "closing": 3184520.37,    "credits": 4872300,    "debits": 2937779.63,    "gmf": 11751.12,    "yields": 412.5,    "interest": null,    "fees": 14280  },  "difference": {    "closingBalance": 0,    "credits": 0,    "debits": 0  },  "checks": [    {      "key": "balance",      "label": "Saldo final",      "status": "PASS",      "expected": 3184520.37,      "actual": 3184520.37,      "detail": "El saldo inicial más los movimientos da el saldo final del banco."    }  ],  "warnings": [],  "hasOriginal": true,  "matchedAt": "2026-10-12T21:03:11.000Z",  "createdAt": "2026-10-12T21:03:02.000Z",  "progress": {    "total": 64,    "resolved": 51,    "pending": 13,    "percentResolved": 80  },  "groups": {    "matched": {      "count": 38,      "amount": 4104300    },    "registered": {      "count": 0,      "amount": 0    },    "bankFees": {      "count": 13,      "amount": 26443.62    },    "ignored": {      "count": 0,      "amount": 0    },    "missingIncomes": {      "count": 6,      "amount": 768000    },    "missingExpenses": {      "count": 7,      "amount": 1843200    },    "onlyInVerifika": {      "count": 2,      "amount": 95000    }  },  "onlyInVerifika": {    "object": "list",    "data": [      {        "incomeId": "cmufa1b2c0009x8w1q4w5e6rt",        "amount": 45000,        "occurredAt": "2026-09-18T15:02:00.000Z",        "day": "2026-09-18",        "customerName": "Juan Pérez",        "status": "VERIFIED",        "origin": "WHATSAPP",        "reference": "M1A2B3C4",        "bankLabel": "Nequi",        "accountLabel": "Ahorros *8300",        "seenByBank": true      }    ],    "hasMore": true  },  "deductions": {    "fee": 0,    "feeTax": 0,    "withholding": 0  },  "bankFeeCategories": [    "GMF",    "CUOTA_MANEJO",    "RENDIMIENTOS"  ],  "passwordRemembered": false,  "usedSavedPassword": false}

Crear el gasto de una lectura POST

Crea el gasto con lo leído, más tus correcciones en `expense`, con la factura adjunta. **Un escaneo crea un gasto**: repetirlo devuelve el mismo (`200`).

Ver un extracto GET

El extracto leído (resumen completo: cuadre, % resuelto, grupos, lo que solo está en Verifika), leyéndose (`processing`, con `Retry-After`) o fallido (`failed`, con el `error` que habría dado la subida). Una lectura con más de 15 min «procesando» se cortó: pasa a `failed` con `PROCESSING_INTERRUPTED`.