Conciliación

Cómo se ingieren, deduplican, atribuyen y exponen como transacciones las ventas de terminal con tarjeta presente — incluidas anulaciones, reembolsos y metadata de punto de venta.

Las ventas con tarjeta presente se originan en la terminal, así que Vecnet las ingiere en lugar de iniciarlas. La conciliación es por capas para que ninguna venta se pierda: una ruta en tiempo real y un barrido periódico convergen en la misma transacción, con el mismo ID determinista.

Rutas de ingestión

Ruta	Qué hace
Tiempo real	Cada venta llega a Vecnet conforme ocurre. Es la ruta rápida.
Proceso de conciliación	Un trabajo programado revisa periódicamente las ventas recientes e inserta lo que la ruta en tiempo real haya omitido. Es la red de seguridad.
Sincronización manual	Desde el panel se puede disparar una conciliación bajo demanda para un comercio.

Como todas las rutas insertan por el mismo ID de transacción determinista, una venta que llega dos veces (una en tiempo real y otra por el proceso periódico) se registra una sola vez. La ingestión es idempotente.

El registro de la transacción

Una venta de terminal se convierte en una fila de transactions en el riel inperson_cp:

{
  "id": "txn_9f3c2a71",
  "rail": "inperson_cp",
  "terminal_id": "trm_6b5a49c2",
  "merchant_id": "mrc_3f9a2c1b",
  "payment_method": "card",
  "status": "approved",
  "amount_cents": 39000,
  "currency": "MXN",
  "card": { "brand": "visa", "last4": "4242" },
  "metadata": {
    "terminal_serial": "TRM-DEMO-0001",
    "ticket_id": "T-000842",
    "authorization_code": "A1B2C3",
    "operation_type": "PAYMENT",
    "input_mode": "contactless",
    "installments": 1,
    "operator_email": "cajero@tienda.example.com",
    "local_datetime": "2026-06-22T08:30:00"
  },
  "created_at": "2026-06-22T14:30:00.000Z"
}

Los números de tarjeta y los CVV nunca se guardan. Solo se conservan la marca y los últimos cuatro dígitos, junto con metadata de punto de venta no sensible.

Metadata de punto de venta

El objeto metadata lleva el detalle de punto de venta que solo existe en ventas con tarjeta presente, útil para cruzarlo con los reportes de tu propio sistema de caja:

Campo	Descripción
`terminal_serial`	El número de serie del dispositivo.
`ticket_id`	El número de ticket o recibo del punto de venta.
`authorization_code`	El código de autorización de la venta.
`operation_type`	`PAYMENT`, `REFUND`, `ANNULMENT`, etcétera.
`input_mode`	Cómo se leyó la tarjeta (chip, contactless, banda).
`installments`	Número de meses sin intereses (MSI), si aplica.
`operator_email`	El cajero u operador que realizó la venta.
`local_datetime`	La hora local que mostraba la terminal.

Leer transacciones de terminal

Filtra la lista de transacciones por riel y, opcionalmente, por terminal:

# Todas las ventas presenciales de un comercio
curl "https://api.vecnet.io/api/transactions?rail=inperson_cp&order=created_at&dir=desc" \
  -H "Authorization: Token vk_live_1a2b3c4d5e6f7a8b9c0d"

# Solo una terminal
curl "https://api.vecnet.io/api/transactions?rail=inperson_cp&terminal_id=trm_6b5a49c2" \
  -H "Authorization: Token vk_live_1a2b3c4d5e6f7a8b9c0d"

Anulaciones y reembolsos

Una venta que se anula o se reembolsa en la terminal produce un segundo registro que comparte la identidad de la venta original. Vecnet resuelve el estado final con una precedencia simple, para que la transacción nunca muestre un resultado más débil que el que alcanzó:

chargeback  >  refunded  =  cancelled  >  declined  >  approved  >  pending

Así, una venta aprobada y después anulada se concilia en una sola transacción cuyo estado refleja la anulación, no la aprobación original.

Recibir notificaciones

Suscríbete a webhooks para reaccionar a las ventas de terminal conforme se registran: payment.approved, payment.declined, payment.cancelled, payment.failed y payment.refunded. El webhook lleva la misma forma de transacción mostrada arriba.

Si una venta esperada nunca aparece, la causa más común es que la terminal no quedó configurada por completo, así que la venta nunca se notificó. El proceso de conciliación y una sincronización manual desde el panel son las rutas de recuperación.