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

# Discord Entitlement

> Conceda aos seus clientes um papel no seu servidor Discord quando eles comprarem, e revogue automaticamente quando a assinatura terminar.

<Info>
  A titularidade do Discord adiciona um cliente pagante ao seu servidor (e, opcionalmente, atribui-lhes um papel) no momento em que sua assinatura se torna ativa ou quando sua compra única é confirmada. Cancelamentos, reembolsos e alterações de plano revogam o papel automaticamente.
</Info>

## O que é entregue

* O cliente conecta sua conta Discord por meio de um link OAuth no e-mail de entrega ou portal do cliente.
* Uma vez autorizado, o Dodo Payments os adiciona ao seu servidor (ou encontra sua associação existente) e atribui o papel que você configurou.
* Se você não escolher um papel específico, apenas a associação ao servidor é concedida.

Esta integração é ideal para comunidades pagas, benefícios para apoiadores e canais de acesso por nível.

## Conectar Discord

<Steps>
  <Step title="Open Entitlements">
    No painel do Dodo Payments, vá para **Entitlements** e clique em **+** para iniciar uma nova titularidade.
  </Step>

  <Step title="Pick Discord">
    Escolha **Discord Access** como a integração. Se você ainda não conectou o Discord para o seu negócio, será solicitado que **Conecte o Discord**.

    <Frame caption="Connect Discord prompt before the OAuth handoff.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/discord/connect-prompt.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=8a34c436dd7510942db2a9221f623938" alt="Novo painel de titularidade solicitando ao comerciante para conectar o Discord" style={{ maxHeight: '500px', width: 'auto' }} width="2844" height="1622" data-path="images/entitlements/discord/connect-prompt.png" />
    </Frame>

    Ao clicar, o Discord será aberto em uma nova aba. Faça login, escolha o servidor que deseja proteger e confirme as permissões do bot (Gerenciar Papéis, Expulsar Membros, Criar Convite) nesse servidor.

    <Frame caption="Discord OAuth: pick the server, then confirm the bot's permissions on it.">
      <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '12px', alignItems: 'center', justifyItems: 'center' }}>
        <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/discord/oauth-add-bot.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=b57bf306fa15aa3f49b528f803cc625e" alt="Tela OAuth do Discord perguntando em qual servidor adicionar o bot do Dodo Payments" style={{ width: '100%', maxHeight: '420px', objectFit: 'contain' }} width="1026" height="1362" data-path="images/entitlements/discord/oauth-add-bot.png" />

        <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/discord/oauth-permissions.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=438c0b04177e3a4863fb90986f5b95e0" alt="Tela de confirmação de permissões do bot do Discord" style={{ width: '100%', maxHeight: '420px', objectFit: 'contain' }} width="1038" height="1472" data-path="images/entitlements/discord/oauth-permissions.png" />
      </div>
    </Frame>

    Quando o Discord redirecionar de volta, você verá uma confirmação de que o servidor está conectado.

    <Frame caption="Server connected — return to the Dodo Payments dashboard to continue.">
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/discord/connected.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=bd1cbb3f9960e4eb1881d7a818dc6f16" alt="Página de confirmação de conexão bem-sucedida do Acesso ao Discord" style={{ maxHeight: '500px', width: 'auto' }} width="2000" height="1140" data-path="images/entitlements/discord/connected.png" />
    </Frame>
  </Step>

  <Step title="Pick a server and role">
    De volta ao painel, selecione o **servidor** (guilda) que você acabou de conectar. Opcionalmente escolha um **papel** para atribuir na entrega, ou deixe em branco para conceder apenas a associação ao servidor. Dê um **nome** à titularidade e clique em **Criar Titularidade**.

    <Frame>
      <img src="https://mintcdn.com/dodopayments/do-W-dMDGVB_xzr_/images/entitlements/discord/create.png?fit=max&auto=format&n=do-W-dMDGVB_xzr_&q=85&s=79e95041881d2925e58fc752280d508e" alt="Nova Titularidade - Formulário de Acesso ao Discord com servidor conectado, seletor de servidor, dropdown de papéis e campo de nome" style={{ maxHeight: '500px', width: 'auto' }} width="1196" height="1564" data-path="images/entitlements/discord/create.png" />
    </Frame>
  </Step>

  <Step title="Save the entitlement">
    Salve a titularidade. Agora está disponível para anexar a qualquer produto.
  </Step>
