Square

Lo que distingue a Square en esta lista es el mostrador. Del lado de Square están el lector de tarjetas y la terminal de punto de venta en el local, la superficie de pagos en línea, el directorio de clientes, el catálogo de artículos, los pedidos, las facturas y los reembolsos. Del lado de AppBO están el contacto, la cita, el pipeline y los flujos de trabajo, que hasta ahora no tenían idea de lo que pasaba cuando el cliente de verdad entraba y pagaba.

Conectarlos cierra ese círculo. Un cliente reserva con un calendario de AppBO, asiste y paga en recepción con un lector de Square; con la integración, ese pago llega a su registro de contacto, así que la secuencia de seguimiento sabe que vino y pagó, y no solo que tenía una reserva. Las campañas de reactivación pueden dirigirse a quienes llevan meses sin hacer una compra, no solo a quienes no han abierto un email. El valor de vida del cliente incluye el mostrador, que en cualquier negocio con local es la mayor parte.

Es la opción correcta cuando una parte importante de los ingresos se cobra en persona, o cuando Square ya es la caja del día a día y reemplazarla no está en discusión. El trabajo de integración es sobre todo de identidad: el flujo de caja de Square está optimizado para la velocidad, lo que significa que a la persona en el mostrador muchas veces se le registra con pocos datos o con ninguno, y un pago sin un cliente asociado no puede llegar a un contacto. Lograr que en el punto de venta se capture una clave de identidad confiable es la diferencia entre una integración útil y un chorro de transacciones huérfanas.

1. Confirma que la cuenta de Square esté configurada para las sucursales involucradas. Square modela cada sitio físico como una ubicación, y cada transacción pertenece a una. Si tienes más de un sitio, ten claro qué ubicaciones entran en el alcance antes de conectar.
2. Decide para qué es la integración: registrar las ventas presenciales en los contactos, cobrar pagos en línea, emitir facturas, o las tres cosas. El manejo de la identidad es distinto en cada caso.
3. En la subcuenta de AppBO, abre la configuración de pagos e inicia la conexión con Square. Completa el flujo de autorización de Square, inicia sesión en la cuenta de Square dueña de esas ubicaciones y aprueba los permisos que pide.
4. Antes de confiar en la conexión, confirma a qué cuenta de Square y a qué ubicaciones quedó asociada. Un comercio con varias ubicaciones puede autorizar la equivocada con mucha facilidad.
5. Decide qué sistema es dueño del catálogo de artículos. El catálogo de Square maneja la caja; los productos de la plataforma manejan su propio pago en línea. Elige uno como fuente oficial para los reportes y acepta que el otro es un espejo.
6. Resuelve la identidad en el mostrador, que es el trabajo real. Decide qué captura el personal en cada transacción (asociar un cliente de Square o, como mínimo, un email o un teléfono) y vuélvelo parte de la rutina de caja. Una venta sin atribuir es una venta que la plataforma no puede ver.
7. Elige la clave para relacionar al cliente de Square con el contacto de AppBO, normalmente el teléfono o el email, y normalízala: teléfono en E.164, email en minúsculas. Los datos que se capturan en el mostrador son los menos limpios de cualquier negocio.
8. Agrega campos personalizados en el contacto para el método de pago o el canal, el identificador de pago de Square y la ubicación, para poder rastrear y conciliar cada venta.
9. Configura los pagos en línea si los vas a usar, conectando Square al formulario de pedido o al paso de pago del funnel, y prueba la experiencia de pago alojada tanto en un teléfono como en una computadora.
10. Arma la automatización sobre el evento de pago. Una venta presencial completada debería poder etiquetar al contacto, actualizar la oportunidad e iniciar una secuencia posterior a la visita: solicitud de reseña, invitación a volver a agendar, instrucciones de cuidado.
11. Arma los caminos de reembolso y anulación. Los reembolsos en mostrador pasan por razones normales varias veces por semana, y todo lo que haya disparado la venta tiene que poder revertirse.
12. Verifica primero en el entorno de pruebas (sandbox) de Square cuando la conexión lo permita: completa un pago, confirma que el registro llega a la plataforma, que el flujo de trabajo corrió y que los campos personalizados se llenaron.
13. Después verifica en el hardware real. Cobra un pago real pequeño en el lector de verdad, en el mostrador de verdad, con una tarjeta real, y confirma que llega al contacto correcto en la ubicación correcta. El hardware se comporta distinto que una llamada a la API en el entorno de pruebas.
14. Prueba a propósito el caso huérfano: cobra un pago sin cliente asociado y observa qué hace la plataforma con él. Diseña el manejo que quieres en lugar de descubrirlo después.
15. Programa la conciliación de forma periódica (los reportes propios de Square contra los registros de la plataforma, por ubicación) y vigila la tasa de transacciones huérfanas como una métrica operativa. Si sube, la rutina de caja se relajó.

