Skip to main content

Como funciona o fluxo de autorização de um WooviApp?

Fluxo de autorização​

Depois de criar seu WooviApp e obter clientId/clientSecret, seu app pode solicitar acesso à conta Woovi de uma empresa através de um fluxo de autorização no estilo OAuth 2.0 (authorization code).

1. Redirecionando a empresa para a tela de consentimento​

Redirecione a empresa (a merchant que vai autorizar seu app) para:

https://store.woovi.com/authorize?client_id={clientId}&redirect_uri={redirectUri}&scope={scopes}&company_id={companyId}

Parâmetros de query:

  • client_id (obrigatório): o Client ID do seu WooviApp.
  • redirect_uri (obrigatório): uma das URIs cadastradas na criação do app. Se não corresponder a nenhuma URI registrada, a tela de consentimento retorna erro e a autorização não prossegue.
  • scope (opcional): lista de permissões separadas por espaço ou vírgula, restrita às permissões opcionais declaradas pelo app. As permissões obrigatórias são sempre solicitadas, independente deste parâmetro. Quando omitido, todas as permissões opcionais do app vêm pré-selecionadas na tela.
  • company_id (opcional): identificador da empresa que está autorizando. Quando omitido, a Woovi usa a empresa da sessão autenticada no momento.
info

A empresa precisa estar autenticada na Woovi (sessão via cookie) para chegar à tela de consentimento. Sem sessão ativa e sem company_id na URL, a tela exibe o aviso "nenhum contexto de empresa encontrado".

2. Comportamento da tela de consentimento​

A tela exibe o nome, logo, site e descrição do app, além de duas listas de permissões:

  • Obrigatórias: sempre marcadas, sem opção de desativar.
  • Opcionais: cada uma com um toggle individual, iniciando marcada ou não conforme o parâmetro scope recebido.

Se a empresa já havia autorizado esse app anteriormente, a tela mostra um estado de "app já autorizado", oferecendo apenas as opções de reautorizar ou cancelar.

3. Aprovação ou negação​

  • Autorizar: ao confirmar, a Woovi valida que todas as permissões solicitadas fazem parte do que o app declarou (obrigatórias + opcionais), gera um authorizationCode de uso único e redireciona a empresa para:

    {redirect_uri}?code={authorizationCode}

  • Negar: redireciona a empresa para:

    {redirect_uri}?error=access_denied
caution

O authorizationCode expira em 10 minutos e só pode ser trocado por uma aplicação da API da Woovi uma única vez. Se as permissões solicitadas excederem o que o app declarou na criação, a autorização é rejeitada com o erro Requested scopes exceed what the app declared.

4. Trocando o código por uma aplicação da API da Woovi​

Com o code recebido no redirect_uri, seu backend cria diretamente uma aplicação da API da Woovi (com clientId/clientSecret próprios, escopados pelas permissões concedidas) para consumir a API pública da Woovi. A troca do code pelo token de acesso acontece internamente, servidor a servidor — você não precisa (nem consegue) chamar esse passo intermediário diretamente:

POST https://api.woovi.com/api/v1/woovi-apps/application
Content-Type: application/json
Authorization: {seu appID}

Authorization: Você precisa de um appID da sua empresa com o escopo WOOVI_APP_APPLICATION_POST para poder fazer essa troca.

{
  "code": "authorization-code-recebido",
  "client_id": "seu-client-id",
  "client_secret": "seu-client-secret"
}
  • code, client_id, client_secret (obrigatórios): o código de autorização recebido no callback e as credenciais do seu WooviApp. A Woovi valida essas informações antes de prosseguir.

O nome da aplicação criada é gerado automaticamente a partir da empresa dona do WooviApp, o tipo é sempre API, e os escopos são exatamente os que a empresa concedeu na tela de autorização — não há como sobrescrever nenhum desses valores por esta rota.

Resposta (201):

{
  "application": {
    "name": "WooviApp - Minha Empresa",
    "isActive": true,
    "type": "API",
    "clientId": "a1b2c3d4e5f6...",
    "clientSecret": "9f8e7d6c5b4a...",
    "appID": "...",
    "scopes": ["CHARGE_GET", "CHARGE_GET_LIST"]
  }
}

Possíveis erros: invalid_request (faltam code, client_id ou client_secret), invalid_client (client_id/secret inválidos), invalid_grant (código inexistente, expirado ou já utilizado) e unsupported_grant_type (não deveria ocorrer neste fluxo, mas é retornado por completude caso o tipo de concessão internamente usado não seja suportado).

caution

O clientSecret desta aplicação também é exibido apenas nesta resposta — armazene-o com segurança. Use clientId/clientSecret (ou o appID) para autenticar as próximas chamadas na API pública da Woovi, já restritas aos escopos concedidos pela empresa.

Revogação​

A empresa pode revogar o acesso concedido a um app a qualquer momento pela tela de apps autorizados em store.woovi.com/authorized-apps. A revogação invalida o access token imediatamente.