Estados y ciclo de vida

Estado documental: Contrato propuesto. Este catálogo define el significado esperado de los estados; cada valor pasa a implementado o verificado únicamente cuando exista en el producto y haya sido probado.

Objetivo

Esta página es la referencia canónica para interpretar los estados de los recursos de YUPY.

Regla: un estado, un evento, un tipo de caso y un motivo son conceptos diferentes.

Estado financiero:
reconciled

Evento:
payment.reconciled

Tipo de caso:
late_payment

Motivo:
payment_detected_after_expiration

Cómo leer un estado

Un mismo recurso puede conservar más de una dimensión de estado.

{
  "state": {
    "operational": "active",
    "financial": "awaiting_payment"
  }
}

La dimensión operativa describe si la experiencia comercial continúa disponible. La dimensión financiera describe qué sabe YUPY sobre el pago.

Estados operativos de una orden

Estado	Significado	Terminal	Acción habitual
`active`	La operación continúa disponible para el flujo comercial correspondiente.	No	Esperar o continuar la experiencia de cobro.
`expired`	La vigencia operativa terminó.	Sí para esa vigencia	No reactivar automáticamente; revisar un pago posterior cuando corresponda.
`cancelled`	La empresa o el sistema canceló la operación comercial.	Sí	No entregar automáticamente; conservar trazabilidad.

Un estado operativo terminal no elimina la posibilidad de identificar posteriormente un ingreso.

Estados financieros de una orden

Estado	Significado	Terminal	Acción habitual	Evento relacionado
`awaiting_payment`	Todavía no existe información suficiente para confirmar el pago.	No	Esperar.	Ninguno obligatorio.
`payment_reported`	El comprador o vendedor informó que pagó o entregó evidencia.	No	Continuar la verificación.	`payment.reported`
`movement_detected`	YUPY identificó información financiera potencialmente relacionada.	No	Esperar la conciliación.	`payment.detected`
`reconciliation_pending`	La evaluación continúa y todavía no existe confirmación final.	No	Esperar o aportar información adicional.	Depende del flujo.
`reconciled`	YUPY relacionó la operación con el ingreso correspondiente.	Sí para la confirmación	Continuar el proceso comercial.	`payment.reconciled`
`amount_difference`	El monto identificado no coincide con el monto esperado.	No	Atender el faltante o exceso.	`payment.amount_difference`
`ambiguous`	La información permite más de una interpretación razonable.	No	No confirmar arbitrariamente.	`payment.ambiguous`
`review_required`	La operación requiere revisión de una persona autorizada.	No	Asignar y resolver el caso.	`payment.review_required`
`late_detected`	El ingreso fue identificado después del vencimiento, cancelación o cierre operativo.	No	La empresa decide la resolución comercial.	`payment.late_detected`

payment_reported no significa reconciled.

Clasificación de diferencias

Cuando el estado financiero es amount_difference, la respuesta puede incluir una clasificación:

Clasificación	Significado	Acción habitual
`underpayment`	El monto recibido es menor que el esperado.	Crear o solicitar el pago complementario cuando corresponda.
`overpayment`	El monto recibido es mayor que el esperado.	Crear un caso de devolución o resolver según la política de la empresa.

La clasificación no sustituye el estado financiero ni la orden original.

Estados de una sesión de Web Checkout

Estado	Significado	Terminal
`active`	El enlace temporal puede utilizarse dentro de su vigencia.	No
`expired`	La vigencia de la sesión terminó.	Sí
`revoked`	La sesión fue invalidada antes de su vencimiento natural.	Sí

Una orden puede tener más de una sesión de checkout a lo largo de su vida. La expiración de una sesión no elimina la orden.

Estados de evidencia y OCR

Estado	Significado	Acción habitual
`queued`	La evidencia fue recibida y espera procesamiento.	Esperar.
`processing`	El archivo está siendo procesado.	Esperar.
`processed`	El procesamiento terminó.	Consultar el resultado disponible.
`partial`	Solo una parte de la información pudo extraerse.	Revisar o aportar otra evidencia.
`unreadable`	La imagen no puede interpretarse de forma suficiente.	Solicitar otra imagen.
`rejected`	El archivo no cumple las condiciones admitidas.	Corregir y volver a enviar cuando esté permitido.
`failed`	El procesamiento terminó con error.	Reintentar únicamente cuando el contrato lo permita.

