Solicitação de Autorização

A solicitação de autorização é o mecanismo que permite aos parceiros solicitar acesso aos dados de clientes da conta digital Nuvende. Este processo garante que o cliente tenha controle total sobre quais dados serão compartilhados e para qual finalidade.

Visão Geral do Fluxo

O processo de autorização funciona da seguinte forma:

1. Solicitação: Parceiro cria uma solicitação via API informando dados do cliente
2. Notificação: Cliente recebe notificação no aplicativo Nuvende
3. Decisão: Cliente aprova ou rejeita a solicitação
4. Webhook: Parceiro recebe a decisão via webhook
5. Integração: Se aprovado, parceiro recebe credenciais para integração

Funcionalidades Disponíveis

Quando um cliente autoriza uma aplicação, o parceiro pode:

• Consultar saldo da conta digital
• Acessar extrato de transações
• Criar cobranças Pix em nome do cliente
• Processar pagamentos via cartão de crédito em terminais Nuvende

Importante: Transferências e pagamentos diretos não são permitidos por questões de segurança.

Endpoints Disponíveis

Criar Solicitação de Autorização

POST /api/v2/partners/requests

Cria uma nova solicitação de autorização vinculada a uma aplicação específica.

curl --location 'https://api-h.nuvende.com.br/api/v2/partners/requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "application_id": "abnks92-cb57-4ee3-a997-655fb5d0ea45",
  "name": "João Silva",
  "document": "12345678901",
  "email": "[email protected]",
  "phone": "11999999999",
  "origin": "partner",
  "scopes": [
    "cob.read",
    "cob.write"
  ],
  "webhook_url": "https://meusite.com/webhook",
  "metadata": [
    "Solicitação via app mobile",
    "Cliente VIP"
  ]
}'

Parâmetros

Resposta de Sucesso

{
  "id": "c3sdaa792-f8b6-4fe1-ad19-f8ea16a723c5",
  "partner": {
    "id": "650c723160-98d9-45d3-a1e0-eb24db30d22e",
    "name": "Nome do Parceiro",
    "contact_email": "[email protected]",
    "contact_phone": "11999999999",
    "status": "active"
  },
  "application": {
    "id": "2fdd5217-cb57-4ee3-a997-655fb5d0ea45",
    "name": "Minha Aplicação",
    "description": "Descrição da aplicação",
    "scopes": [
      "cob.read",
      "cob.write"
    ],
    "status": "active"
  },
  "status": "pending",
  "scopes": [
    "cob.read",
    "cob.write"
  ],
  "origin": "partner",
  "name": "João Silva",
  "document": "12345678901",
  "email": "[email protected]",
  "phone": "11999999999",
  "webhook_url": "https://meusite.com/webhook",
  "decision_at": null,
  "user_id": null,
  "account_id": null,
  "metadata": [
    "Solicitação via app mobile",
    "Cliente VIP"
  ],
  "created_at": "2025-01-15T14:27:14-03:00",
  "updated_at": "2025-01-15T14:27:14-03:00"
}

Listar Solicitações

GET /api/v2/partners/requests

Lista todas as solicitações realizadas pelo parceiro autenticado.

curl --location 'https://api-h.nuvende.com.br/api/v2/partners/requests' \
--header 'Authorization: Bearer {access_token}'

Parâmetros de Query

Resposta

{
  "data": [
    {
      "id": "c3sdaa792-f8b6-4fe1-ad19-f8ea16a723c5",
      "status": "approved",
      "scopes": [
        "cob.read",
        "cob.write"
      ],
      "name": "João Silva",
      "document": "12345678901",
      "email": "[email protected]",
      "phone": "11999999999",
      "decision_at": "2025-01-15T15:30:00-03:00",
      "created_at": "2025-01-15T14:27:14-03:00"
    }
  ],
  "links": {
    "first": "https://api-h.nuvende.com.br/api/v2/partners/requests?page=1",
    "last": "https://api-h.nuvende.com.br/api/v2/partners/requests?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Status das Solicitações

Fluxo Detalhado

1. Criação da Solicitação

const createAuthorizationRequest = async (token, requestData) => {
  const response = await fetch('https://api-h.nuvende.com.br/api/v2/partners/requests', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      application_id: requestData.applicationId,
      name: requestData.clientName,
      document: requestData.clientDocument,
      email: requestData.clientEmail,
      phone: requestData.clientPhone,
      origin: 'partner',
      scopes: requestData.scopes,
      webhook_url: requestData.webhookUrl,
      metadata: requestData.metadata
    })
  });

  if (!response.ok) {
    throw new Error(`Erro ao criar solicitação: ${response.status}`);
  }

  return response.json();
};

2. Notificação ao Cliente

Após a criação da solicitação:

1. Sistema cruza CPF/CNPJ com usuários cadastrados
2. Cliente recebe notificação no aplicativo Nuvende
3. Cliente visualiza detalhes da solicitação
4. Cliente decide aprovar ou rejeitar

3. Processamento da Decisão

Se Aprovado

O sistema executa os seguintes passos:

1. Criação de Credenciais: Gera client_id e client_secret específicos
2. Configuração de Acessos: Configura as permissões da conta e dos escopos aprovados
3. Webhook de Aprovação: Envia dados de integração para o parceiro

Se Rejeitado

1. Webhook de Rejeição: Notifica o parceiro sobre a rejeição
2. Registro da Decisão: Armazena a decisão para auditoria

Validações e Regras

Regras de Negócio

• Documento Único: Não é possível ter múltiplas solicitações pendentes para o mesmo documento
• Escopos Válidos: Escopos solicitados devem ser subconjunto dos escopos da aplicação
• Aplicação Ativa: Aplicação deve estar aprovada e ativa
• Webhook Válido: URL de webhook deve ser HTTPS e acessível

Validações Técnicas

• Formato de Documento: CPF (11 dígitos) ou CNPJ (14 dígitos)
• E-mail Válido: Formato de e-mail correto
• Telefone: Formato brasileiro válido
• Escopos: Lista não vazia de escopos válidos

Exemplo Completo

// Criar solicitação de autorização
const requestAuthorization = async (token, clientData) => {
  try {
    const request = await createAuthorizationRequest(token, {
      applicationId: 'abnks92-cb57-4ee3-a997-655fb5d0ea45',
      clientName: clientData.name,
      clientDocument: clientData.document,
      clientEmail: clientData.email,
      clientPhone: clientData.phone,
      scopes: ['cob.read', 'cob.write'],
      webhookUrl: 'https://meusite.com/webhook',
      metadata: ['Solicitação via app', 'Cliente premium']
    });

    console.log('Solicitação criada:', request.id);
    return request;
  } catch (error) {
    console.error('Erro ao criar solicitação:', error);
    throw error;
  }
};

// Listar solicitações
const listRequests = async (token) => {
  const response = await fetch('https://api-h.nuvende.com.br/api/v2/partners/requests', {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });

  return response.json();
};

// Uso
const requests = await listRequests(accessToken);
console.log('Solicitações:', requests.data);

Próximos Passos

Após criar uma solicitação:

1. Configurar webhook para receber notificações
2. Aguardar decisão do cliente
3. Processar resposta via webhook
4. Implementar integração com credenciais recebidas