VerifikaDocs
ReferenciaIngresos

Declarar un ingreso

Anota un pago en el libro. Nace DECLARED: editable, borrable y sin consumir cupo de verificaciones — nadie pidió verificar nada. No confundir con POST /v1/verifications, que sí verifica y sí consume. Son dos intenciones distintas: esta es para sincronizar lo que ya sabes; aquella, para preguntar si un pago es real.

POST
/incomes

Autorización

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

Cuerpo de la respuesta

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/incomes" \  -H "Content-Type: application/json" \  -d '{    "amount": 45000,    "occurredAt": "2026-09-04T15:00:00.000Z",    "customerName": "Juan Pérez",    "reference": "TX-9912",    "bankLabel": "Nequi"  }'
{  "object": "income",  "id": "cmtnoxo4s00066kw1mgbyuzdd",  "amount": 45000,  "currency": "COP",  "status": "DECLARED",  "origin": "DECLARED",  "occurredAt": "2026-09-04T15:00:00.000Z",  "createdAt": "2026-09-04T15:02:11.104Z",  "verifiedAt": null,  "reference": "TX-9912",  "customerName": "Juan Pérez",  "bankLabel": "Nequi",  "accountLabel": null,  "duplicateOfId": null,  "branch": {    "id": "cmt7xbfrj0002q3w1iq4ysatr",    "name": "Principal"  },  "confirmedBy": {    "id": null,    "name": "ERP del contador",    "phone": null  },  "attachments": [],  "bankChannels": []}

Verificar un comprobante POST

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.

Eliminar un ingreso declarado DELETE

Solo ingresos DECLARED. Borra también sus comprobantes del almacenamiento.