Gerenciamento de Aplicações

As aplicações são o núcleo da integração entre parceiros e clientes da Nuvende. Cada aplicação representa um produto ou serviço específico que o parceiro oferece e define quais permissões serão solicitadas aos clientes.

Visão Geral

Uma aplicação de parceiro é caracterizada por:

• Identidade: Nome, descrição e categoria da aplicação
• Escopos: Permissões específicas que serão solicitadas aos clientes
• Credenciais: client_id e client_secret únicos (gerados após aprovação)
• Webhook: URL para receber notificações de autorização
• Status: Estado atual da aplicação no processo de homologação

Fluxo de Criação

1. Cadastro: Parceiro cria a aplicação com escopos necessários
2. Homologação: Equipe Nuvende analisa e aprova a aplicação
3. Credenciais: client_id e client_secret são gerados
4. Ativação: Aplicação fica disponível para solicitações de autorização

Endpoints Disponíveis

Listar Aplicações

GET /api/v2/partners/application

Lista todas as aplicações cadastradas pelo parceiro autenticado.

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

Resposta

{
  "data": [
    {
      "id": "abnks92-cb57-4ee3-a997-655fb5d0ea45",
      "partner": {
        "id": "981239kd-98d9-45d3-a1e0-eb24db30d22e",
        "name": "Nome do Parceiro",
        "contact_email": "[email protected]",
        "contact_phone": "11999999999",
        "status": "active",
        "scopes": [
          "cob.read",
          "cob.write",
          "pix.read",
          "pix.write"
        ]
      },
      "name": "Minha Aplicação",
      "description": "Descrição detalhada da aplicação",
      "briefing": "Resumo da aplicação",
      "category": "Fintech",
      "scopes": [
        "cob.read",
        "cob.write"
      ],
      "client_id": "ffcfb2ed-d669-4e33-9c4d-fa87dd4c226e",
      "client_secret": "nFNTATLHFp1hGAPZNU0JwJAPY3fQQZVW",
      "status": "active",
      "created_at": "2025-01-15T14:25:57-03:00",
      "updated_at": "2025-01-15T14:25:57-03:00"
    }
  ],
  "links": {
    "first": "https://api-h.nuvende.com.br/api/v2/partners/application?page=1",
    "last": "https://api-h.nuvende.com.br/api/v2/partners/application?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "per_page": 10,
    "to": 1,
    "total": 1
  }
}

Criar Aplicação

POST /api/v2/partners/application

Cria uma nova aplicação vinculada ao parceiro autenticado.

curl --location 'https://api-h.nuvende.com.br/api/v2/partners/application' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "name": "Nome da Aplicação",
  "description": "Descrição detalhada da aplicação",
  "briefing": "Resumo da aplicação",
  "category": "Fintech",
  "scopes": [
    "cob.read",
    "cob.write"
  ]
}'

Parâmetros

Escopos Disponíveis

Atualizar Aplicação

PATCH /api/v2/partners/application/{application_id}

Atualiza os dados de uma aplicação específica.

curl --location --request PATCH 'https://api-h.nuvende.com.br/api/v2/partners/application/{application_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data '{
  "name": "Novo Nome da Aplicação",
  "description": "Nova descrição",
  "briefing": "Novo briefing",
  "category": "Nova Categoria",
  "scopes": [
    "cob.read",
    "cob.write",
    "pix.read"
  ]
}'

Status das Aplicações

Processo de Homologação

Critérios de Aprovação

1. Escopos Necessários: Apenas escopos realmente utilizados
2. Documentação: Descrição clara do uso da aplicação
3. Segurança: Implementação adequada de segurança
4. Testes: Demonstração funcional em ambiente de teste

Documentação Necessária

• Descrição detalhada da aplicação
• Casos de uso específicos
• Justificativa para cada escopo solicitado
• Evidências de implementação técnica
• Política de privacidade e termos de uso

Boas Práticas

Organização de Aplicações

• Separação por Produto: Uma aplicação por produto/serviço
• Escopos Mínimos: Solicite apenas permissões necessárias
• Documentação Clara: Descreva o propósito de cada aplicação
• Categorização: Use categorias consistentes

Segurança

• Credenciais Seguras: Mantenha client_secret em segurança
• Rotação: Renove credenciais periodicamente
• Monitoramento: Acompanhe uso e acessos
• Logs: Mantenha logs de operações importantes

Exemplo Completo

// Criar nova aplicação
const createApplication = async (token, applicationData) => {
  const response = await fetch('https://api-h.nuvende.com.br/api/v2/partners/application', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      name: applicationData.name,
      description: applicationData.description,
      briefing: applicationData.briefing,
      category: applicationData.category,
      scopes: applicationData.scopes
    })
  });

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

  return response.json();
};

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

  return response.json();
};

// Uso
const applications = await listApplications(accessToken);
console.log('Aplicações:', applications.data);

Próximos Passos

Após criar e aprovar uma aplicação:

1. Criar solicitações de autorização
2. Configurar webhooks
3. Implementar integração com os escopos aprovados