Controle de Acesso & Onboarding

Esta seção descreve os endpoints do ecossistema de acesso do portal FastGivr, que lidam com o onboarding de novos clientes (registro), autenticação de usuários (Sanctum/JWT), verificação de contas e gestão de chaves/tokens de API.

• Base URL: /api/... (sem prefixo geral de grupo, exceto /auth e /manager para fins de organização).
• Autenticação: Rotas de /auth/login e /register são públicas. Subrotas sob auth e manager exigem cabeçalho Authorization: Bearer {token}.

---

🚀 1. Onboarding e Registro de Contas

Estes endpoints realizam o fluxo de auto-cadastro e upload dos documentos iniciais de empresas ou indivíduos.

• POST /api/register: Registra uma conta básica na plataforma.
• POST /api/register-full: Registra uma conta master completa contendo informações corporativas adicionais.
• GET /api/register/status: Consulta o status da análise de cadastro da conta atual (Pendente, Aprovado, Rejeitado).
• POST /api/register/email: Dispara o e-mail de boas-vindas e confirmação inicial de onboarding.
• POST /api/register/images: Envia os documentos de identificação (CNH, RG, Contrato Social) para o armazenamento em nuvem associado à aprovação da conta.

---

🔒 2. Autenticação e Gestão de Sessão (/auth)

Login do Usuário no Portal (POST /api/auth/login)

Realiza a autenticação de sub-usuários e integradores.

• Payload JSON:

  {
    "email": "joao@empresa.com",
    "password": "minhasenhasecreta"
  }

• Retorno (200 OK) - Raw JSON:

  {
    "token": "34|sanctumPlainToken...",
    "session_duration": 24,
    "expires_at": "2026-05-19 12:00:00",
    "app_id": 5
  }

Obtenção de Token JWT da API (POST /api/access/account/get-token)

Utilizado por integradores de back-end com a Chave Secreta ativa (API token).

• Payload JSON:

  {
    "email": "integrador@empresa.com",
    "token": "sec_prod_xyz123"
  }

• Retorno (200 OK) - ApiResponseClass Wrapper:

  {
    "code": 200,
    "success": true,
    "data": {
      "token": "35|sanctumPlainToken...",
      "token_type": "Bearer",
      "expires_at": "2026-05-18T20:27:57+00:00",
      "permissions": [
        {
          "id": 1,
          "name": "charges.create",
          "guard_name": "api"
        },
        {
          "id": 2,
          "name": "withdrawals.create",
          "guard_name": "api"
        }
      ]
    },
    "message": "Autenticado com sucesso"
  }

Detalhes do Perfil e Permissões (GET /api/auth/me)

Retorna as informações completas da conta ativa selecionada, dados do usuário e permissões da role atual.

• Retorno (200 OK) - Raw JSON:

  {
    "account": {
      "id": 5,
      "name": "Minha Empresa LTDA",
      "email": "financeiro@empresa.com",
      "document": "12345678000109",
      "agency": "1234",
      "account": "567890",
      "status": 1,
      "bank_id": 1
    },
    "user": {
      "id": 10,
      "name": "João da Silva",
      "email": "joao@empresa.com",
      "phone": "11999999999",
      "document": "12345678909",
      "status": 1
    },
    "permissions": [
      {
        "id": 1,
        "name": "charges.create",
        "slug": "charges-create"
      }
    ],
    "role": {
      "id": 2,
      "name": "Financeiro",
      "guard_name": "api"
    },
    "accounts": [
      {
        "account": {
          "id": 5,
          "name": "Minha Empresa LTDA",
          "email": "financeiro@empresa.com",
          "document": "12345678000109",
          "agency": "1234",
          "account": "567890",
          "status": 1,
          "bank_id": 1
        },
        "role": {
          "id": 2,
          "name": "Financeiro",
          "guard_name": "api"
        }
      }
    ]
  }

Renovar Sessão (PUT /api/auth/refresh)

• Retorno (200 OK) - Raw JSON:

  {
    "token": "36|sanctumPlainToken...",
    "session_duration": 24,
    "expires_at": "2026-05-19 12:00:00",
    "app_id": 10
  }

Atualizar Perfil / Senha (PUT /api/auth/edit)

• Payload JSON:

  {
    "name": "João Silva Alterado",
    "current_password": "minhasenhasecreta",
    "new_password": "novasenhasecreta"
  }

• Retorno (200 OK) - ApiResponseClass Wrapper:

  {
    "code": 200,
    "success": true,
    "user": {
      "id": 10,
      "name": "João Silva Alterado",
      "email": "joao@empresa.com",
      "phone": "11999999999",
      "document": "12345678909",
      "status": 1
    },
    "message": "Usuário atualizado com sucesso"
  }

Encerrar Sessão (POST /api/auth/logout)

• Retorno (200 OK) - Raw JSON:

  {
    "message": "Successfully logged out"
  }

---

📧 3. Verificação de Segurança (E-mail & PIN)

Enviar Código de Verificação OTP (POST /api/auth/send-verification-code)

Dispara o e-mail contendo o código OTP de 6 dígitos.

• Payload JSON:

  {
    "email": "joao@empresa.com"
  }

• Retorno (200 OK) - ApiResponseClass Wrapper:

  {
    "code": 200,
    "success": true,
    "data": null,
    "message": "Código de verificação enviado com sucesso"
  }

Validar Código de E-mail (POST /api/auth/verify-email)

• Payload JSON:

  {
    "email": "joao@empresa.com",
    "verification_code": "123456"
  }

• Retorno (200 OK) - Raw JSON:

  {
    "message": "E-mail verificado com sucesso!"
  }

Cadastrar PIN Financeiro de Saque (POST /api/account/pin)

• Payload JSON:

  {
    "pin": "1234"
  }

• Retorno (200 OK):

  {
    "message": "PIN cadastrado com sucesso!"
  }