Transferencias

Cuando un comprador transfiere su boleto a otra persona, tu sistema cambia de titular y, según tu plataforma, puede o no emitir un QR nuevo. Ambos casos se resuelven con el mismo POST /v1/partner/tickets/bulk, sin endpoints extra. Solo hay que respetar una regla.

Regla única

Envía siempre, en cada fila:

Campo	Regla
`externalRef`	Tu ID estable del boleto. No cambia nunca, aunque cambie el titular o el QR. Es la identidad del boleto en el espejo.
`holderRef`	ID estable del titular actual (userId, teléfono…). No uses nombre ni email si pueden cambiar.
`holderName`	Nombre para mostrar al operador en puerta.

Y hazlo como push en el momento en que se acepta la transferencia, no esperes al feed: hasta que nos llegue, la puerta sigue viendo al titular anterior (y, si hubo QR nuevo, sigue aceptando el viejo).

Si externalRef cambia entre envíos, para nosotros es otro boleto (y el anterior seguirá vigente hasta que lo anules). Si holderRef falta, no podemos saber quién es el titular ni aplicar el sello multi-uso.

Caso A — el QR no cambia

Reenvía la fila con el mismo qrContent, el mismo externalRef y el holderRef/holderName nuevos. El titular se actualiza y el boleto sigue válido con su QR de siempre. Cuenta en updated.

{
  "experienceId": "22222222-2222-4222-8222-222222222222",
  "rows": [
    {
      "qrContent": "ABC.DEF",
      "externalRef": "TG-1001",
      "holderRef": "user-99",
      "holderName": "Luis Gómez"
    }
  ]
}

{ "inserted": 0, "updated": 1, "reissued": 0, "rejected": [] }

Caso B — el QR se reemite

Envía la fila con el mismo externalRef y el qrContent nuevo (más el titular nuevo). El boleto se reemite en su misma fila: conserva su historial, sus usos y su externalRef; el QR viejo deja de existir en el espejo y, si alguien lo presenta en puerta, el escáner responde “no existe (reemitido)”. Cuenta en reissued.

{
  "experienceId": "22222222-2222-4222-8222-222222222222",
  "rows": [
    {
      "qrContent": "XYZ.987",
      "externalRef": "TG-1001",
      "holderRef": "user-99",
      "holderName": "Luis Gómez"
    }
  ]
}

{ "inserted": 0, "updated": 0, "reissued": 1, "rejected": [] }

Si tu plataforma reemite el QR sin cambiar de titular (por ejemplo, el comprador pide reenviar su boleto), el mismo request aplica: mismo externalRef, QR nuevo, mismo holderRef.

Rechazos en transferencias

`reason`	Qué pasó
`QR_TAKEN`	El `qrContent` nuevo ya pertenece a otro boleto (otro `externalRef`). Emite otro QR o revisa tu mapeo.
`EXPERIENCE_MISMATCH`	Ese `externalRef` existe en otra experiencia. Un boleto no cambia de evento; usa un `externalRef` nuevo.
`REDEEMED_CONFLICT`	El boleto ya entró por la puerta (o agotó sus usos). Un boleto redimido no se transfiere ni se reemite; la fila se ignora.

Las filas rechazadas no afectan al resto del request: revisa rejected[].index y corrige solo esas. Tabla completa en la referencia del bulk.

Sello multi-uso

Para boletos con maxUses > 1 (pulseras multi-día, pases de varios accesos) el organizador puede tener activa en Gate la política sellar al primer titular (activa por defecto): tras la primera entrada, el boleto queda sellado al holderRef que tenía en ese momento y solo ese titular puede volver a usarlo. Si después nos llega una transferencia (Caso A o B) y alguien presenta el boleto, la puerta responde HOLDER_MISMATCH y no consume un uso.

Consecuencias para tu integración:

holderRef tiene que ser estable. Si lo cambias sin que haya una transferencia real (por ejemplo, pasas de userId a email), el sello dejará de coincidir y el titular legítimo será rechazado.
Envía holderRef en cada actualización del boleto (bulk y feed). Si falta, no podemos aplicar el sello: el boleto multi-uso queda sin protección contra “prestar la pulsera”. (Un boleto sin holderRef nunca es denegado por este motivo.)
Una transferencia antes del primer uso es libre; después del primer uso, con la política activa, el boleto ya no se puede ceder. Para “deshacer” una transferencia enviada por error, reenvía la fila con el holderRef original.

Detalle en Multi-usos.

Tabla de escenarios

Escenario	Qué envías	Resultado en el bulk	Resultado en puerta
Transferencia antes del primer uso, mismo QR	misma fila, `holderRef` nuevo	`updated`	Entra con su QR; el operador ve al nuevo titular.
Transferencia antes del primer uso, QR nuevo	mismo `externalRef`, `qrContent` nuevo, `holderRef` nuevo	`reissued`	QR nuevo entra; QR viejo → “no existe (reemitido)”.
Transferencia después del primer uso, boleto de un solo uso	cualquier fila	`REDEEMED_CONFLICT`	Sin cambios: ya está redimido (`DUPLICATE`).
Transferencia después del primer uso, boleto multi-uso, sello activo	misma fila, `holderRef` nuevo (con o sin QR nuevo)	`updated` / `reissued`	`HOLDER_MISMATCH`, sin consumir uso, hasta que el `holderRef` vuelva a coincidir con el sellado.
Transferencia después del primer uso, boleto multi-uso, sello desactivado por el organizador	ídem	`updated` / `reissued`	Entra el nuevo titular mientras queden usos.
Boleto multi-uso agotado (`redeemed`)	cualquier fila	`REDEEMED_CONFLICT`	`DUPLICATE`.
Boleto anulado que se transfiere	fila con `status: "valid"` y `holderRef` nuevo	`updated` (vuelve a `valid`)	Entra el nuevo titular.