Verificar un comprobante

Registra un comprobante y devuelve el veredicto. Pasa por la misma cadena que el bot propio de Verifika: candado de la cuenta → plan → cupo → duplicado → cruce con el aviso del banco. Consume una verificación del cupo mensual salvo que resulte duplicado. El pago nace PENDING, nunca VERIFIED: solo el cruce con el aviso real del banco puede confirmarlo. Si el banco ya había avisado, el cruce ocurre en esta misma llamada y el ingreso vuelve verificado.

Autorización

apiKey verifications.write

AutorizaciónBearer <token>

La llave del negocio, creada en el panel: Integraciones → API pública. Formato vk_live_… (o vk_test_… fuera de producción).

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 (plan Multi); 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.

Cuerpo de la petición

application/json

Tipos de TypeScript

Usa el tipo request body en TypeScript.

phone*string

Quién reporta el pago, en formato internacional (+57…). Tiene que ser un teléfono del equipo del negocio — el dueño, un supervisor o un cajero. Es lo que ata el movimiento a una persona y a una sucursal. Se tolera con o sin + y con separadores.

amount*integer

Cuánto dice el comprobante, en pesos enteros. Es uno de los tres datos con los que se cruza contra el aviso del banco.

reference?string

La referencia del comprobante. Es la llave anti-duplicados: con ella detectamos que el mismo comprobante se está usando dos veces. Sin ella no podemos — dos ventas de $20.000 el mismo día son legítimas. Mándala siempre que puedas extraerla.

occurredAt?string

Cuándo dice el comprobante que se hizo el pago, en ISO 8601 con zona horaria. Si no la mandas se usa el momento de la llamada, y el cruce con el banco pierde precisión.

Formatodate-time

customerName?string

Quién pagó, según el comprobante. Queda en el libro para que el dueño lo reconozca.

bankLabel?string

De qué banco o billetera salió: «Nequi», «Bancolombia».

accountLabel?string

A qué cuenta del negocio entró: «Nequi *4821».

imageUrl?string

URL pública de la imagen del comprobante. La descargamos y la copiamos a nuestro almacenamiento, así que no dependemos de que tu enlace siga vivo. Si la descarga falla, el pago se registra igual y te lo decimos en attachment.stored.

Formatouri

Cuerpo de la respuesta

`application/json`

curl -X POST "https://example.com/verifications" \  -H "Content-Type: application/json" \  -d '{    "phone": "+573001112233",    "amount": 45000,    "reference": "M1A2B3C4",    "customerName": "Juan Pérez",    "bankLabel": "Nequi",    "imageUrl": "https://tu-cdn.com/comprobante.jpg"  }'

{  "outcome": "DUPLICATE",  "business": {    "companyId": "cmt7xbfrg0001q3w1itst7uwo",    "companyName": "Panadería Delipan"  },  "income": null,  "duplicateOf": {    "id": "cmtj0000000000000000000",    "status": "VERIFIED",    "amount": 45000,    "reference": "M1A2B3C4"  }}

Verificar un comprobante

Autorización

Parámetros de consulta

Parámetros de cabecera

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

201application/json

400application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`