De Square a la plataforma

• Pagos completados con monto, moneda, estado, el identificador de pago de Square y la ubicación.
• El método de pago usado (tarjeta presente en el lector, tarjeta no presente en línea, billetera digital u otro medio), que es como distingues las ventas de mostrador de las ventas web.
• Los datos del cliente del directorio de Square cuando se asoció un cliente: nombre, email, teléfono.
• El detalle del pedido y de cada partida cuando se usa el catálogo, lo que permite que la automatización se ramifique según lo que de verdad se compró.
• Reembolsos y anulaciones de pagos anteriores.
• Los resultados de facturas cuando se usa la facturación de Square.

De la plataforma a Square

• Solicitudes de pago para el pago en línea y los formularios de pedido: monto, moneda y referencia.
• Registros de cliente creados o relacionados en el directorio de Square cuando un pago se origina en la plataforma.
• Solicitudes de factura o de enlace de pago cuando se usa ese flujo.
• Solicitudes de reembolso de un pago anterior, cuando se inician desde la plataforma.

Lo que no se mueve

• Los datos de la tarjeta. Los captura el lector o los campos alojados de Square, y nunca llegan a la plataforma.
• El estado del hardware y de la terminal. La vinculación del lector, las solicitudes de propina y la impresión de recibos se configuran en Square.
• Las existencias de inventario, a menos que hayas decidido a propósito sincronizar un catálogo; la plataforma no es un sistema de inventario.
• Los datos de turnos, registros de horas y gestión del personal del punto de venta.
• Las transacciones cobradas antes de que existiera la conexión, y las transacciones en ubicaciones que la autorización no cubrió.
• Cualquier atribución de una venta en la que no se asoció un cliente en la caja. No hay nada con qué relacionarla.

Escenario: una clínica agenda citas en AppBO y cobra en recepción con un lector de Square. La secuencia posterior a la visita solo debe correr para las personas que de verdad pagaron.

1. Un paciente reserva una consulta con un calendario de AppBO. El contacto existe con un número de celular guardado en E.164 y un email.
2. El paciente asiste. En recepción, la recepcionista busca por teléfono en el directorio de clientes de Square, encuentra el registro de cliente creado en una visita anterior, lo asocia a la venta y cobra el pago en el lector.
3. Square completa el pago con tarjeta presente y emite la transacción con su identificador de pago, la ubicación y el cliente asociado.
4. La plataforma recibe el pago, relaciona el teléfono del cliente de Square con el teléfono del contacto y registra la transacción en ese contacto.
5. Se dispara el flujo de pago: escribe Square: tarjeta presente en el campo de canal, guarda el identificador de pago y la ubicación en campos personalizados, marca la cita como asistida y mueve la oportunidad a Completada.
6. Después el flujo espera dos horas y envía el email de cuidados posteriores, espera tres días y envía por SMS una solicitud de reseña, y programa una invitación a volver a agendar para dentro de seis semanas. Nada de esto se habría disparado con una inasistencia, porque lo mueve el pago y no la reserva.
7. El siguiente paciente paga con prisa y la recepcionista no asocia ningún cliente. La plataforma recibe un pago que no puede relacionar. En lugar de descartarlo, la integración lo registra en una vista de espera y crea una tarea para que alguien lo atribuya a partir de la lista de citas del día.
8. Esa tarde, alguien del equipo atribuye el pago huérfano al contacto correcto, lo que registra la venta e inicia la misma secuencia posterior a la visita con unas horas de retraso.
9. Una semana después, el primer paciente pide un reembolso parcial. Se procesa en recepción en Square, que emite un evento de reembolso.
10. Un flujo que se dispara con el reembolso etiqueta al contacto como reembolsado, lo saca de la secuencia para volver a agendar y crea una tarea para que la gerente de la clínica anote el motivo en el contacto.
11. A fin de mes, la clínica concilia el reporte por ubicación de Square contra los registros de pago de la plataforma. Los totales coinciden, y el conteo de transacciones huérfanas es de dos entre varios cientos. Lo bastante bajo como para saber que la rutina de caja funciona, y medido para que siga así.

