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. OworkspaceIddo caminho deve ser o workspace dessa key. Qualquer outro workspace é recusado com403BRIDGE_CORE_0301, e nada é lido nem escrito. - Os pipelines devem estar habilitados para o workspace. Caso contrário, todas as operações respondem
403BRIDGE_PIPELINE_0301. - Obtenha o pipeline em que você escreve. Ele lista os valores de
stageId, os ids de atributo que você usa como chaves devaluese 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 decontact.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.
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
EnvieexternalId 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 com409 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.
Evite sobrescrever mudanças com expectedRevision
Cada registro tem umrevision 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 ostageId 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.
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
As ações são executadas depois que a API responde; a resposta não espera por elas. Os resultados chegam como eventos de webhookpipeline_action.*.
Erros e limites
- Todo erro responde um corpo
Problem. Decida pelocode, não pelotitle. 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.

