Documentação da API de Configurações da Conta (Account)

Gerenciamento completo dos dados cadastrais, configurações bancárias, SMTP, endereços e regras de notificação da conta ativa.

Base URL: /access/account e /access/accounts

---

🚀 Endpoints

Método	Rota	Descrição
GET	/access/accounts	Lista todas as contas vinculadas ao usuário.
GET	/access/account	Detalhes da conta ativa na sessão.
PUT	/access/account	Atualiza os dados da conta ativa (Requer PIN).
POST	/access/account/pin	Define o PIN inicial de segurança (Apenas se não definido).
POST	/access/account/get-token	Gera um token Bearer para integração Server-to-Server.

---

🔑 Autenticação de API (POST /access/account/get-token)

Este endpoint é utilizado para obter um token de acesso temporário para integrações via API (Server-to-Server).

Parâmetros (Payload)

• email: E-mail do usuário vinculado à conta.
• token: Token fixo da conta (encontrado nas configurações da conta).

Resposta (200 OK)

Retorna um token Bearer com validade de 10 minutos.

{
  "success": true,
  "data": {
    "token": "1|abc123def...",
    "token_type": "Bearer",
    "expires_at": "2026-05-15T14:10:00+00:00",
    "permissions": [
      { "id": 1, "name": "charges.create", "guard_name": "web" }
    ]
  },
  "message": "Autenticado com sucesso"
}

---

🛠️ Atualização de Conta (PUT /access/account)

Para atualizar qualquer campo, é obrigatório enviar o campo pin (6 dígitos) para autenticação da transação. O sistema valida o PIN usando o algoritmo Bcrypt.

Parâmetros do Request (Payload)

Campo	Tipo	Obrigatório	Descrição
name	string	Não	Nome da conta/empresa.
email	string	Não	E-mail de contato principal.
document	string	Não	CPF ou CNPJ (apenas números).
webhook_url	string	Não	URL para recebimento de webhooks ativos.
pin	string	Sim	PIN de 6 dígitos atual para autorização.
new_pin	string	Não	Novo PIN de 6 dígitos (caso queira alterar).
logo	file/string	Não	Arquivo de imagem ou string Base64 (data:image/...).
address	object	Não	Objeto contendo o endereço (street, number, city, state, zip_code).
smtp	object	Não	Configurações de servidor de e-mail próprio.
notification_rules	object	Não	Regras para disparos automáticos de mensagens.
boleto_configs	object	Não	Taxas e descontos específicos para Boletos.

---

📬 Regras de Notificação (notification_rules)

As notificações podem ser enviadas por Email, WhatsApp e SMS. Você pode selecionar os canais desejados para cada evento.

Regra	Subcampos	Descrição
on_creation	enabled, message, channels	Dispara ao gerar uma nova cobrança.
on_payment	enabled, message, channels	Dispara ao confirmar o pagamento.
on_due	enabled, message, channels	Dispara no dia exato do vencimento.
on_update	enabled, message, channels	Dispara quando os dados da cobrança são alterados.
on_delete	enabled, message, channels	Dispara quando a cobrança é excluída/cancelada.
before_due	enabled, message, days, channels	Lembrete enviado X dias antes do vencimento.
after_due	enabled, message, days, channels	Cobrança enviada X dias após o vencimento (se pendente).

Canais Disponíveis: email, whatsapp, sms. Placeholders: Use :name, :value, :link, :code e :date para personalizar as mensagens.

---

📦 Estrutura do Resource (Resposta)

A resposta retorna o objeto da conta com o campo has_pin para controle de interface.

{
  "success": true,
  "data": {
    "account": {
      "id": 123,
      "code_account": "ACC-456",
      "name": "Minha Empresa LTDA",
      "email": "financeiro@empresa.com",
      "document": "12345678000190",
      "has_pin": true,
      "webhook_url": "https://meusite.com/webhook",
      "path_logo": "https://s3.aws.com/logos/meu-logo.png",
      "address": {
        "street": "Avenida Paulista",
        "city": "São Paulo",
        "state": "SP",
        "zip_code": "01311-000"
      },
      "notification_rules": {
        "on_creation": { 
            "enabled": true, 
            "channels": ["email", "whatsapp"], 
            "message": "Olá :name, sua fatura :code foi gerada!" 
        }
      },
      "created_at": {
        "formatted": "01/03/2026 18:00:00",
        "human": "há 1 hora"
      }
    }
  }
}

---

🔒 Segurança (PIN)

O PIN de 6 dígitos protege operações críticas.

• Definição: POST /access/account/pin. Retorna "Pin definido com sucesso."
• Alteração: PUT /access/account enviando o pin atual e o new_pin.
• Validação: Se a conta não possuir PIN configurado, o sistema negará qualquer tentativa de atualização via PUT que exija autorização.

---

👨‍💻 Referência Técnica (Backend)

Resource: AccountResource (app/Http/Resources/AccountResource.php)

Gerencia a transformação dos dados, incluindo a verificação has_pin => $this->pin !== null.

Request: UpdateAccountRequest (app/Http/Requests/UpdateAccountRequest.php)

Realiza a validação dos campos e autorização via Hash::check. Foi corrigido para tratar o pin como string (corrigindo erro de algoritmo Bcrypt).

Observer: ChargeObserver (app/Observers/ChargeObserver.php)

Escuta os eventos do modelo Charge e dispara as notificações baseadas nas notification_rules configuradas na conta vinculada.