Glosario, identificadores y convenciones

Estado documental: Contrato propuesto. Esta página define el vocabulario y las convenciones utilizadas en toda la documentación de YUPY.

Objetivo

El glosario evita que dos equipos utilicen palabras iguales con significados distintos y establece convenciones procesables para IDs, montos, fechas, estados y respuestas.

Glosario

Término	Definición
Empresa	Organización que utiliza YUPY para cobrar y conciliar. Recibe el dinero directamente en su cuenta.
Integración	Configuración que identifica a una empresa, sus credenciales, ambientes, capacidades y webhooks.
Perfil de cobro	Configuración comercial que determina opciones de pago, moneda, presentación y valores efectivos.
Orden de pago	Recurso canónico que representa la intención de cobrar una operación comercial.
Operación	Venta, reserva, pedido, pasaje, servicio u otra transacción comercial vinculada con una orden.
Web Checkout	Experiencia temporal para que el comprador visualice opciones de pago y el estado de la operación.
Sesión de checkout	Acceso temporal y limitado a una orden. Puede vencer o ser revocado sin eliminar la orden.
POS vía chat	Experiencia operativa que utiliza un chat autorizado para crear y atender cobros.
POS integrado	Integración directa entre YUPY y un sistema POS. Es diferente de POS vía chat.
Turno	Periodo operativo asociado con un usuario y, cuando corresponda, un dispositivo.
Dispositivo	Equipo autorizado que puede recibir operaciones o instrucciones.
Usuario	Persona autorizada con permisos definidos dentro de la empresa.
Entrega	Intento de enviar instrucciones, información o un evento a un receptor.
Evidencia	Captura, fotografía, constancia u otro archivo aportado para apoyar la verificación.
OCR	Procesamiento que extrae información visible de una imagen. No confirma por sí solo un pago.
Conciliación	Relación entre una operación y el ingreso identificado en una cuenta autorizada.
Caso pendiente	Recurso operativo que registra una situación que requiere atención o decisión.
Diferencia de monto	Situación en la que el importe identificado no coincide con el esperado.
Pago tardío	Ingreso identificado después del vencimiento, cancelación o cierre operativo.
Devolución	Proceso que la empresa revisa y ejecuta para retornar dinero cuando corresponde. YUPY organiza y registra el caso.
Webhook	Notificación server-to-server enviada a un endpoint de la empresa.
Evento	Hecho canónico con un `event_id` único que puede generar una o más entregas.
Entrega de webhook	Intento individual de enviar un evento a un receptor.
Reporte	Vista o archivo que resume información operativa, financiera o de auditoría.
Trabajo de reporte	Proceso asíncrono utilizado para generar una exportación grande.
Sandbox	Ambiente de prueba que no mueve dinero real.
Producción	Ambiente que procesa operaciones y configuraciones reales.

Diferencias críticas

Orden y sesión

payment_order
≠ checkout_session

Una orden puede tener varias sesiones temporales.

Pago informado y pago conciliado

payment_reported
≠ reconciled

Informar que se pagó inicia o refuerza la verificación. No confirma el ingreso.

Evidencia y confirmación financiera

evidence_received
≠ payment_reconciled

POS vía chat y POS integrado

POS vía chat
≠ integración con un sistema POS

Evento y entrega

webhook_event
≠ webhook_delivery

Un evento puede tener varios intentos de entrega sin convertirse en varios eventos comerciales.

Caso y orden

pending_case
≠ payment_order

El caso conserva el problema operativo; la orden conserva la intención de cobro.

Identificadores

Identificador	Responsable	Uso
`external_transaction_id`	Empresa	Identidad comercial estable de la operación dentro del sistema de la empresa.
`payment_order_uid`	YUPY	Identidad canónica de la orden dentro de YUPY.
`checkout_session_id`	YUPY	Identidad de una sesión temporal de Web Checkout.
`shift_id`	YUPY o integración	Identidad de un turno operativo.
`device_id`	YUPY	Identidad de un dispositivo registrado.
`user_id`	YUPY o empresa	Identidad de un usuario autorizado según el recurso.
`delivery_id`	YUPY	Identidad de una entrega operativa.
`evidence_id`	YUPY	Identidad de una evidencia.
`case_id`	YUPY	Identidad de un caso pendiente.
`refund_case_id`	YUPY	Identidad de un caso de devolución.
`event_id`	YUPY	Identidad única de un evento.
`webhook_endpoint_id`	YUPY	Identidad de un receptor configurado.
`webhook_delivery_id`	YUPY	Identidad de un intento de entrega de webhook.
`request_id`	YUPY	Trazabilidad de una solicitud y su respuesta.
`report_job_id`	YUPY	Identidad de un trabajo de reporte.

Idempotency-Key

