Saltar al contenido principal
Un registro de pipeline sigue un trabajo con un contacto, como una oportunidad de venta, a lo largo de las etapas de un pipeline. Usa esta receta para llevar los registros de tu sistema a un pipeline de Bridge: créalos, cambia sus valores, muévelos entre etapas, ciérralos con un motivo y reábrelos. Para recibir los cambios hechos en Bridge, suscríbete a los eventos de registros de pipeline.

Antes de empezar

  • Obtén una API Key de servidor en Autenticación y envíala en x-api-key, como en cualquier otra operación. El workspaceId de la ruta debe ser el workspace de esa key. Cualquier otro workspace se rechaza con 403 BRIDGE_CORE_0301, y no se lee ni se escribe nada.
  • Los pipelines deben estar habilitados para el workspace. Si no, todas las operaciones responden 403 BRIDGE_PIPELINE_0301.
  • Obtén el pipeline en el que escribes. Lista los valores de stageId, los ids de atributo que usas como claves de values y los motivos de cierre activos. Lista los pipelines para encontrar su id.
403 BRIDGE_CORE_0301

Las operaciones

... representa /bridge/api/v1/workspaces/{workspaceId}, en el host de la API REST https://api-connect-us.bridge.new.

Crea un registro

Indica el contacto con exactamente uno de contact.id, contact.phone o contact.email. Bridge encuentra el contacto igual que la búsqueda de contactos; un contacto fusionado con otro se resuelve al contacto que lo reemplazó. El contacto nunca se crea: si no existe, la solicitud falla con 404 BRIDGE_EXTERNAL_0001, así que crea el contacto primero y reintenta. Sin pipelineId, el registro va al pipeline predeterminado del workspace, y sin stageId, a la etapa inicial del pipeline. Al crear no se acepta una etapa final. Un pipeline configurado para no aceptar registros de la API rechaza la creación con 403 BRIDGE_PIPELINE_0317.
Un registro creado responde 201 con un header Location y el registro. Guarda su id y su revision:
201
404 BRIDGE_EXTERNAL_0001

Vincula el registro con tu propio id

Envía externalId con el id que tiene el registro en tu sistema. Un pipeline tiene un registro por externalId: una segunda creación con el mismo externalId en el mismo pipeline falla con 409 BRIDGE_PIPELINE_0003, y extra.recordId es el registro que ya lo tiene. Lee ese registro en vez de crear otro. Para encontrarlo después, lista los registros con externalId (y pipelineId cuando no es el pipeline predeterminado). Bridge elige el id del registro; el cuerpo de la solicitud no tiene un campo para fijarlo.
409 BRIDGE_PIPELINE_0003

Un registro abierto por contacto

Un pipeline puede configurarse en Bridge para que un contacto tenga un solo registro abierto a la vez. En ese pipeline, crear un registro para un contacto que ya tiene uno abierto falla con 409 BRIDGE_PIPELINE_0318, y extra.openRecordId es ese registro abierto: trabaja sobre él. Los registros cerrados no cuentan, así que un contacto puede empezar un registro nuevo cuando el anterior está cerrado. Reabrir un registro falla de la misma forma cuando el contacto tiene otro registro abierto en el pipeline.
409 BRIDGE_PIPELINE_0318

Reintenta con seguridad con Idempotency-Key

POST .../records, POST .../move y POST .../reopen exigen un header Idempotency-Key de 1 a 255 caracteres. Usa una key por cada cambio que quieras hacer y envía la misma key cuando reintentes ese cambio. Una key se guarda 24 horas; después, la misma key se ejecuta como una solicitud nueva. Todas las operaciones del workspace comparten las keys, así que no reutilices una entre registros.
Si una solicitud se corta antes de terminar, su key puede seguir respondiendo 409 BRIDGE_PIPELINE_0401 hasta por 24 horas. Reintenta con una key nueva. Envía externalId cuando crees registros, para que un reintento con una key nueva nunca cree un segundo registro.

Evita sobrescribir cambios con expectedRevision

Cada registro tiene un revision que sube en uno cada vez que el registro cambia. Envía el revision que leíste por última vez como expectedRevision en el cuerpo de PATCH, move o reopen. Si alguien cambió el registro mientras tanto, la solicitud falla con 409 BRIDGE_PIPELINE_0101 y no cambia nada. extra.currentRecord es el registro como está ahora: decide de nuevo a partir de él y reintenta con su revision. expectedRevision es opcional. Sin él, el cambio se aplica al registro tal como Bridge lo lee, y un cambio hecho en el mismo momento todavía puede hacerlo fallar con el mismo 409.
PATCH
409 BRIDGE_PIPELINE_0101
extra.currentRecord trae el registro completo, con los mismos campos que la respuesta 201 de arriba; el ejemplo muestra solo tres.

Mueve, cierra y reabre

Mueve el registro con el stageId de una etapa de la versión del pipeline que sigue. Moverlo a una etapa final lo cierra. Un movimiento a una etapa final puede llevar reasonId, uno de los motivos de cierre activos del pipeline, y un reasonNote de hasta 500 caracteres, que necesita reasonId. El motivo de cierre es opcional: sin él, el registro se cierra con closeReason: null.
La respuesta es 200 con el registro. Un registro cerrado tiene state: "FINAL", closedAt y, cuando el movimiento llevó uno, closeReason con el id, label y note del motivo. Reabre un registro cerrado para devolverlo a la etapa abierta en la que estaba antes de cerrarse; su motivo de cierre se borra. Cuando su historial no nombra ninguna etapa abierta de su versión, el registro va a la etapa inicial del pipeline. El cuerpo es opcional y solo acepta expectedRevision. Reabrir un registro abierto falla con 409 BRIDGE_PIPELINE_0307.

Las acciones de etapa corren en cada entrada

Una etapa puede tener acciones, como crear una tarea o crear un registro en otro pipeline. Corren cada vez que un registro entra a la etapa: cuando se crea en ella, cuando se mueve a ella y cuando se reabre en ella. Eso incluye cada registro que creas con la API, así que una importación masiva a una etapa con acciones las corre una vez por registro. Revisa las acciones de la etapa antes de una importación.
Las acciones corren después de que la API responde; la respuesta no las espera. Sus resultados llegan como eventos de webhook pipeline_action.*.

Errores y límites

  • Todo error responde un cuerpo Problem. Decide según code, no según title. Consulta los códigos de error de pipelines para cada código y qué hacer.
  • Las operaciones de pipelines consumen el mismo presupuesto que el resto de la API: 50 solicitudes cada 5 segundos por workspace. Consulta Límites de solicitudes.