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. ElworkspaceIdde la ruta debe ser el workspace de esa key. Cualquier otro workspace se rechaza con403BRIDGE_CORE_0301, y no se lee ni se escribe nada. - Los pipelines deben estar habilitados para el workspace. Si no, todas las operaciones responden
403BRIDGE_PIPELINE_0301. - Obtén el pipeline en el que escribes. Lista los valores de
stageId, los ids de atributo que usas como claves devaluesy 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 decontact.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.
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íaexternalId 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 con409 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.
Evita sobrescribir cambios con expectedRevision
Cada registro tiene unrevision 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 elstageId 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.
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
Las acciones corren después de que la API responde; la respuesta no las espera. Sus resultados llegan como eventos de webhookpipeline_action.*.
Errores y límites
- Todo error responde un cuerpo
Problem. Decide segúncode, no segúntitle. 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.