Límites de uso

Square publica sus propios límites de API, y son por endpoint; revisa la documentación vigente en lugar de suponerlos, y espera antes de reintentar cuando recibas respuestas de límite excedido. El límite más realista para un mostrador con mucho movimiento son los picos: la hora de la comida produce un grupo denso de eventos de pago, así que lo que los consuma tiene que aguantar un pico y no solo el promedio.

Reintentos e idempotencia

Las APIs de pago de Square aceptan una clave de idempotencia y siempre deberías enviar una. Una solicitud de pago reintentada sin ella puede cobrarle dos veces al cliente, lo que en un mostrador significa una discusión enfrente de la fila. Las notificaciones de eventos se entregan al menos una vez y se reintentan, así que elimina duplicados por el identificador del evento o del pago. Los reembolsos necesitan el mismo cuidado: un reembolso reintentado sin idempotencia puede devolver el dinero dos veces.

Trampas al mapear campos

Los montos están en la unidad más pequeña de la moneda; verifícalo contra una transacción real antes de confiar en tu mapeo. Los datos de contacto que se capturan en el mostrador vienen desordenados (teléfonos sin código de país, emails mal escritos, nombres en el campo equivocado), así que normaliza a fondo antes de relacionar. Los identificadores de ubicación importan: un comercio con varios sitios que ignora la ubicación no puede saber qué sitio generó qué, y atribuir todos los ingresos a un solo sitio es algo que va a notar quien dirige el otro.

Transacciones sin atribuir

Este es el problema característico de Square, y es operativo, no técnico. Un pago cobrado sin cliente asociado no tiene nada que relacionar con un contacto, y va a pasar cada vez que el mostrador esté lleno. Diseña el manejo a propósito: retén la transacción, muéstrala para que alguien la atribuya y mide la tasa. No la descartes sin avisar, y no adivines el contacto solo por la hora.

Creación de duplicados

Los clientes duplicados en Square se acumulan rápido en un mostrador cuando el personal crea un registro nuevo en lugar de buscar el que ya existe, y cada duplicado puede producir un segundo contacto en AppBO. Entrena el hábito de buscar primero, y combina los duplicados de forma periódica en el directorio de Square, no solo en la plataforma.

Pruebas contra producción

El entorno de pruebas de Square cubre bien la API, pero no puede reproducir el hardware. Un flujo que funciona perfecto contra el entorno de pruebas todavía puede sorprenderte en un lector físico: solicitudes de propina, autorizaciones parciales, modo sin conexión. Siempre termina las pruebas con una transacción real en la terminal real, y ten cuidado con las credenciales de producción en un entorno de pruebas: una clave de producción en una página de prueba cobra dinero real.

Modo sin conexión y tiempos

Los lectores pueden cobrar pagos mientras no hay conexión y subirlos después. Esas transacciones llegan tarde y fuera de orden, así que un flujo de trabajo que da por hecho que un pago es reciente puede actuar con información vieja. Compara la marca de tiempo propia del pago y no la hora de llegada.

Vencimiento de la autorización

Un administrador puede revocar la autorización de Square, puede vencer si los tokens no se renuevan, y no cubre las ubicaciones agregadas después de otorgarla. Un sitio nuevo simplemente no va a aparecer hasta que se vuelva a autorizar. Vigila si hay una ubicación cuyas transacciones dejaron de llegar, que suele ser el primer síntoma.

Lo que se rompe con más frecuencia

• Pagos cobrados sin cliente asociado, que dejan ingresos imposibles de atribuir.
• Una ubicación nueva de Square agregada y nunca autorizada, que falta en los reportes sin que nadie lo note.
• Teléfonos guardados de forma inconsistente, así que las ventas de mostrador no coinciden con ningún contacto.
• Pagos sin conexión que llegan tarde y disparan flujos de trabajo fuera de orden.
• Reembolsos en mostrador sin un camino de reversión en la plataforma.
• Clientes duplicados en el directorio de Square que se multiplican en contactos duplicados.
• Errores de unidad mínima en los montos de los mapeos del pago en línea.