🏦 Gestão de Contas Bancárias (Backoffice)
Endpoints para monitoramento de contas bancárias e saldos.
Listagem e Dashboard
Para detalhes sobre a listagem de contas, filtros e metadados de resumo para o dashboard, consulte o documento específico: 👉 Listagem de Contas e Orientações Front-end
Atualizar Conta
Atualiza parcialmente (PATCH) ou totalmente (PUT) os dados de uma conta bancária, taxas, limites, endereço e configurações complementares.
Endpoint: PUT/PATCH /backoffice/accounts/\{id\}
Parâmetros (JSON)
| Campo | Tipo | Descrição | Obrigatório/Opcional |
|---|---|---|---|
name | string | Nome da conta. | Opcional |
email | string | Endereço de e-mail (deve ser único). | Opcional |
document | string | CPF ou CNPJ (validado pelo formato e dígito). | Opcional |
status | string | Status da conta (ACTIVE, INACTIVE, SUSPENDED, SOFT_DELETED, DELETED). | Opcional |
bank_id | integer | ID do banco associado. | Opcional |
agency | string | Agência bancária. | Opcional |
account | string | Número da conta bancária. | Opcional |
webhook_url | string (url) | URL para recebimento de webhooks. | Opcional |
webhook_events | array | Lista de eventos habilitados para webhook (ex: ['charge.paid', 'pix.received']). | Opcional |
tax_boleto | numeric | Taxa padrão de boleto. | Opcional |
tax_pix_out | numeric | Taxa de transferência Pix emitida. | Opcional |
tax_pix_in | numeric | Taxa de recebimento Pix. | Opcional |
tax_boleto_in | numeric | Taxa de recebimento Boleto. | Opcional |
tax_fee | numeric | Tarifa de manutenção da conta. | Opcional |
tax_bolepix | numeric | Taxa de cobrança híbrida Bolepix. | Opcional |
min_pix_in | numeric | Valor mínimo para recebimento via Pix. | Opcional |
max_pix_out | numeric | Limite máximo diário de emissão Pix. | Opcional |
min_boleto_in | numeric | Valor mínimo para emissão de boleto. | Opcional |
max_boleto_in | numeric | Valor máximo para emissão de boleto. | Opcional |
address | object | Dados de endereço da conta. | Opcional |
address.street | string | Logradouro (obrigatório se address for enviado). | Condicional |
address.number | string | Número. | Opcional |
address.zip_code | string | CEP (pode-se usar zip ou zip_code). | Opcional |
address.city | string | Cidade (obrigatório se address for enviado). | Condicional |
address.state | string | Estado (obrigatório se address for enviado). | Condicional |
address.country | string | País (Padrão: Brasil). | Opcional |
smtp | object | Dados do servidor SMTP da conta. | Opcional |
smtp.host | string | Endereço do host do servidor SMTP. | Opcional |
smtp.port | integer | Porta de conexão SMTP. | Opcional |
smtp.user | string | Usuário do SMTP. | Opcional |
smtp.password | string | Senha do SMTP. | Opcional |
smtp.encryption | string | Tipo de criptografia (tls ou ssl). | Opcional |
smtp.from_name | string | Nome do remetente das mensagens. | Opcional |
smtp.from_address | string | E-mail do remetente. | Opcional |
notification_rules | object | Regras de envio de notificações e gatilhos. | Opcional |
boleto_configs | object | Configurações específicas de emissão de boletos. | Opcional |
Payload de Exemplo (JSON)
json
{
"name": "Nova Razão Social",
"document": "83884813000109",
"status": "ACTIVE",
"tax_pix_in": 1.50,
"tax_pix_out": 2.00,
"address": {
"street": "Avenida Paulista",
"number": "1000",
"zip_code": "01311-000",
"city": "São Paulo",
"state": "SP"
},
"smtp": {
"host": "smtp.mailtrap.io",
"port": 2525,
"user": "smtpuser",
"encryption": "tls"
}
}Resposta de Sucesso (200 OK)
json
{
"code": 200,
"success": true,
"account": {
"id": 1,
"name": "Nova Razão Social",
"email": "contato@empresa.com",
"document": "83884813000109",
"status": {
"code": "ACTIVE",
"title": "Ativo",
"color": "success"
},
"bank": {
"id": 2,
"title": "Banco do Brasil"
},
"balance": {
"current": 1500.50,
"total_balance": 150050,
"formatted_balance": "R$ 1.500,50"
},
"agency": "0001",
"account": "12345-6",
"address": {
"id": 5,
"street": "Avenida Paulista",
"number": "1000",
"zip": "01311-000",
"city": "São Paulo",
"state": "SP",
"country": "Brasil"
},
"configurations": {
"tax_pix_in": "1.50",
"tax_pix_out": "2.00",
"tax_boleto_in": "1.00",
"min_pix_in": "1.00",
"max_pix_out": "5000.00",
"webhook_url": "https://webhook.site/abc"
},
"created_at": "2024-04-20 12:00:00",
"updated_at": "2026-05-21 09:10:00"
},
"message": "Account updated successfully"
}Respostas de Erro
Erro de Validação (422 Unprocessable Entity)
json
{
"code": 422,
"message": "The document field must be a valid CPF or CNPJ.",
"success": false,
"data": {
"document": [
"O documento fornecido não é um CPF ou CNPJ válido."
]
}
}Conta Não Encontrada (404 Not Found)
json
{
"code": 404,
"message": "Nenhum resultado encontrado para o modelo especificado.",
"success": false,
"data": "No query results for model [App\\Models\\Account] 99"
}Detalhar Conta
Retorna dados completos da conta, incluindo endereço, usuários vinculados e estatísticas de movimentação.
Endpoint: GET /backoffice/accounts/\{id\}
Resposta (Estrutura)
json
{
"data": {
"id": 1,
"name": "Nome da Conta",
"users": [
{
"id": 10,
"name": "João Silva",
"roles": { "id": 1, "name": "Admin" }
}
],
"balance": {
"current": 1500.50,
"total_balance": 150050,
"formatted_balance": "R$ 1.500,50"
}
},
"stats": {
"transactions": {
"total_count": 500
},
"charges": {
"total_count": 120,
"total_value": 45000.00,
"total_paid": 38000.00,
"by_status": [
{
"status": "PAGO",
"count": 80,
"value": 38000.00
},
{
"status": "PENDENTE",
"count": 40,
"value": 7000.00
}
]
}
}
}Consultar Saldo
Consulta o saldo atual consolidado de uma conta.
Endpoint: GET /backoffice/accounts/\{id\}/balance
Resposta
json
{
"account_id": 1,
"name": "Empresa Exemplo",
"balance": 1500.50,
"total_balance": 150050,
"formatted_balance": "R$ 1.500,50"
}Relatório de Contas
Gera um relatório consolidado de todas as contas e seus saldos totais.
Endpoint: GET /backoffice/reports/accounts