> ## Documentation Index
> Fetch the complete documentation index at: https://docs.play2sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrações Customizadas

> Construa integrações personalizadas com o SalesOS usando a API REST e webhooks.

# Integrações Customizadas

Construa integrações sob medida para conectar o SalesOS aos seus sistemas internos usando a API REST e webhooks.

## Abordagens de integração

<CardGroup cols={3}>
  <Card title="API REST" icon="code">
    Faça requisições diretas à API para ler e escrever dados no SalesOS.
  </Card>

  <Card title="Webhooks" icon="globe">
    Receba eventos em tempo real e reaja automaticamente.
  </Card>

  <Card title="SalesOS Connect" icon="plug">
    Use webhooks para reagir a eventos sem manter um serviço próprio.
  </Card>
</CardGroup>

## Guia de implementação

<Steps>
  <Step title="Defina o escopo">
    Identifique quais dados precisam ser sincronizados e em qual direção (SalesOS para seu sistema, vice-versa, ou ambos).
  </Step>

  <Step title="Obtenha credenciais">
    Gere um Client ID e Secret em **Configurações > API > Credenciais**.
  </Step>

  <Step title="Implemente a autenticação">
    Configure o fluxo de autenticação OAuth2 para obter tokens JWT.
  </Step>

  <Step title="Desenvolva a integração">
    Implemente as chamadas à API e/ou configure webhooks para eventos.
  </Step>

  <Step title="Teste em ambiente seguro">
    Valide a integração completamente antes de ativá-la em produção.
  </Step>

  <Step title="Monitore">
    Acompanhe logs de webhook e métricas da API para garantir funcionamento correto.
  </Step>
</Steps>

## Cenários comuns

<AccordionGroup>
  <Accordion title="Formulário web para leads">
    Seu site captura leads em formulários e envia para o SalesOS via `POST /v1/leads`. Ideal para landing pages, chatbots e formulários de contato.
  </Accordion>

  <Accordion title="Sincronização com CRM legado">
    Exporte dados do CRM antigo para o SalesOS via API em lote, ou mantenha ambos sincronizados durante o período de migração.
  </Accordion>

  <Accordion title="Dashboard externo de BI">
    Consuma dados de leads, deals e métricas via API para alimentar dashboards em ferramentas como Power BI, Metabase ou Grafana.
  </Accordion>

  <Accordion title="Notificações em sistemas de comunicação">
    Configure webhooks para enviar notificações de eventos (deal ganho, novo lead) para Slack, Microsoft Teams ou Discord.
  </Accordion>

  <Accordion title="Integração com sistema financeiro">
    Ao fechar um deal, envie os dados para seu sistema financeiro via webhook ou chamada API para gerar pedidos, contratos ou faturas.
  </Accordion>
</AccordionGroup>

## Boas práticas

<Tabs>
  <Tab title="Segurança">
    * Armazene credenciais em variáveis de ambiente, nunca no código
    * Valide assinaturas de webhooks antes de processar
    * Use HTTPS em todos os endpoints
    * Implemente rate limiting no seu lado
  </Tab>

  <Tab title="Resiliência">
    * Implemente retentativas com backoff exponencial
    * Trate erros de rate limit (429) com espera adequada
    * Armazene payloads de webhook para reprocessamento em caso de falha
    * Implemente idempotência para evitar duplicatas
  </Tab>

  <Tab title="Performance">
    * Use paginação ao listar grandes volumes de dados
    * Cache dados que mudam pouco (equipes, etapas do pipeline)
    * Processe webhooks de forma assíncrona
    * Limite a frequência de polling se não usar webhooks
  </Tab>
</Tabs>

<Tip>
  Para reagir a eventos sem manter um serviço próprio, comece pelos [webhooks](/pt/api/integrations/webhooks).
</Tip>

<Warning>
  Respeite o rate limit da API (100 requisições/minuto). Integrações que excedem consistentemente o limite podem ter o acesso temporariamente bloqueado.
</Warning>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Autenticação" icon="lock" href="/pt/api/authentication">
    Configure a autenticação da sua integração.
  </Card>

  <Card title="Webhooks" icon="globe" href="/pt/api/integrations/webhooks">
    Receba eventos em tempo real.
  </Card>
</CardGroup>