Conectores de dados permitem que Fin interaja com sistemas externos via endpoints de API. Fin pode usar conectores de dados para:
Ler informações do conector de dados (por exemplo, qual plano o usuário possui).
Realizar ações (por exemplo, usar um POST para cancelar uma assinatura em um sistema externo).
Começar
Adicionando um conector de dados a uma etapa de Instrução
Dentro de uma etapa de Instrução, digite @ para abrir o menu de ferramentas.
Selecione Chamar conector de dados.
Escolha o conector específico que deseja executar (por exemplo, Obter pedidos para recuperar o histórico de compras de um cliente).
Dica: Aprenda como configurar conectores de dados para puxar informações ao vivo dos seus sistemas internos ou APIs de terceiros diretamente para seus Fin Procedures.
Acesse a resposta usando atributos gerados automaticamente
Uma vez que um conector é adicionado, você pode acessar imediatamente a resposta em etapas subsequentes. Isso está disponível para Fin como contexto geral, mas também analisamos os campos da resposta nos conectores de dados para permitir que você se refira explicitamente a itens no corpo da resposta para maior confiabilidade.
Nota: O mapeamento da resposta não é necessário ao usar conectores de dados em Procedures. Fin usa a resposta de teste que você configura no conector de dados para entender a estrutura da resposta da API com os nomes de campos disponíveis e seus tipos. Você pode então usar linguagem simples nas instruções do procedimento para dizer ao Fin quais dados da resposta usar. Em tempo de execução, Fin faz uma chamada de API ao vivo e lê os valores reais desses campos.
Digite @ e selecione Ler um atributo.
Você verá os campos de resposta do conector de dados listados automaticamente no topo do menu suspenso (por exemplo, Obter pedido de entrega > status, Obter pedido de entrega > order_id).
Selecione o atributo específico que você precisa para inseri-lo em sua instrução ou condição.
O contexto é compartilhado em todo o Procedure
Quando você instrui o Fin a usar um conector de dados (@ use data connector), os dados retornados ficam disponíveis durante todo o procedimento.
Para maior confiabilidade, você pode acessar esses dados usando (@ read attributes). Fin mantém os dados do conector durante toda a duração de um Procedure, incluindo todas as etapas e subprocedimentos. Você só precisa chamar cada conector uma vez por Procedure, a menos que precise explicitamente de dados atualizados.
Por exemplo, se você chamar (@ use Get_Subscription_info) na primeira etapa, Fin manterá o contexto da assinatura do cliente para todas as etapas e subprocedimentos subsequentes.
Melhores práticas
Aproveite os conectores de dados simulados para testar e começar a construir seu procedimento
Você não precisa de uma API ao vivo totalmente construída para começar a criar procedimentos. Pode usar respostas de exemplo para simular dados.
Resposta de exemplo: Na configuração do Conector de Dados (na aba "Resposta de teste"), selecione Resposta de exemplo e cole um payload JSON simulado. Isso permite que você construa e teste o fluxo do procedimento imediatamente.
Simulação dinâmica: Para cenários mais complexos, você pode usar ferramentas como Beeceptor para simular respostas dinâmicas de API.
Otimize suas respostas de API para serem o menor subconjunto possível de dados relevantes que o Fin precisa para o procedimento
Dados irrelevantes em excesso podem impactar o desempenho. Geralmente, quanto menor e mais preciso, melhor.
Se uma transformação de dados for necessária, é fortemente recomendado que você transforme os dados selecionando um número limitado de campos ou usando blocos de código do conector de dados. Isso transformará a resposta da API antes que o Fin a veja no procedimento.
Otimize para usar no máximo um conector de dados por etapa
Uma etapa deve ser uma única unidade de trabalho. Fin é mais confiável quando você chama apenas um conector de dados em uma única etapa.
Chame conectores de dados uma vez por contexto
Em Procedures, “contexto” refere-se à execução inteira do Procedure. Fin reutiliza automaticamente os dados do conector em todas as etapas e subprocedimentos. Você não precisa chamar a mesma API duas vezes.
❌ Não é necessário chamar o mesmo conector duas vezes em etapas diferentes:
Step 1:
… (@use Get_Subscription_info) … and include @read plan status in your response so the users knows
Step 2
… (@use Get_Subscription_info) … and include @read refund eligibility in your response so the users knows
✅ É mais simples, limpo e rápido chamar o conector apenas uma vez:
Step 1:
… (@use Get_Subscription_info) … include @read plan status in your response so the users knows
Step 2
… include @read refund eligibility in your response so the users knows
Se você precisar de dados de múltiplos sistemas, divida a lógica em várias etapas em vez de chamar vários conectores em uma única etapa.
Não há necessidade de pedir ao Fin para coletar dados que já estão configurados como entradas obrigatórias para um conector de dados
As entradas são pré-configuradas durante a configuração do conector de dados, então o Fin deduz as entradas que precisa coletar para chamar o conector de dados sem que você precise pedir explicitamente ao Fin para coletar esses dados.
Por exemplo, se o conector de dados Get Order Details já tem o campo de entrada email configurado:
❌ Instrução desnecessariamente complexa:
First ask the customer for their email, then call @get_order_details with that email
✅ Instruções claras:
Call @get_order_details
Fin deduz e coleta automaticamente as entradas necessárias com base na configuração do conector, a menos que a entrada já seja fornecida diretamente pelo Intercom.
Nota: Se você notar problemas de desempenho ou confiabilidade na coleta de entradas, pode solicitar explicitamente ao Fin quando coletar esses dados.
Dica profissional: Quando um Procedure requer dados precisos, não modificados ou seguros (por exemplo, email, ID do usuário ou informações da conta), injete esses valores diretamente do Intercom no conector. Ao configurar o atributo diretamente no conector em vez de como uma entrada coletada pelo Fin, os dados evitam a coleta ou processamento do Fin e permanecem inalterados.
Monitorando a saúde do conector
Procedures que usam conectores de dados mostram um indicador de saúde diretamente na página da lista de procedimentos, para que você possa identificar problemas do conector rapidamente sem abrir cada procedimento. O selo reflete o conector com pior desempenho usado por aquele procedimento, calculado nos últimos 14 dias (limitado a 1.000 execuções por conector).
Procedures sem conectores de dados não mostram indicador; conectores com zero execuções são considerados saudáveis.
Status de saúde
Status | Critério | Implicação |
🟢 Saudável | Todos os conectores têm taxa de sucesso >95% e tamanho médio da resposta abaixo de 50KB. | Operando de forma ideal. |
🟡 Degradado | Qualquer conector tem taxa de sucesso entre 80–95%, ou taxa de sucesso >95% mas tamanho médio da resposta ≥50KB (~15K tokens). | Apresentando problemas ou retornando respostas grandes que podem aumentar o risco de alucinação. |
🔴 Não saudável | Qualquer conector tem taxa de sucesso <80%, ou tamanho médio da resposta ≥100KB (~30K tokens). | Problemas críticos ou respostas perigosamente grandes que requerem atenção imediata. |
Detalhamento
Clicar no selo de saúde abre uma gaveta com um detalhamento por conector: status, taxa de sucesso, tamanho médio da resposta, latência P90 e principais erros. Os nomes dos conectores linkam diretamente para a página de configurações para depuração rápida.
Dica: Se um conector estiver mostrando Degradado ou Não saudável devido ao tamanho da resposta, veja a Melhor prática de otimizar suas respostas de API para serem o menor subconjunto possível de dados relevantes que o Fin precisa acima; filtrar campos ou usar blocos de código para reduzir a resposta antes que o Fin a veja é a correção mais rápida.
Manipulando arrays
Quando um conector de dados retorna uma lista, o Fin expõe apenas o array raiz como um atributo. Elementos filhos dentro do array não são expostos como atributos separados no seletor de atributos.
Por exemplo, se um conector retorna um array items, você verá:
Obter pedidos > items
Mas você não verá:
Obter pedidos > items > titleObter pedidos > items > price
O Fin ainda pode trabalhar com o conteúdo de uma lista. Por exemplo, se você fornecer a seguinte instrução: "Se o cliente perguntar o que há no pedido, use Obter pedido > items para listar os produtos e seus preços."
O Fin lerá o conteúdo completo da lista de items e responderá com: "Seu pedido inclui um Mouse Sem Fio (R$24,99) e um Suporte para Laptop (R$39,99)."
Por exemplo: Para o payload de resposta abaixo, apenas o elemento do array raiz items é exposto como um atributo temporário e não seus filhos.
{
"order_id": "ORD-1001",
"status": "processing",
"created_at": "2025-01-12T14:23:00Z",
"items": [
{
"product_id": "PROD-200",
"name": "Wireless Mouse",
"quantity": 1,
"unit_price": 24.99
},
{
"product_id": "PROD-122",
"name": "Laptop Stand",
"quantity": 1,
"unit_price": 39.99
}
]
}
Nota: @Read Obter pedidos > items e diga ao cliente os três principais itens do pedido.
Usando arrays em condições de código
Atributos de array estão disponíveis sob o objeto inputs["data_connector"], agrupados pelo nome do conector de dados. Arrays são indexados em zero, o que significa que o primeiro item está no índice 0. Sempre verifique o comprimento do array antes de acessar um índice específico.
Você ainda pode consultar valores dentro de um array usando uma condição de código.
Em condições de código, os dados do array são acessados usando expressões Python, onde você referencia explicitamente os itens por índice ou itera sobre a lista.
Esta condição verifica se o pedido contém pelo menos quatro itens e se a quantidade do quarto item é maior que três.
Sempre valide o comprimento do array antes de acessar um índice para evitar erros em tempo de execução durante a avaliação da condição.
Nota: As ações disponíveis dependem de como seu conector de dados está configurado.
Conectores de dados suportam:
Criar: Use requisições POST para criar novos registros em um sistema externo.
Ler: Use requisições GET para recuperar dados existentes.
Atualizar: Use requisições PUT ou PATCH para modificar registros existentes.
Excluir: Use requisições DELETE para remover registros.