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

# Registre seu Aplicativo

> Obtenha suas credenciais de cliente para começar a construir uma integração com a Vendaze.

Antes que seu aplicativo possa autenticar usuários da Vendaze, você precisa registrá-lo. O registro é aberto a qualquer desenvolvedor, sem processo de aprovação. Suas credenciais chegam por e-mail em segundos.

<Tip>
  Ainda não tem uma conta na Vendaze? [Crie gratuitamente](https://app.vendaze.com/register). Novas
  contas incluem 14 dias de teste para você construir e validar sua integração antes de solicitar
  acesso de usuários reais.
</Tip>

<Note>
  Cada endereço de e-mail pode estar associado a apenas um aplicativo registrado. Se você precisar
  atualizar o nome, as URIs de redirecionamento ou rotacionar as credenciais, use o endpoint de
  [rotação de credenciais](/pt/guides/rotate-app) em vez de registrar novamente.
</Note>

## O que você vai precisar

* Um endereço de e-mail válido para receber as credenciais (um aplicativo por e-mail)
* Pelo menos uma URI de redirecionamento HTTPS para o callback OAuth
* Uma decisão sobre quais escopos sua integração precisa

## Registrar via API

Envie um `POST` para `/v1/auth/register-app`:

```bash theme={null}
curl -X POST https://api.vendaze.com/v1/auth/register-app \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "Minha Integração",
    "email": "dev@meuapp.com",
    "description": "Sincroniza contatos e negócios entre a Vendaze e o MeuApp",
    "avatar_url": "https://meuapp.com/assets/logo.webp",
    "redirect_uris": ["https://meuapp.com/oauth/callback"],
    "scopes": ["people:read", "people:write", "deals:read"]
  }'
```

**Resposta (201):**

```json theme={null}
{
  "data": {
    "app_name": "Minha Integração",
    "client_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
    "avatar_url": "https://storage.vendaze.com/assets/integrations/minhaintegração.jpg",
    "message": "Credentials sent by email."
  }
}
```

Se o endereço de e-mail já estiver associado a um aplicativo registrado, a requisição é rejeitada:

**Resposta (409):**

```json theme={null}
{
  "error": {
    "code": "conflict",
    "message": "An app is already registered with this email address.",
    "request_id": "01966b3e-7c2a-7000-8f1e-4d3b2a1c0e9f"
  }
}
```

Para atualizar um aplicativo existente ou rotacionar suas credenciais, use o endpoint de [rotação de credenciais](/pt/guides/rotate-app) com seu `client_id` e e-mail cadastrado.

Seu `client_secret` é enviado **somente por e-mail** e nunca retorna na resposta da API. Guarde-o com segurança assim que receber.

## Parâmetros da requisição

| Parâmetro       | Tipo      | Obrigatório | Descrição                                                                                                             |
| --------------- | --------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `app_name`      | string    | Sim         | Nome da integração exibido aos usuários na tela de consentimento. Máx. 100 chars.                                     |
| `email`         | string    | Sim         | E-mail para receber as credenciais. Cada endereço pode estar associado a apenas um aplicativo registrado.             |
| `description`   | string    | Não         | Descrição curta do que seu app faz. Máx. 500 chars.                                                                   |
| `avatar_url`    | string    | Não         | URL HTTPS do logo do seu app. Formatos aceitos: JPEG, PNG, WebP, GIF, BMP, TIFF. Máx. 2MB.                            |
| `redirect_uris` | string\[] | Sim         | Uma ou mais URIs HTTPS para o callback OAuth. Correspondência exata obrigatória.                                      |
| `scopes`        | string\[] | Sim         | Escopos que seu app precisa. O usuário vê a lista completa na tela de consentimento e aprova ou nega tudo de uma vez. |

O `avatar_url` na resposta é sempre uma URL `https://storage.vendaze.com`.

## URIs de redirecionamento

As URIs devem ser URLs HTTPS exatas. Curingas e padrões não são aceitos:

```
Aceito:   https://meuapp.com/oauth/callback
Aceito:   https://meuapp.com/integracoes/vendaze/callback
Recusado: https://meuapp.com/oauth/*
Recusado: http://meuapp.com/callback
```

Durante o desenvolvimento local, `http://localhost` e `http://127.0.0.1` são aceitos.

Você pode registrar múltiplas URIs de redirecionamento para diferentes ambientes. Na hora da autorização, a `redirect_uri` da requisição precisa corresponder exatamente a uma das URIs registradas.

## Escopos disponíveis

| Escopo                | Descrição                                     |
| --------------------- | --------------------------------------------- |
| `people:read`         | Ler contatos (pessoas)                        |
| `people:write`        | Criar, atualizar, deletar pessoas             |
| `companies:read`      | Ler empresas                                  |
| `companies:write`     | Criar, atualizar, deletar empresas            |
| `deals:read`          | Ler negócios                                  |
| `deals:write`         | Criar, atualizar, deletar negócios            |
| `tasks:read`          | Ler tarefas                                   |
| `tasks:write`         | Criar, atualizar, deletar tarefas             |
| `activities:read`     | Ler atividades                                |
| `activities:write`    | Criar, deletar atividades                     |
| `products:read`       | Ler produtos                                  |
| `products:write`      | Criar, atualizar, deletar produtos            |
| `tags:read`           | Ler tags                                      |
| `tags:write`          | Criar, atualizar, deletar tags                |
| `lists:read`          | Ler listas                                    |
| `lists:write`         | Criar, atualizar, deletar listas              |
| `custom_fields:read`  | Ler campos customizados e seus valores        |
| `custom_fields:write` | Criar, atualizar, deletar campos customizados |

Solicitar um escopo durante o registro não garante que o usuário aprove o acesso. Na tela de consentimento, o usuário vê todos os escopos solicitados e pode apenas aprovar ou negar o acesso completo. Não é possível selecionar escopos individualmente.

<Warning>
  Seu `client_secret` aparece apenas uma vez, no e-mail que você recebe após o registro. Se
  perdê-lo, você pode rotacionar suas credenciais usando o `client_id` e o e-mail cadastrado. Nunca
  o comite em repositórios ou inclua em código client-side.
</Warning>

## Próxima etapa

Com seu `client_id` e `client_secret`, você está pronto para implementar o fluxo OAuth. Veja [Autenticação](/pt/guides/authentication) para autorizar seu primeiro usuário, ou [Rotacionar credenciais](/pt/guides/rotate-app) se precisar atualizar seu aplicativo depois.

Quando sua integração estiver completa e em produção, você pode solicitar o [selo Verificado](/pt/guides/verified-app) para listar seu aplicativo no marketplace da Vendaze e marcá-lo como confiável na tela de consentimento.