</Steps>

## Fluxo do cliente

1. O cliente completa a compra.
2. Dodo Payments cria uma concessão em `pending` status com um `oauth_url` apontando para o Discord.
3. O cliente recebe um e-mail com um botão "Join the Discord" (o link OAuth). O link também está visível em seu portal do cliente.
4. Após a autorização do cliente, o bot os adiciona ao servidor e atribui o papel configurado. A concessão muda para `delivered`.
5. Se a assinatura for cancelada, pausada ou expirou, ou se o comerciante revogar manualmente, o bot remove o papel e a concessão muda para `revoked`.

<Tip>
  Certifique-se de que o papel do bot do Dodo Payments esteja posicionado **acima** do papel que você concede. O Discord impede bots de atribuírem papéis com classificação mais alta que a deles.
</Tip>

## Configuração necessária

| Campo      | Obrigatório | Descrição                                                                                |
| ---------- | ----------- | ---------------------------------------------------------------------------------------- |
| `guild_id` | Sim         | ID do servidor do Discord. O seletor do painel preenche isso para você.                  |
| `role_id`  | Não         | O papel a ser atribuído na entrega. Omitir para acesso somente à associação ao servidor. |

## Criar via API

<CodeGroup>
  ```typescript TypeScript theme={null} theme={null}
  import DodoPayments from 'dodopayments';

  const client = new DodoPayments({
    bearerToken: process.env['DODO_PAYMENTS_API_KEY'],
    environment: 'test_mode',
  });

  const entitlement = await client.entitlements.create({
    name: 'Patrons Discord Role',
    integration_type: 'discord',
    integration_config: {
      guild_id: '123456789012345678',
      role_id: '987654321098765432',
    },
  });
  ```

  ```python Python theme={null} theme={null}
  client.entitlements.create(
      name="Patrons Discord Role",
      integration_type="discord",
      integration_config={
          "guild_id": "123456789012345678",
          "role_id": "987654321098765432",
      },
  )
  ```

  ```go Go theme={null} theme={null}
  client.Entitlements.New(ctx, dodopayments.EntitlementNewParams{
    Name:            dodopayments.F("Patrons Discord Role"),
    IntegrationType: dodopayments.F(dodopayments.EntitlementIntegrationTypeDiscord),
    IntegrationConfig: dodopayments.F[dodopayments.IntegrationConfigUnionParam](
      dodopayments.IntegrationConfigDiscordConfigParam{
        GuildID: dodopayments.F("123456789012345678"),
        RoleID:  dodopayments.F("987654321098765432"),
      },
    ),
  })
  ```
</CodeGroup>

## Webhooks

Inscreva-se nos [eventos do webhook `entitlement_grant.*`](/developer-resources/webhooks/intents/entitlement-grant) para acompanhar as concessões do Discord:

* `entitlement_grant.created` é acionado com `status: "pending"` e um `oauth_url` para o cliente autorizar.
* `entitlement_grant.delivered` é acionado assim que o papel é atribuído.
* `entitlement_grant.revoked` é acionado quando o papel é removido.

## Solução de problemas

<AccordionGroup>
  <Accordion title="Customer never sees the role assigned">
    A concessão está em `pending` até o cliente completar o fluxo OAuth. Verifique a lista de concessões da titularidade e confirme se eles clicaram no link OAuth. Reenvie o e-mail de entrega, se necessário.
  </Accordion>

  <Accordion title="Grant moves to failed with permission errors">
    Certifique-se de que o bot do Dodo Payments permaneça no servidor, tenha permissão `Manage Roles` e esteja posicionado acima do papel sendo atribuído. Re-salvar a titularidade re-executa a validação.
  </Accordion>

  <Accordion title="Customer cancelled but still has the role">
    O Discord propaga remoções de papel imediatamente, mas o cliente local do Discord pode fazer cache. Eles devem reconectar ou atualizar; o estado no servidor está correto.
  </Accordion>
</AccordionGroup>