Zapier, Make e n8n

As plataformas de integração conectam o Sursa a centenas de outras ferramentas sem código. Elas não precisam de um app dedicado do Sursa: as etapas genéricas de requisição HTTP e de webhook delas funcionam diretamente com a API. Este guia trata das três receitas mais comuns:

Seja qual for a plataforma, guarde a chave no cofre de credenciais ou de conexões dela, e não na própria etapa, para que a chave não seja copiada para cada cenário e para cada log de execução.

Enviar registros como cartões

Crie uma fonte personalizada no Sursa (Sources → New source → Custom source: fontes, nova fonte, fonte personalizada) e depois uma chave para ela na página da fonte, em API keys (chaves de API da fonte). A chave começa com kbsrc_ e só pode gravar documentos nesta fonte, o que faz dela a chave certa para guardar em uma plataforma de terceiros.

A configuração comum é “quando um registro for criado ou atualizado em X, envie-o ao Sursa”:

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• Mapeie para external_id um ID estável do registro, nunca um horário ou um número de execução. Assim, enviar o mesmo registro de novo atualiza o mesmo cartão, e uma etapa repetida não causa danos: a resposta é unchanged.
• Para um gatilho de “registro excluído”, acrescente um segundo fluxo de trabalho com o método DELETE e a URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Teste a conexão com GET https://api.example.com/v1/push/sources/42 e o mesmo cabeçalho Authorization. Ele retorna o nome da fonte e o número de documentos dela.

Os campos do documento são os mesmos que no código.

Zapier

Use a ação Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: desativado. Data: o JSON acima, com os campos inseridos a partir do gatilho.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Use o módulo HTTP → Make a request:

• Method POST, URL como acima, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: o JSON acima, com os valores mapeados.
• Ative Parse response para usar result (created, updated, unchanged) nos módulos seguintes.
• Para enviar um arquivo, escolha Body type Multipart/form-data, com um campo file (o arquivo de um módulo anterior) e um campo de texto document com os campos JSON sem content.

n8n

Use o nó HTTP Request:

• Method POST, URL como acima.
• Authentication Generic Credential Type → Header Auth, com o nome Authorization e o valor Bearer kbsrc_….
• Send Body ativado, Body Content Type JSON, campos mapeados com expressões como {{ $json.id }}.

Para uma exportação completa agendada, encadeie três nós HTTP Request: abra uma sincronização (POST …/syncs com {"type": "initial"} na primeira vez e {"type": "incremental"} nas seguintes), envie os itens e feche a sincronização com {"status": "complete"}. O n8n executa um nó uma vez por item; para enviar menos requisições, agrupe os itens com um nó Aggregate e envie-os para …/documents/batch como {"sync_number": …, "documents": [...]}.

Fazer uma pergunta em um fluxo de trabalho

Um fluxo de trabalho pode perguntar ao Sursa e usar a resposta: redigir uma resposta a um chamado de suporte, enriquecer um registro do CRM, publicar uma resposta em um canal de chat. Use uma chave de API da organização com o escopo ask e uma função que veja as coleções certas.

A resposta traz o texto da resposta em answer (Markdown) e as fontes dele em sources, cada uma com doc_name. Quando a base de conhecimento não tem nada sobre a pergunta, empty é preenchido (por exemplo, no_hits): acrescente uma etapa de filtro para que o fluxo de trabalho não publique uma resposta vazia. Veja Criar um bot de perguntas e respostas.

As respostas podem levar vários segundos. Se a etapa HTTP da plataforma tiver um tempo limite padrão curto, aumente-o para pelo menos 60 segundos.

Iniciar um fluxo de trabalho a partir de um evento do Sursa

Todas as plataformas podem receber webhooks:

1. Crie o gatilho e copie o endereço HTTPS que ele fornece.
2. No Sursa, registre um webhook com esse endereço e os eventos que você quer, em Administration → Integrations → Webhooks and API (administração, integrações, webhooks) ou com POST /v1/webhooks.
3. Envie um evento de teste pela página do webhook e mapeie os campos do evento (type, data.card.title, …) nas etapas seguintes.

Verifique a assinatura. O endereço do gatilho é público: qualquer pessoa que o descubra pode enviar requisições para ele. Verifique a assinatura de cada entrega antes de agir com base nela, principalmente se o fluxo de trabalho altera dados:

• No n8n, acrescente um nó Code depois do nó Webhook, com a verificação de assinaturas em Node.js de Receber webhooks, e ative a opção de corpo bruto do nó Webhook para que os bytes exatos fiquem disponíveis.
• No Zapier e no Make, onde é mais difícil chegar ao corpo bruto, pelo menos mantenha o endereço em segredo, filtre por type e leia o objeto de novo pela API antes de agir com base nele.

As novas tentativas e as duplicatas valem para as plataformas como para qualquer receptor: filtre pelo id do evento se uma execução duplicada puder causar danos.

Dicas

• Em um 429, deixe a nova tentativa automática da plataforma aguardar os segundos de Retry-After. Prefira lotes para exportações grandes.
• As plataformas registram cada requisição e cada resposta. Nunca coloque uma chave em uma URL e prefira a chave kbsrc_ sempre que o fluxo de trabalho só gravar documentos.
• Se uma etapa falhar com 401 sources.push_key_invalid, verifique se o ID da fonte na URL corresponde à chave.