El procesamiento de evidencia no constituye confirmación financiera.

Estados de casos pendientes

Estado	Significado	Terminal
`created`	El caso fue generado.	No
`acknowledged`	Un responsable confirmó que conoce el caso.	No
`assigned`	El caso tiene un responsable.	No
`waiting_for_evidence`	La resolución espera información adicional.	No
`under_review`	Una persona autorizada analiza el caso.	No
`resolved`	Existe una resolución registrada.	Sí para la decisión
`closed`	El seguimiento operativo terminó.	Sí

Un caso pendiente no sustituye a la orden. Conserva el problema operativo y su resolución.

Estados de devoluciones

Estado	Significado	Terminal
`refund_identified`	YUPY identificó una posible necesidad de devolución.	No
`refund_requested`	La devolución fue solicitada.	No
`refund_under_review`	La empresa analiza la solicitud.	No
`refund_approved`	La empresa aprobó la devolución.	No
`refund_pending_execution`	La empresa todavía debe ejecutar la devolución.	No
`refund_completed`	La empresa registró la ejecución y YUPY aceptó la evidencia correspondiente.	Sí
`refund_rejected`	La empresa rechazó la solicitud.	Sí
`refund_failed`	Un intento de ejecución fue registrado como fallido.	No necesariamente
`refund_cancelled`	El caso fue cancelado de forma auditada.	Sí

refund_approved no significa refund_completed. YUPY no ejecuta la devolución.

Estados de trabajos de reporte

Estado	Significado	Terminal
`queued`	El trabajo espera procesamiento.	No
`processing`	El reporte se está generando.	No
`ready`	El reporte está disponible durante su vigencia.	Sí para la generación
`failed`	El reporte no pudo generarse.	Sí para ese intento
`cancelled`	El trabajo fue cancelado.	Sí

Estados de entregas

Las entregas pueden corresponder a instrucciones operativas o intentos de webhook. Cada recurso debe indicar su tipo.

Estado	Significado
`queued`	La entrega espera procesamiento.
`processing`	La entrega está en curso.
`delivered`	El receptor aceptó la entrega.
`retry_scheduled`	Existe un nuevo intento programado.
`failed`	El intento terminó con error.
`cancelled`	La entrega fue cancelada.

delivered significa que el receptor aceptó la entrega técnica. No demuestra por sí solo que haya completado su efecto comercial.

Estados de turnos, dispositivos e integraciones

Recurso	Estado	Significado
Turno	`active`	El turno está abierto.
Turno	`expiring`	El turno se aproxima a su cierre configurado.
Turno	`closed`	El turno fue cerrado.
Turno	`auto_closed`	YUPY cerró el turno según la configuración aplicable.
Dispositivo	`active`	El dispositivo puede recibir operaciones autorizadas.
Dispositivo	`inactive`	El dispositivo no puede recibir nuevas operaciones.
Integración o credencial	`active`	El acceso está habilitado.
Integración o credencial	`inactive`	El acceso fue desactivado.
Credencial	`revoked`	La credencial ya no es válida.
Token	`expired`	La vigencia terminó.

Transiciones

La API puede rechazar una transición cuando el recurso ya no admite la acción solicitada.

HTTP 409
invalid_state_transition

No todas las transiciones son reversibles. Una corrección debe conservar la decisión anterior y registrar una nueva acción auditada.

Tratamiento de valores desconocidos

El cliente debe:

no interpretar un valor desconocido como éxito;
conservar el valor para diagnóstico;
continuar procesando campos conocidos cuando sea seguro;
consultar la versión del contrato y el changelog;
evitar fallos totales por la incorporación compatible de un nuevo estado no terminal.

Criterios de aceptación documental

Los estados están separados por recurso y dimensión.
Los eventos no se presentan como estados.
payment_reported no equivale a reconciled.
La expiración operativa no borra un posible resultado financiero posterior.
Las diferencias conservan su clasificación.
OCR no confirma financieramente un pago.
Un caso pendiente no sustituye a la orden.
refund_approved no equivale a refund_completed.
Una entrega técnica no garantiza el efecto comercial.
Los valores desconocidos no se tratan como éxito.

API Technical Docs