Registre seu Aplicativo

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.

Ainda não tem uma conta na Vendaze? Crie gratuitamente. Novas contas incluem 14 dias de teste para você construir e validar sua integração antes de solicitar acesso de usuários reais.

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 em vez de registrar novamente.

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:

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):

{
  "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):

{
  "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 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.

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.

Próxima etapa

Com seu client_id e client_secret, você está pronto para implementar o fluxo OAuth. Veja Autenticação para autorizar seu primeiro usuário, ou Rotacionar credenciais se precisar atualizar seu aplicativo depois. Quando sua integração estiver completa e em produção, você pode solicitar o selo Verificado para listar seu aplicativo no marketplace da Vendaze e marcá-lo como confiável na tela de consentimento.

Visão Geral

Começando

Utilizando a API

Boas Práticas

O que você vai precisar

Registrar via API

Parâmetros da requisição

URIs de redirecionamento

Escopos disponíveis

Próxima etapa

​O que você vai precisar

​Registrar via API

​Parâmetros da requisição

​URIs de redirecionamento

​Escopos disponíveis

​Próxima etapa

O que você vai precisar

Registrar via API

Parâmetros da requisição

URIs de redirecionamento

Escopos disponíveis

Próxima etapa