voltcerto/docs/API.md

API da aplicacao

Arquitetura

Web e API usam os mesmos servicos em app/Services, com as mesmas regras de negocio e acesso aos dados. A web mantem as vistas Blade e os redirecionamentos. A API devolve JSON, exceto a exportacao Excel e o diagnostico HTML phpinfo. Os controllers nao fazem chamadas HTTP a propria aplicacao. APP_API_URL ou app.api_url deixam de ser necessarios para o login e a sessao web.

O bootstrap Laravel regista routes/api.php com o prefixo /api.

Autenticacao

POST /api/login recebe email e password e devolve token e user. Os tokens Sanctum expiram apos 20 minutos. Use estes cabecalhos nos pedidos:

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

POST /api/refresh prolonga um token ainda valido por 20 minutos. POST /api/logout revoga o token atual. A recuperacao de senha revoga todos os tokens do utilizador. Contas com can_login=false nao podem autenticar-se nem usar tokens existentes. O login web usa o mesmo servico, regenera a sessao e valida/renova o token localmente em cada pedido autenticado.

Login e verificacao de PIN permitem 10 tentativas por minuto; pedidos publicos de recuperacao de senha e envio de email de teste permitem 5 por minuto.

Endpoints

Todos os caminhos abaixo sao relativos a /api. CRUD /recurso significa GET /recurso, POST /recurso, GET /recurso/{id}, PUT ou PATCH /recurso/{id} e DELETE /recurso/{id}. As rotas /resources aceitam PUT, nao PATCH.

Operacao	Endpoint	Acesso
Login	POST /login	Publico
Pedir recuperacao de senha	POST /password/email	Publico
Redefinir senha	POST /password/reset	Publico
Sair / renovar / verificar token	POST /logout, POST /refresh, GET /check-token	Autenticado
Utilizador atual e permissoes	GET /me	Autenticado
Dashboard	GET /dashboard	Autenticado
Analises	GET /analytics	Role administracao
Guardar / verificar PIN	POST /user/pin, POST /user/check-pin	Autenticado
Clientes	CRUD /clients	Autenticado
Opcoes de clientes	GET /clients/options?type={client_type_id}	Autenticado
Detalhe e contratos de cliente	GET /clients/{id}/detail	Autenticado
Pesquisa por nome	GET /clients/search/name?term=...	Autenticado
Pesquisa por ID	POST /clients/search/id, corpo {"id":1}	Autenticado
Leads	CRUD /leads	Autenticado
Estados de leads	GET /leads/options	Autenticado
Converter lead	PUT /leads/{id}/convert	Autenticado
Contratos	CRUD /contracts	Autenticado
Opcoes de contratos	GET /contracts/options?client_id=...	Autenticado
Dados de edicao	GET /contracts/{id}/edit	Autenticado
Opcoes / executar renovacao	GET /contracts/{id}/renew, POST /contracts/{id}/renew	Autenticado
Historico	GET /contracts/{id}/history	Autenticado
Ler / editar / eliminar historico	GET, PUT, DELETE /contracts/{id}/history/{historyId}	Autenticado
Eliminar contratos em lote	DELETE /contracts/bulk, corpo {"ids":[1,2]}	Autenticado
Exportar contratos	GET /contracts/export	Permissao view_contract_summary
Utilizadores	CRUD /users	Role admin
Roles para criar utilizador	GET /users/options	Role admin
Enviar recuperacao de senha a utilizador	POST /users/{user}/password-reset	Role admin
Roles e permissoes	GET /admin/access/roles-permissions	Role admin
Atualizar permissoes de role	POST /admin/access/roles/{role}/permissions	Role admin
Utilizadores e roles	GET /admin/access/users	Role admin
Atualizar roles de utilizador	POST /admin/access/users/{user}/roles	Role admin
Recursos auxiliares	CRUD /resources/{resource}	Permissao manage_resources
Informacao do sistema	GET /admin/info	Role admin
Diagnostico PHP (HTML)	GET /admin/phpinfo	Role admin
Executar migrations	POST /admin/runMigrations	Role admin
Email de teste	POST /admin/testEmail, corpo {"email":"destino@example.com"}	Role admin

Recursos permitidos: power_tiers, contract_types, payment_methods, typologies, cui_tiers, suppliers, contract-statuses. Roles e permissoes sao enviadas como listas de nomes nos campos roles e permissions. Os campos de negocio e datas seguem os FormRequests existentes, incluindo o formato d/m/Y nos formularios de contratos. As operacoes de senha recebem email; a redefinicao tambem recebe token, password e password_confirmation.

Respostas e compatibilidade

Criacao: 201; operacao concluida: 200; nao autenticado: 401; acesso negado: 403; registo inexistente: 404; validacao: 422; limite de tentativas: 429. Erros de validacao incluem message e errors. Os erros API sao JSON mesmo sem o cabecalho Accept.

Clientes mantem a listagem antiga {"clients":[...]} quando per_page nao e enviado. Com per_page, devolvem um paginador em clients, com data, current_page, last_page, per_page, total e links. Clientes e contratos limitam per_page ao intervalo 1-100. A listagem paginada de clientes filtra type=client, tal como a web; a listagem antiga conserva o comportamento anterior de devolver os registos ativos. Filtros de nome, NIF, email, tipo e codigo de contrato sao partilhados. Contratos incluem os totais da pagina atual.

IDs de clientes passam a ser incluidos nas respostas. Passwords, hashes de PIN e remember tokens nao sao serializados. Dados financeiros e snapshots de contratos sao omitidos das respostas de negocio sem view_contract_summary. Atualizacoes sem essa permissao preservam os valores financeiros e parcelas. Exportacoes exigem essa permissao, tambem na web.

As antigas operacoes administrativas GET /admin/runMigrations e GET /admin/testEmail passam a POST, exigem a role admin, e o email de destino passa a ser obrigatorio. Nenhuma migration foi executada durante esta refatoracao. Estes endpoints devem ser restritos tambem ao nivel de rede em producao, especialmente phpinfo e a execucao de migrations.

Verificacao

Os testes unitarios de regras ficam em tests/Unit. Os testes HTTP da API ficam em tests/Api, e os fluxos web destinados ao browser ficam em tests/Browser. Ambos usam uma base SQLite em memoria, com o esquema oficial de permissoes do Spatie e tabelas minimas; nao usam nem alteram a base de dados da aplicacao. Os testes Browser verificam a resposta HTTP, vistas, CSRF, redirecionamentos e sessoes Laravel; nao executam JavaScript num Chromium real.

APP_ENV=testing DB_CONNECTION=sqlite DB_DATABASE=:memory: CACHE_STORE=array SESSION_DRIVER=array \
  vendor/bin/phpunit tests/Unit tests/Api tests/Browser

Cada grupo tambem pode ser executado isoladamente com vendor/bin/phpunit --testsuite API ou vendor/bin/phpunit --testsuite Browser. O PHP CLI necessita da extensao pdo_sqlite. Os testes Feature legados que dependem de dados preexistentes nao estao incluidos no comando acima.