VerifikaDocs
ReferenciaVerificaciones

Verificar un comprobante

Mandas la imagen del comprobante (imageUrl o imageBase64) y Verifika la lee con IA, busca duplicados, la cruza contra el aviso del banco del negocio y devuelve el veredicto con un message listo para reenviarle a quien pagó.

  • 201 VERIFIED: el banco ya había avisado.
  • 201 PENDING: registrado y esperando al banco (AWAITING_BANK) o a una persona (AWAITING_REVIEW). Cuando se resuelva llega el webhook verification.verified o verification.not_found, con tu metadata.
  • 200 DUPLICATE o REJECTED: no se registró nada y no consume cupo.

Consume una verificación del cupo mensual solo cuando queda registrada. Si mandas amount, se usa el contrato de datos de siempre: no se lee la imagen y la respuesta es la forma anterior (outcome, business, income, attachment) más verificationId y livemode.

Con una llave de prueba (vk_test_) la lectura con IA es real pero el veredicto es simulado (valores mágicos en reference) y nada toca el libro. Ver «Verifica desde tu propio bot» y «Modo de prueba».

POST
/verifications

Autorización

apiKey verifications.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: verifications.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

application/json

Tipos de TypeScript

Usa el tipo request body en TypeScript.

Elige una de tres formas. Lo obligatorio va marcado con asterisco (*); todo lo demás es opcional. Con la imagen (URL o base64) basta: la IA lee el resto. Si mandas amount, se usa el contrato de datos.

Lo único obligatorio es imageUrl. La IA lee monto, referencia, banco, fecha y quién pagó. Todo 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/verifications" \  -H "Content-Type: application/json" \  -d '{    "imageUrl": "https://cdn.tubot.com/comprobantes/7f3a.jpg",    "expectedAmount": 85000,    "reporter": {      "phone": "+573104567890",      "name": "Laura Restrepo",      "externalId": "wa_573104567890"    },    "metadata": {      "chatId": "wa_573104567890",      "pedido": "PED-10293"    }  }'

{  "object": "verification",  "id": "vrf_3f9a1c0e7b2d4e8fa61c5d90b7e24a13",  "livemode": true,  "status": "DUPLICATE",  "code": "DUPLICATE",  "message": "Este comprobante por $85.000 ya se había usado el 11 oct, 3:12 p. m., así que no lo podemos contar otra vez. Si es un pago nuevo, mándanos su comprobante.",  "mode": "IMAGE",  "companyId": "cmt7xbfrg0001q3w1itst7uwo",  "createdAt": "2026-10-12T20:00:06.000Z",  "updatedAt": "2026-10-12T20:00:06.000Z",  "resolvedAt": "2026-10-12T20:00:05.000Z",  "extracted": {    "isReceipt": true,    "amount": 85000,    "reference": "M48213907",    "bankLabel": "Nequi",    "accountLabel": "Nequi ··4821",    "occurredAt": "2026-10-12T19:58:00.000Z",    "customerName": "Laura Restrepo",    "confidence": 0.96,    "note": null  },  "income": null,  "duplicate": {    "level": "CERTAIN",    "evidence": "EXACT_FILE",    "duplicateOf": {      "id": "cmug9x2b10017x8w1k3r5t7yu",      "status": "VERIFIED",      "origin": "API",      "amount": 85000,      "occurredAt": "2026-10-11T20:12:00.000Z",      "reference": "M48213907",      "bankLabel": "Nequi",      "accountLabel": "Nequi ··4821",      "customerName": "Laura Restrepo",      "verifiedAt": "2026-10-11T20:13:41.000Z"    }  },  "reporter": {    "phone": "+573104567890",    "name": "Laura Restrepo",    "externalId": "wa_573104567890"  },  "metadata": {    "chatId": "wa_573104567890",    "pedido": "PED-10293"  },  "receipt": {    "stored": true,    "source": "URL",    "contentType": "image/jpeg",    "size": 182340,    "sha256": "9c1e5f2a7b3d4c6e8f0a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f6a"  },  "nextStep": null,  "warnings": []}

Plan y consumo GET

Plan actual, funciones incluidas, límites y verificaciones consumidas en el mes. Sirve para que un bot pregunte «¿esta cuenta todavía puede verificar?» antes de pedirle la foto al cliente.

Ver una verificación GET

Una verificación con su estado **de ahora** (y el ingreso como está hoy). Es la red de seguridad si se te perdió un webhook.