POS vía chat, turnos, dispositivos y entregas

Estado documental: Contrato propuesto. Las rutas, campos, límites y tiempos pasan a estado confirmado solo después de su implementación y verificación.

Objetivo: Inventariar turnos, dispositivos, entregas y configuración administrativa del POS vía chat.

Regla de turno

Un turno
= una persona identificada
+ un dispositivo
+ un canal
+ una ventana operativa

No existe cambio de persona dentro de un turno. Para otro vendedor se cierra el turno actual y se abre uno nuevo.

Turnos

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/shifts`	Abrir turno después de identificar al usuario.	Obligatoria	shift.opened
Integración	`GET`	`/v1/shifts`	Listar turnos.	No	Ninguno
Integración	`GET`	`/v1/shifts/{shift_id}`	Consultar turno.	No	Ninguno
Integración	`POST`	`/v1/shifts/{shift_id}/close`	Cerrar turno.	Obligatoria	shift.closed
Integración	`GET`	`/v1/shifts/{shift_id}/payment-orders`	Consultar órdenes del turno.	No	Ninguno
Integración	`GET`	`/v1/shifts/{shift_id}/pending-cases`	Consultar pendientes del turno.	No	Ninguno
Integración	`GET`	`/v1/shifts/{shift_id}/summary`	Obtener resumen operativo.	No	Ninguno

Ejemplo: abrir turno

POST /v1/shifts
Idempotency-Key: 1cf08e71-6484-4d08-b772-45573a4beec4

{
  "user_id": "usr_01JXYZ",
  "device_id": "dev_01JXYZ",
  "channel": "whatsapp",
  "identification": {
    "type": "pin",
    "value": "<PROTECTED_VALUE>"
  }
}

{
  "shift_id": "shf_01JXYZ",
  "user_id": "usr_01JXYZ",
  "device_id": "dev_01JXYZ",
  "opened_at": "2026-07-20T08:00:00-05:00",
  "maximum_duration_seconds": 28800,
  "expiration_mode": "warning_and_renewal",
  "status": "active",
  "request_id": "req_01JXYZ"
}

Crear una orden para el turno

La orden se crea mediante POST /v1/payment-orders e incluye:

{
  "external_transaction_id": "TICKET-88412",
  "amount": "80.00",
  "buyer_name": "Carlos Vega",
  "integration_experience": "chat_pos",
  "shift_id": "shf_01JXYZ",
  "device_id": "dev_01JXYZ"
}

Dispositivos y entregas

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`GET`	`/v1/devices/{device_id}`	Consultar dispositivo autorizado.	No	Ninguno
Integración	`GET`	`/v1/devices/{device_id}/active-shift`	Consultar turno activo.	No	Ninguno
Integración	`GET`	`/v1/devices/{device_id}/inbox`	Consultar operaciones por entregar.	No	Ninguno
Integración	`POST`	`/v1/devices/{device_id}/inbox/{item_id}/acknowledge`	Confirmar recepción.	Obligatoria	device.delivery_received
Integración	`GET`	`/v1/devices/{device_id}/pending-cases`	Consultar pendientes operativos.	No	Ninguno
Integración	`POST`	`/v1/payment-orders/{id}/deliveries`	Crear entrega de instrucciones.	Obligatoria	delivery.queued
Integración	`GET`	`/v1/payment-orders/{id}/deliveries`	Listar entregas.	No	Ninguno
Integración	`GET`	`/v1/deliveries/{delivery_id}`	Consultar estado.	No	Ninguno
Integración	`POST`	`/v1/deliveries/{delivery_id}/retry`	Reintentar entrega fallida.	Obligatoria	delivery.queued
Integración	`POST`	`/v1/deliveries/{delivery_id}/cancel`	Cancelar antes del envío.	Obligatoria	delivery.cancelled

Ejemplo: crear entrega

POST /v1/payment-orders/ypt_01JXYZ/deliveries

{
  "delivery_target": {
    "type": "shift_device",
    "shift_id": "shf_01JXYZ",
    "device_id": "dev_01JXYZ"
  },
  "content_type": "payment_instructions"
}

{
  "delivery_id": "dly_01JXYZ",
  "status": "queued",
  "request_id": "req_01JXYZ"
}

Usuarios administrativos

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`POST`	`/v1/admin/users`	Registrar usuario.	Sí	user.created
Administración	`GET`	`/v1/admin/users`	Listar usuarios.	No	Ninguno
Administración	`GET`	`/v1/admin/users/{id}`	Consultar usuario.	No	Ninguno
Administración	`PATCH`	`/v1/admin/users/{id}`	Actualizar datos permitidos.	Sí	user.updated
Administración	`POST`	`/v1/admin/users/{id}/activate`	Activar usuario.	Sí	user.activated
Administración	`POST`	`/v1/admin/users/{id}/deactivate`	Desactivar usuario.	Sí	user.deactivated
Administración	`POST`	`/v1/admin/users/{id}/reset-credential`	Restablecer identificación.	Sí	security.user_credential_reset
Administración	`GET`	`/v1/admin/users/{id}/history`	Consultar auditoría.	No	Ninguno

Dispositivos administrativos

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`POST`	`/v1/admin/devices`	Registrar dispositivo.	Sí	device.created
Administración	`GET`	`/v1/admin/devices`	Listar dispositivos.	No	Ninguno
Administración	`GET`	`/v1/admin/devices/{id}`	Consultar dispositivo.	No	Ninguno
Administración	`PATCH`	`/v1/admin/devices/{id}`	Actualizar configuración.	Sí	device.updated
Administración	`POST`	`/v1/admin/devices/{id}/activate`	Activar.	Sí	device.activated
Administración	`POST`	`/v1/admin/devices/{id}/deactivate`	Desactivar.	Sí	device.deactivated
Administración	`POST`	`/v1/admin/devices/{id}/pair`	Vincular canal o terminal.	Sí	device.paired
Administración	`POST`	`/v1/admin/devices/{id}/unpair`	Desvincular.	Sí	device.unpaired
Administración	`POST`	`/v1/admin/devices/{id}/assign-supervisor`	Asignar supervisor.	Sí	device.supervisor_assigned
Administración	`GET`	`/v1/admin/devices/{id}/history`	Consultar auditoría.	No	Ninguno

Política de turnos y alertas

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`GET`	`/v1/admin/shift-policy`	Consultar duración y modalidad.	No	Ninguno
Administración	`PATCH`	`/v1/admin/shift-policy`	Configurar política de turnos.	Sí	shift_policy.updated
Administración	`POST`	`/v1/admin/shift-policy/test`	Probar política.	Sí	Ninguno
Administración	`POST`	`/v1/admin/alert-rules`	Crear regla de alerta.	Sí	alert_rule.created
Administración	`GET`	`/v1/admin/alert-rules`	Listar reglas.	No	Ninguno
Administración	`GET`	`/v1/admin/alert-rules/{id}`	Consultar regla.	No	Ninguno
Administración	`PATCH`	`/v1/admin/alert-rules/{id}`	Modificar regla.	Sí	alert_rule.updated
Administración	`DELETE`	`/v1/admin/alert-rules/{id}`	Desactivar regla.	Sí	alert_rule.deactivated
Administración	`POST`	`/v1/admin/alert-rules/{id}/test`	Enviar alerta de prueba.	Sí	alert.test_sent
Administración	`GET`	`/v1/admin/alerts`	Consultar historial.	No	Ninguno
Administración	`POST`	`/v1/admin/alerts/{id}/acknowledge`	Registrar atención.	Sí	alert.acknowledged

Ejemplo: política de turnos

PATCH /v1/admin/shift-policy

{
  "maximum_duration_seconds": 28800,
  "expiration_mode": "warning_and_renewal",
  "warning_after_each_transaction": true,
  "auto_close": false
}

Ejemplo: regla de alerta

{
  "event_types": [
    "payment.late_detected",
    "payment.amount_difference"
  ],
  "recipients": [
    {
      "type": "seller"
    },
    {
      "type": "supervisor"
    }
  ],
  "channels": [
    "whatsapp",
    "email"
  ],
  "active": true
}

Errores principales

HTTP	Código	Descripción
404	`shift_not_available`	Turno inexistente o no disponible.
409	`shift_closed`	El turno ya fue cerrado.
409	`shift_device_mismatch`	Dispositivo distinto al del turno.
403	`user_not_authorized`	Usuario sin autorización.
404	`device_not_available`	Dispositivo no disponible.
404	`delivery_not_found`	Entrega inexistente.
409	`delivery_retry_not_allowed`	La entrega no puede reintentarse.

API Technical Docs