Pular para o conteúdo principal
Um registro de pipeline acompanha um trabalho com um contato, como uma oportunidade de venda, pelas etapas de um pipeline. Use esta receita para levar os registros do seu sistema para um pipeline do Bridge: crie-os, mude os seus valores, mova-os entre etapas, feche-os com um motivo e reabra-os. Para receber as mudanças feitas no Bridge, assine os eventos de registros de pipeline.

Antes de começar

  • Obtenha uma API Key de servidor em Autenticação e envie-a em x-api-key, como em qualquer outra operação. O workspaceId do caminho deve ser o workspace dessa key. Qualquer outro workspace é recusado com 403 BRIDGE_CORE_0301, e nada é lido nem escrito.
  • Os pipelines devem estar habilitados para o workspace. Caso contrário, todas as operações respondem 403 BRIDGE_PIPELINE_0301.
  • Obtenha o pipeline em que você escreve. Ele lista os valores de stageId, os ids de atributo que você usa como chaves de values e os motivos de fechamento ativos. Liste os pipelines para encontrar o id dele.
403 BRIDGE_CORE_0301

As operações

... representa /bridge/api/v1/workspaces/{workspaceId}, no host da API REST https://api-connect-us.bridge.new.

Crie um registro

Indique o contato com exatamente um de contact.id, contact.phone ou contact.email. O Bridge encontra o contato do mesmo jeito que a busca de contatos; um contato mesclado com outro é resolvido para o contato que o substituiu. O contato nunca é criado: se ele não existe, a requisição falha com 404 BRIDGE_EXTERNAL_0001, então crie o contato primeiro e tente de novo. Sem pipelineId, o registro vai para o pipeline padrão do workspace e, sem stageId, para a etapa inicial do pipeline. Uma etapa final é recusada na criação. Um pipeline configurado para não aceitar registros da API recusa a criação com 403 BRIDGE_PIPELINE_0317.
Um registro criado responde 201 com um header Location e o registro. Guarde o id e o revision dele:
201
404 BRIDGE_EXTERNAL_0001

Vincule o registro ao seu próprio id

Envie externalId com o id que o registro tem no seu sistema. Um pipeline tem um registro por externalId: uma segunda criação com o mesmo externalId no mesmo pipeline falha com 409 BRIDGE_PIPELINE_0003, e extra.recordId é o registro que já o tem. Leia esse registro em vez de criar outro. Para encontrá-lo depois, liste os registros com externalId (e pipelineId quando não for o pipeline padrão). O Bridge escolhe o id do registro; o corpo da requisição não tem um campo para defini-lo.
409 BRIDGE_PIPELINE_0003

Um registro aberto por contato

Um pipeline pode ser configurado no Bridge para que um contato tenha um só registro aberto por vez. Nesse pipeline, criar um registro para um contato que já tem um aberto falha com 409 BRIDGE_PIPELINE_0318, e extra.openRecordId é esse registro aberto: trabalhe nele. Registros fechados não contam, então um contato pode começar um registro novo depois que o anterior for fechado. Reabrir um registro falha do mesmo jeito quando o contato tem outro registro aberto no pipeline.
409 BRIDGE_PIPELINE_0318

Repita com segurança com Idempotency-Key

POST .../records, POST .../move e POST .../reopen exigem um header Idempotency-Key de 1 a 255 caracteres. Use uma key para cada mudança que você quer fazer e envie a mesma key quando repetir essa mudança. Uma key é mantida por 24 horas; depois disso, a mesma key é executada como uma requisição nova. Todas as operações do workspace compartilham as keys, então não reutilize uma entre registros.
Se uma requisição for interrompida antes de terminar, a key dela pode continuar respondendo 409 BRIDGE_PIPELINE_0401 por até 24 horas. Tente de novo com uma key nova. Envie externalId ao criar registros, para que uma nova tentativa com outra key nunca crie um segundo registro.

Evite sobrescrever mudanças com expectedRevision

Cada registro tem um revision que sobe em um a cada mudança do registro. Envie o revision que você leu por último como expectedRevision no corpo de PATCH, move ou reopen. Se alguém mudou o registro nesse meio-tempo, a requisição falha com 409 BRIDGE_PIPELINE_0101 e nada muda. extra.currentRecord é o registro como está agora: decida de novo a partir dele e tente outra vez com o revision dele. expectedRevision é opcional. Sem ele, a mudança se aplica ao registro como o Bridge o lê, e uma mudança feita no mesmo momento ainda pode fazê-la falhar com o mesmo 409.
PATCH
409 BRIDGE_PIPELINE_0101
extra.currentRecord traz o registro completo, com os mesmos campos da resposta 201 acima; o exemplo mostra só três.

Mova, feche e reabra

Mova o registro com o stageId de uma etapa da versão do pipeline que ele segue. Movê-lo para uma etapa final o fecha. Uma movimentação para uma etapa final pode levar reasonId, um dos motivos de fechamento ativos do pipeline, e um reasonNote de até 500 caracteres, que precisa de reasonId. O motivo de fechamento é opcional: sem ele, o registro é fechado com closeReason: null.
A resposta é 200 com o registro. Um registro fechado tem state: "FINAL", closedAt e, quando a movimentação levou um, closeReason com o id, o label e a note do motivo. Reabra um registro fechado para levá-lo de volta à etapa aberta em que estava antes de ser fechado; o motivo de fechamento é apagado. Quando o histórico dele não cita nenhuma etapa aberta da sua versão, o registro vai para a etapa inicial do pipeline. O corpo é opcional e só aceita expectedRevision. Reabrir um registro aberto falha com 409 BRIDGE_PIPELINE_0307.

As ações de etapa são executadas em cada entrada

Uma etapa pode ter ações, como criar uma tarefa ou criar um registro em outro pipeline. Elas são executadas cada vez que um registro entra na etapa: quando é criado nela, quando é movido para ela e quando é reaberto nela. Isso inclui cada registro que você cria pela API, então uma importação em massa para uma etapa com ações as executa uma vez por registro. Confira as ações da etapa antes de uma importação.
As ações são executadas depois que a API responde; a resposta não espera por elas. Os resultados chegam como eventos de webhook pipeline_action.*.

Erros e limites

  • Todo erro responde um corpo Problem. Decida pelo code, não pelo title. Consulte os códigos de erro de pipelines para cada código e o que fazer.
  • As operações de pipelines consomem a mesma cota que o resto da API: 50 requisições a cada 5 segundos por workspace. Consulte Limites de requisições.