Idempotency-Key identifica técnicamente una intención reintentable.

external_transaction_id
→ identidad comercial

payment_order_uid
→ identidad canónica en YUPY

Idempotency-Key
→ identidad técnica del intento reintentable

request_id
→ trazabilidad de una solicitud

event_id
→ identidad única de un evento

La misma intención utiliza la misma clave y el mismo payload. Una intención nueva utiliza otra clave.

Montos y monedas

{
  "amount": "85.50",
  "currency": "PEN"
}

Los montos se representan como cadenas decimales.
No deben enviarse como números de punto flotante.
La moneda utiliza un código documentado, por ejemplo PEN.
La cantidad de decimales debe cumplir las reglas de la moneda y del endpoint.

Fechas y horas

2026-07-20T18:00:00-05:00

Las fechas y horas utilizan ISO 8601.
Los valores operativos deben incluir zona horaria o utilizar UTC cuando el contrato lo indique.
Una fecha sin hora no debe utilizarse cuando el orden temporal sea relevante.

Campos opcionales, null y cadenas vacías

Representación	Significado
Campo omitido	El dato no fue proporcionado o no se solicita en ese contexto.
`null`	El campo forma parte de la respuesta, pero no existe un valor disponible o aplicable según el schema.
Cadena vacía	Debe evitarse salvo que el contrato del campo la permita expresamente.

El cliente no debe convertir automáticamente null en cero, falso o cadena vacía.

Booleanos

true
false

No deben utilizarse cadenas como "true" o "false" salvo que el schema del endpoint lo establezca.

Listas y objetos

Una lista vacía se representa como [].
Un objeto vacío se representa como {} solo cuando sea válido.
El orden de los campos JSON no tiene significado contractual.
El orden de una lista solo es significativo cuando la documentación lo indique.

Paginación

{
  "data": [],
  "pagination": {
    "page": 1,
    "page_size": 50,
    "total_items": 0,
    "total_pages": 0
  },
  "request_id": "req_01JXYZ"
}

Los límites máximos y valores predeterminados permanecen propuestos hasta su publicación.

Nombres y formatos

snake_case
→ estados, campos y códigos de error

payment.reconciled
→ tipos de evento

/v1/payment-orders
→ rutas versionadas

Idempotency-Key
→ header HTTP

Referencias personalizadas

El objeto context puede incluir referencias propias de la empresa:

{
  "context": {
    "custom_reference_1": "RUTA-184",
    "custom_reference_2": "ASIENTO-12A"
  }
}

Estas referencias ayudan a la trazabilidad. No sustituyen a external_transaction_id.

Campos desconocidos

Para cambios compatibles, el cliente debe ignorar campos desconocidos que no necesite, sin borrar ni reinterpretar los campos conocidos.

Un valor desconocido de estado o código no debe tratarse como éxito automático.

Criterios de aceptación documental

Los conceptos principales tienen una definición única.
Orden y sesión permanecen separadas.
Pago informado, evidencia y conciliación no se confunden.
POS vía chat y POS integrado permanecen separados.
Evento y entrega tienen identificadores distintos.
Los IDs de la empresa y de YUPY tienen responsabilidades claras.
Los montos utilizan cadenas decimales.
Las fechas utilizan ISO 8601.
Omitido, null y cadena vacía no se tratan como equivalentes.
Las referencias personalizadas no sustituyen la identidad comercial.

Identificadores de Payment Order

Para el contrato público de Payment Orders deben mantenerse separados tres conceptos:

Identificador	Quién lo genera	Uso
`external_transaction_id`	Sistema del cliente	Identidad comercial estable de la operación en el sistema origen.
`Idempotency-Key`	Caller	Controla reintentos técnicos de una operación HTTP/API y evita duplicados involuntarios.
`payment_order_uid`	YUPY	Identidad canónica de la Payment Order dentro de YUPY y de punta a punta entre sus eventos y operaciones.

Idempotency-Key no sustituye a external_transaction_id. Del mismo modo, payment_order_uid no es el ID comercial del sistema origen: es el identificador canónico que genera YUPY.

Convención propuesta

external_transaction_id = "ORDER-10482"
Idempotency-Key = "8e2d7c1b-..."
payment_order_uid = "pay_01JXYZ..."

La palabra “transacción” puede seguir utilizándose cuando se hable de una transacción financiera real o de una referencia externa. El cambio de nomenclatura aplica específicamente a la identidad canónica pública de la Payment Order.

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: se renombró la identidad canónica pública yupy_transaction_id a payment_order_uid; se mantuvieron separados external_transaction_id e Idempotency-Key; se documentó explícitamente que el cambio no implica reemplazar indiscriminadamente la palabra “transacción” cuando se refiere a transacciones financieras u otros conceptos distintos de la Payment Order.

API Technical Docs