Integração de vendas com sistema externo assíncrono

A proposta era permitir que a venda fosse fechada sem depender do tempo de resposta de uma plataforma externa. Depois que a Oportunidade chega a Closed Won, o Salesforce inicia em segundo plano o processo de criação da assinatura. Se houver uma falha que permita nova tentativa, a solicitação pode ser enviada novamente sem criar uma assinatura duplicada.

Quando uma Oportunidade era fechada, também era preciso criar uma assinatura em uma plataforma externa. Se o Salesforce fizesse essa chamada antes de concluir o fechamento, a pessoa vendedora poderia ter de esperar pela resposta de outro sistema. Uma lentidão ou indisponibilidade da plataforma externa também poderia impedir uma etapa que deveria depender apenas do processo comercial.

Havia outro risco. Em algumas situações, a plataforma externa poderia receber e processar a solicitação, mas a resposta não chegaria ao Salesforce a tempo. Isso pode acontecer, por exemplo, se houver uma interrupção na comunicação entre os sistemas. Sem saber se a assinatura foi criada, o Salesforce poderia enviar o pedido novamente e acabar criando outra.

Por isso, o desafio era deixar o fechamento da Oportunidade seguir sem esperar pela integração e, ao mesmo tempo, permitir novas tentativas sem duplicar o provisionamento. Nota: neste case, provisionamento é a criação da assinatura na plataforma externa.

Separei o fechamento da Oportunidade da chamada à plataforma externa. Um Flow, configurado para agir depois que o registro é salvo, identifica quando a etapa muda para Closed Won. Nesse momento, cria um registro Provisioning_Request__c para guardar a solicitação de criação da assinatura.

Esse registro inclui a referência à Oportunidade, as informações usadas no pedido e uma chave única para identificar aquela operação.

Depois, uma classe Apex que pode ser chamada pelo Flow coloca a solicitação em uma fila de trabalho (classe queueable). Na prática, isso permite que o Salesforce deixe a Oportunidade ser fechada e execute a integração separadamente, de forma assíncrona. Uma classe Queueable busca a solicitação que foi salva e faz a chamada REST, que é a comunicação entre os sistemas, usando uma Named Credential, configuração que guarda como o Salesforce deve se conectar à plataforma externa.

A chave única também é enviada na chamada como chave de idempotência. Esse nome descreve uma proteção contra duplicidade: quando a mesma operação é enviada mais de uma vez, a chave permite que a plataforma externa reconheça que se trata do mesmo pedido, em vez de criar outra assinatura.

O registro da solicitação guarda o status, o número de tentativas, quando uma nova tentativa poderá ocorrer e o último status HTTP recebido. Também mantém dois identificadores com funções diferentes. O identificador de correlação ajuda a acompanhar a chamada e relacionar os registros ou mensagens associados àquela operação. O identificador externo é o código que a plataforma externa devolve para localizar a assinatura criada.

Quando o pedido é concluído, o Salesforce salva esse identificador externo. Timeouts e falhas do servidor podem permitir uma nova tentativa. Já um erro de validação, que indica que alguma informação precisa ser corrigida, fica disponível para revisão sem consumir uma tentativa.

As novas tentativas são controladas por uma rotina agendada no Salesforce, mantida por uma classe Apex Scheduled. Em vez de colocar todos os pedidos em execução continuamente, essa rotina verifica quais estão prontos para tentar de novo e ainda não chegaram ao limite configurado.

Como a solicitação foi salva antes da chamada externa, a indisponibilidade da outra plataforma não impede o fechamento da Oportunidade. Quando a rotina agendada (via Apex Scheduled) verifica que um pedido pode ser tentado novamente, ela o envia usando a mesma chave de idempotência.

Isso também trata o caso em que a plataforma externa criou a assinatura, mas o Salesforce não recebeu a confirmação. Na nova tentativa, a mesma chave identifica a operação original e ajuda a evitar que uma segunda assinatura seja criada.

Se a solicitação falhar por causa de uma informação inválida, ela fica disponível para correção e pode ser enviada novamente de forma manual. Não é necessário reabrir nem alterar a Oportunidade para fazer esse ajuste.

A pessoa vendedora fecha a Oportunidade e segue o trabalho sem aguardar a integração. Em paralelo, o Salesforce tenta criar a assinatura e registra o resultado. Se houver uma falha que permita nova tentativa, o pedido poderá ser processado depois. Se for preciso corrigir uma informação, a solicitação fica visível para revisão.

O fechamento da Oportunidade deixa de esperar pela resposta da plataforma externa. A criação da assinatura passa a ter uma solicitação registrada, com status e tentativas controladas. Quando a integração precisa ser repetida, a mesma chave ajuda a evitar uma assinatura duplicada.