Este guia mostra como criar um procedimento Fin reutilizável que consulta um catálogo de produtos via sua API, corresponde ao item solicitado pelo cliente, verifica o estoque e direciona o fluxo com base na disponibilidade. Você pode usar este procedimento para criar novos pedidos ou atualizar os existentes usando suas APIs de pedidos backend.
Mantenha seus próprios endpoints de API e nomes de parâmetros — substitua as URLs de exemplo, corpos de requisição e nomes de campos pelos que seu backend expõe. Se você nunca criou um procedimento antes, leia Building Fin Procedures primeiro.
Nota:
Conectores de Dados: Você precisa de três conectores específicos:
Um para retornar um catálogo de produtos (GET).
Um para criar um item de pedido (POST).
Um para atualizar um pedido existente (PUT).
Formato canônico de resposta: Suas APIs devem retornar uma estrutura de dados consistente.
Tratamento de Erros: Para um procedimento robusto, suas etapas de Condição devem usar os atributos de resposta
status_codeeerrorretornados pelos Conectores de Dados. Isso permite que o Fin ramifique em códigos HTTP específicos de erro (ex.: 400, 500) em vez de depender de um caminho genérico de sucesso/falha.
Dica: Conecte-se com Especialistas da Comunidade e Arquitetos de Soluções Intercom em nosso Procedures Meetup Office Hours. Realizadas a cada duas semanas, essas sessões oferecem suporte prático em tempo real, incluindo perguntas e respostas ao vivo para ajudar você a configurar e otimizar seus Procedimentos Fin e conectores de dados.
Configurando conectores de dados
Crie três conectores com nomes claros (por exemplo, Get Product Catalog, Create Order Item, Update Order Item) para ajudar o Fin a identificar a ação correta.
Colete quaisquer entradas que o conector precise. Atributos Temporários agora podem ser passados diretamente como entradas para um Conector de Dados — se os dados já existirem em uma variável temporária, o Fin os mapeia automaticamente sem solicitar ao cliente. Configure uma entrada como coletada do cliente somente se o valor ainda não estiver armazenado. Substitua https://api.example.com e nomes de campos pelos seus próprios endpoints e chaves JSON. Para dúvidas comuns sobre configuração de conectores, autenticação e execução, veja Fin and Data connectors FAQs.
1. Get Product Catalog (GET)
Objetivo: Retorna uma lista de produtos incluindo id, nome, preço e estoque.
Método: GET.
URL: https://api.example.com/items (ou seu endpoint de catálogo)
Headers: Content-Type: application/json (+ auth conforme necessário)
Resposta: Um array de objetos de produto.
Example response:
[
{ "id": "sku-100", "name": "Classic T-Shirt", "price": 19.99, "stock": 120 },
{ "id": "sku-101", "name": "Running Shoes", "price": 89.50, "stock": 45 },
{ "id": "sku-104", "name": "Nintendo Switch", "price": 119.00, "stock": 0 }
]
2. Create Order Item (POST)
Objetivo: Cria um novo pedido ou um item específico do pedido.
Método: POST.
URL: https://api.example.com/orders (ou seu endpoint de criação de pedido)
Headers: Content-Type: application/json (+ auth)
Corpo da requisição: Deve incluir product_id e quantity.
{
"product_id": "<product id>",
"quantity": <integer>
}
Configure as entradas do conector se quiser que o Fin colete product_id e quantity.
3. Update Order Item (PUT)
Objetivo: Adiciona itens ou atualiza um pedido existente.
Método: PUT.
URL: https://api.example.com/orders/{{order_id}} (ou PUT /orders/{order_id}/items)
Headers: Content-Type: application/json (+ auth)
Corpo da requisição: Deve incluir product_id e quantity.
{
"product_id": "<product id>",
"quantity": <integer>
}Entradas obrigatórias: order_id, product_id, quantity
Conexão API mostrando variável de caminho order_id e corpo da requisição.
Coletar entradas de dados listando order_id, product_id, quantity.
Construindo o fluxo do procedimento
Use variáveis temporárias para armazenar dados intermediários durante a conversa. Variáveis recomendadas incluem Temporary.SelectedProductID, Temporary.StockLevel e Temporary.OrderAction.
Passo 1: Consulta e pesquisa de produto
Solicite ao cliente: Pergunte, "Qual produto você gostaria?".
Chame o Conector de Dados: Use Get Product Catalog.
Lógica: Procure na lista retornada um produto cujo nome (ou SKU) corresponda melhor a Temporary.SelectedProductName.
Ao encontrar correspondência, defina:
Temporary.SelectedProductID = id do produto
Temporary.SelectedProductName = nome canônico do produto no catálogo
Temporary.StockLevel = estoque do produto (convertido para inteiro)
Validação: Se nenhuma correspondência for encontrada, peça ao cliente para esclarecer ou sugira os principais produtos similares do catálogo e volte ao Passo 1 se ele escolher outro produto.
Notas de implementação
A lógica de correspondência pode ser uma simples busca por substring ou uma correspondência difusa mais sofisticada. Mantenha a correspondência determinística para que as etapas de condição do Fin funcionem de forma confiável.
Passo 2: Verificação de estoque e ramificação
Use um bloco lógico padrão IF/ELSE na interface do procedimento para verificar Temporary.StockLevel. Esta é uma comparação direta de valores — não é necessário uma condição de código aqui. Use o construtor visual de condições e selecione Temporary.StockLevel como o atributo.
IF Temporary.StockLevel > 0: Continue para o Passo 3.
ELSE: Direcione para a seção "Fora de Estoque" (Passo 8).
Passo 3: Perguntar pedido novo ou existente
Prompt: “Você gostaria de criar um pedido novo para este item ou adicioná-lo a um pedido existente?”
Aceitar respostas:
Novo → Temporary.OrderAction = "new" → Passo 4
Existente → Temporary.OrderAction = "existing" → Passo 4
Se não estiver claro, faça uma pergunta de esclarecimento e repita.
Passo 4 — Perguntar quantidade e validar (atualização menor)
Prompt: “Quantas unidades você gostaria?” → analisar inteiro → armazenar em Temporary.Quantity.
Validação:
Se Temporary.Quantity ≤ 0 → pergunte novamente.
Se Temporary.Quantity > Temporary.StockLevel → informe o cliente sobre o estoque disponível e faça uma das seguintes ações:
Ofereça o máximo disponível e peça para confirmar uma quantidade menor (loop dentro do Passo 4), ou
Ofereça opções de pedido em atraso/notificação (Passo 8).
Após a validação da quantidade, prossiga para o Passo 5 (Decisão da ação do pedido).
Blocos de prompt e validação de quantidade.
Passo 5: Decisão da ação do pedido (IF / ELSE IF)
Em vez de lidar com criação e atualização de pedidos inline, direcione cada caminho para um subprocedimento dedicado. Isso mantém o fluxo principal limpo e torna cada caminho testável independentemente. Adicione um bloco condicional IF / ELSE IF, depois use @Run sub-procedure em cada ramo: Para comparações complexas ou baseadas em datas, veja Como escrever condições de código para Fin Procedures.
IF Temporary.OrderAction == 'new': use @Run sub-procedure para invocar o subprocedimento Create New Order.
ELSE IF Temporary.OrderAction == 'existing': use @Run sub-procedure para invocar o subprocedimento Update Existing Order.
ELSE (fallback): escalar para a equipe
Passo 6: CREATE NEW ORDER (subprocedimento)
Mova este passo para um subprocedimento dedicado (ex.: "Create New Order") para manter o fluxo principal legível. Dentro desse subprocedimento, chame o conector Create Order Item. Atributos temporários como Temporary.SelectedProductID e Temporary.Quantity podem ser mapeados diretamente para as entradas do conector — sem necessidade de prompt manual:
product_id = Temporary.SelectedProductID
quantity = Temporary.Quantity
Capture a resposta em Temporary.NewOrderID (se retornado) e armazene o status_code do conector em Temporary.CreateOrderStatus.
Em caso de sucesso: responda:
“Pedido novo criado com [Temporary.Quantity] × [Temporary.SelectedProductName]. ID do pedido: [Temporary.NewOrderID]. Posso ajudar em mais alguma coisa?”Ofereça opções pós-ação (adicionar mais itens, alterar quantidade, finalizar compra, terminar). Persista Temporary.NewOrderID se continuar a sessão.
Adicione um passo de Condição imediatamente após a chamada do conector e ramifique com base em Temporary.CreateOrderStatus. O status_code e os atributos de erro podem aparecer no final do seletor de atributos — role para baixo se não os vir. Use os seguintes ramos: IF status_code == 200 ou 201: prossiga para a confirmação de sucesso. ELSE IF status_code == 400: informe ao cliente que a solicitação é inválida (ex.: ID do produto ou quantidade incorreta), peça para corrigir a entrada e ofereça uma nova tentativa. ELSE IF status_code >= 500: peça desculpas por um erro no servidor, capture o atributo de erro em uma nota interna para depuração e escale para a E-Comm Support Team. ELSE (status inesperado): registre Temporary.CreateOrderStatus e escale para a E-Comm Support Team. Para um guia mais detalhado sobre depuração de falhas de conector e interpretação de códigos de status, veja Solução de problemas em Fin Procedures e Data connectors.
Chamada do conector com entradas mapeadas e mapeamento de resposta (order_id → Temporary.NewOrderID).
Mensagem de confirmação pós-ação e opções.
Passo 7: UPDATE EXISTING ORDER (subprocedimento)
Prompt: “Por favor, forneça o ID do pedido existente ao qual deseja adicionar este item.” → salvar em Temporary.ExistingOrderID.
Chamada: conector Update Order Item com:
order_id = Temporary.ExistingOrderID
product_id = Temporary.SelectedProductID
quantity = Temporary.Quantity
Capture o status_code do conector em Temporary.UpdateOrderStatus e o campo de erro (se presente) em Temporary.UpdateOrderError.
Em caso de sucesso: responda:
“Adicionado [Temporary.Quantity] × [Temporary.SelectedProductName] ao pedido [Temporary.ExistingOrderID]. Mais alguma coisa?”
Ofereça opções pós-ação (adicionar mais itens, alterar quantidade, finalizar compra, terminar).Adicione um passo de Condição imediatamente após a chamada do conector e ramifique com base em Temporary.UpdateOrderStatus. Como no Passo 6, os atributos status_code e erro podem aparecer no final do seletor de atributos. Use os seguintes ramos: IF status_code == 200: prossiga para a confirmação de sucesso. ELSE IF status_code == 400: informe ao cliente que o ID do pedido pode ser inválido, peça para verificar e inserir novamente, e ofereça uma nova tentativa. ELSE IF status_code >= 500: peça desculpas por um erro no servidor, exiba Temporary.UpdateOrderError em uma nota interna e escale para a E-Comm Support Team. ELSE (status inesperado): registre o status e escale para a E-Comm Support Team. Veja Solução de problemas em Fin Procedures e Data connectors para orientação completa sobre diagnóstico de falhas de conector em conversas ao vivo.
Dica: Os atributos status_code e erro retornados por um Data Connector podem aparecer no final do seletor de atributos. Role para baixo se não os vir imediatamente — eles são essenciais para construir ramos robustos de tratamento de erros.
Coleta de ExistingOrderID e a chamada do conector Update que o utiliza.
Mensagem de confirmação pós-ação e opções.
Passo 8: FORA DE ESTOQUE
Dispare quando Temporary.StockLevel ≤ 0 ou quando a quantidade solicitada > disponível e o cliente recusar a quantidade reduzida.
Ações:
Peça desculpas e apresente opções claras:
Mostrar produtos similares (principais correspondências do catálogo).
Oferecer pedido em atraso/notificar quando disponível — registrar preferência de contato.
Oferecer quantidade parcial se disponível.
Se o cliente escolher notificar/pedido em atraso → registrar preferência e confirmar.
Se o cliente escolher uma alternativa → retornar ao Passo 1 (Consulta e pesquisa de produto) com a nova seleção.
Encerrar ou repetir conforme resposta do cliente.
Próximos passos
Depois que o fluxo principal do pedido estiver funcionando, considere esses padrões avançados para lidar com resultados mais complexos.
Transferir para um Workflow após a criação do pedido
Após um novo pedido bem-sucedido, transfira para um Workflow (por exemplo, "Enviar Confirmação de Pedido") para lidar com automações posteriores, como recibos por e-mail ou atualizações no CRM. Use um passo Handoff to workflow no final do seu subprocedimento Criar Novo Pedido. O procedimento termina na transferência e não retoma após o Workflow terminar, então faça deste o último passo.
Alternar procedimentos com base no resultado do pedido
Se o pedido resultar em um estado específico — por exemplo, um pedido em atraso ou um pagamento falhado — alterne para um procedimento dedicado (por exemplo, "Gerenciamento de Pedido em Atraso" ou "Recuperação de Falha de Pagamento") em vez de tratar todos os resultados em um único procedimento. Isso mantém os procedimentos individuais focados e mais fáceis de manter.
Escalar com contexto em falhas repetidas de API
Se o mesmo conector falhar na tentativa de nova execução (por exemplo, dois erros 500 consecutivos), escale para uma equipe humana e inclua uma nota interna resumindo Temporary.CreateOrderStatus ou Temporary.UpdateOrderError para que o colega tenha contexto completo sem precisar perguntar novamente ao cliente.
Encadear subprocedimentos para carrinhos com múltiplos itens
Para suportar clientes que pedem vários produtos em uma sessão, retorne ao subprocedimento Consulta de Produto após uma ação de pedido bem-sucedida e incremente um contador de itens. Encerre o loop quando o cliente confirmar que terminou.