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

# Guias de integração com o QSmartHub

> Padrões para integrar o QSmartHub ao seu CRM, ERP, automações e agentes de IA combinando webhooks e a API de leitura.

As integrações do QSmartHub combinam duas peças: **webhooks** avisam quando algo acontece, e a **API de leitura** devolve o estado atual quando você precisa dele. Esta seção reúne padrões para os casos mais comuns. Guias passo a passo detalhados estão sendo adicionados.

> [!NOTE]
>
> O padrão central é sempre o mesmo: **reaja ao webhook, leia o detalhe pela API quando precisar de mais campos.** Como a v1 é de leitura, você reflete a operação no seu sistema, sem escrever de volta no QSmartHub.

## Casos de uso

> [card] CRM e ERP
>
> Espelhe senhas, chamadas e agendamentos no seu sistema de registro, para unir o atendimento presencial ao histórico do cliente.

> [card] Automação
>
> Dispare rotinas quando um evento chega: notificar uma equipe, atualizar um painel, abrir um chamado.

> [card] Agentes de IA
>
> Alimente um agente com os eventos em tempo real e deixe-o consultar a API de leitura para responder sobre a operação.

> [card] BI e relatórios
>
> Acumule os eventos de chamada e agendamento para medir tempos de espera e atendimento fora do QSmartHub.

## Padrão: espelhar o atendimento no seu sistema

Um fluxo típico para manter um registro externo em dia:

**1. Assine os eventos que importam**

Cadastre um webhook (veja [Webhooks](https://developers.qsmarthub.com/webhooks.md)) e assine, por exemplo, `ticket.created`, `call.called`, `call.completed` e `ticket.completed`.

**2. Valide e confirme rápido**

Ao receber a entrega, [valide a assinatura](https://developers.qsmarthub.com/webhooks/seguranca.md), responda `2xx` e enfileire o processamento. Use o `X-QSmartHub-Delivery` para ignorar duplicatas.

**3. Leia o detalhe quando precisar**

O evento traz os `id` envolvidos. Quando precisar de mais campos, chame a API: por exemplo, `GET /tickets/{id}` para o estado completo da senha, ou `GET /calls/{id}` para a chamada.

**4. Atualize o seu registro**

Grave ou atualize o registro correspondente no seu CRM, ERP ou data warehouse, usando o `id` do QSmartHub como chave estável.

> [!TIP]
>
> Precisa dos dados do cliente (nome, e-mail, telefone)? Eles não vêm nos webhooks. Gere uma chave com o escopo `customers:read` e leia-os pela API, no bloco `customer` de senhas e agendamentos.

## Antes de começar

> [card] [Começando](https://developers.qsmarthub.com/comecando.md)
>
> Gere a chave e faça a primeira requisição.

> [card] [Conceitos](https://developers.qsmarthub.com/conceitos.md)
>
> Entenda senha, chamada e ponto antes de modelar a integração.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.