CLP SISTEMASTermos e privacidade

Integre ao login do seu sistema

API REST autenticada por aplicação. Cadastre a empresa, confirme o pagamento e crie uma aplicação no painel. Guarde as duas chaves no backend, nunca no navegador do usuário final.

1. Avaliar um acesso

Use a chave de avaliação em Authorization: Bearer SUA_CHAVE, JSON e um Idempotency-Key exclusivo por evento. A base é a mesma origem deste painel.

POST /v1/access/evaluations
Authorization: Bearer SUA_CHAVE
Idempotency-Key: evento_00000001
Content-Type: application/json

{
  "subject_id": "usuario_0001",
  "session_id": "sessao_00001",
  "device_id": "dispositivo_0001",
  "action": "view_dashboard",
  "primary_authenticated": true,
  "authenticated_at": "2026-09-29T10:00:00Z",
  "authentication_method": "passkey"
}

O horário acima é ilustrativo: envie o instante real da autenticação verificada pelo seu servidor. Identificadores e idempotência: 8–128 caracteres ASCII, letras minúsculas (a–z), números, traço ou sublinhado. Gere pseudônimos canônicos, como hashes hexadecimais minúsculos; não transforme IDs distintos do seu sistema em um mesmo pseudônimo. Não envie dados pessoais diretos ou segredos. O identificador do dispositivo deve ser vinculado à sessão pelo backend, não aceito cegamente do navegador.

Ações: view_dashboard, view_account, login, failed_login, change_bank_account, account_recovery, enroll_factor, payment. Métodos: password, email_otp, sms_otp, totp, passkey. Para falha de login, use primary_authenticated: false, com horário e método nulos. O método informado neste evento é uma declaração do seu backend: a avaliação de risco não verifica o desafio do seu provedor. Para verificação TOTP pela CLP, use a integração MFA descrita abaixo.

2. Interpretar a resposta

recommended_action: continue_existing_session, require_step_up, review ou deny. A resposta inclui decision_id, mode, enforceable, reason_codes, signal_quality, policy_version, evaluated_at, expires_at, app_id, subject_id, session_id, device_id, action, allowed_methods.

Observação (shadow) nunca dispensa o desafio atual. Ative a política pelo painel depois de testar sua integração. Em modo ativo, a continuidade exige dispositivo confiável e autenticação recente com passkey ou TOTP; isso não equivale a uma probabilidade de fraude. TOTP não oferece a mesma resistência a phishing que passkeys. Ações sensíveis sempre exigem confirmação adicional. Cinco falhas em 15 minutos resultam em recusa recomendada.

3. Consumir uma decisão ativa

Antes de aplicá-la, envie o mesmo contexto e um identificador exclusivo da operação. Uma decisão não pode ser usada em outra operação. O ERP deve executar a operação também de forma idempotente usando este identificador.

POST /v1/access/evaluations/DECISION_ID/consume
Authorization: Bearer SUA_CHAVE
Content-Type: application/json

{
  "subject_id": "usuario_0001",
  "session_id": "sessao_00001",
  "device_id": "dispositivo_0001",
  "action": "view_dashboard",
  "operation_id": "operacao_00000001"
}

Consumo aceita apenas decisão ativa, válida e da versão atual. Repetir o mesmo consumo é idempotente. Mudar contexto, operação ou política, revogar o dispositivo ou ultrapassar a validade pode gerar 409. A validade máxima é 60 segundos, limitada pelo prazo da autenticação. O campo enforceable não significa “acesso autorizado”: aplique a recomendação retornada.

4. Dispositivos e feedback

Após verificação forte recente no seu backend, use a chave administrativa para POST /v1/admin/devices com subject_id, device_id, verification_method, verified_at. São aceitos passkey/TOTP verificados nos últimos cinco minutos. A confiança dura 30 dias. Revogue por DELETE /v1/admin/devices/{subject}/{device}. A chave de avaliação não pode criar confiança.

Envie POST /v1/access/evaluations/{id}/feedback com {"outcome":"challenge_passed"}. Outros resultados: challenge_failed, confirmed_compromise, confirmed_legitimate, unknown. Resultados confirmados exigem chave administrativa. O primeiro feedback é imutável; repetição igual é aceita. Feedback nunca cria confiança. Desafio aprovado não comprova legitimidade.

5. Consultas, limites e falhas

Avaliação nova: 201. Mesma idempotência e mesmo corpo: 200 com a decisão original, sem renovar validade ou consumir de novo. Corpo diferente: 409. Após 30 dias, replay retorna 410; identificadores de idempotência ficam protegidos por até 90 dias. Não reutilize chaves antigas.

20.000 avaliações por mês de calendário UTC, compartilhadas entre até três aplicações. 120 requisições/minuto por aplicação. 16 KB por corpo. Campos desconhecidos são rejeitados. 400: entrada inválida; 401: chave ausente, inválida, revogada, vencida ou conta sem vigência; 403: permissão; 404: recurso não encontrado neste escopo; 409: conflito; 413: corpo grande; 429: limite; 5xx: indisponibilidade. Nunca converta erro, timeout ou resultado vencido em baixo risco. Preserve a autenticação habitual e recuse ações sensíveis se o fallback não puder ser aplicado.

Na rotação pelo painel, a chave anterior é revogada imediatamente. Cada chave vale até um ano. A desativação da aplicação revoga ambas as chaves. Não envie chaves em URLs, logs, telas ou chamados.

6. Relatórios com IA

Solicitados no painel, com quatro requisições aceitas/mês por empresa e mínimo de dez avaliações. Apenas contagens de recomendações e resultados seguem ao Gemini. A análise é assíncrona, pode falhar e não altera a política. Consulte novamente o painel para acompanhar. Não inclua dados de usuários em nomes de aplicações ou chamados.

7. Operação

Confirme autenticação do seu backend, isolamento por aplicação, requisições concorrentes, fallback, revogação e reversão de política antes de ativar. O modo ativo é uma política de regras, não um modelo estatístico antifraude calibrado. Não há SLA individual nesta oferta. Para suporte: contato@clpsistemas.com.br.

8. MFA com aplicativo autenticador

Acrescente uma confirmação TOTP ao login do usuário do seu ERP. A CLP oferece a etapa hospedada de cadastro e confirmação; seu backend continua responsável pela autenticação primária, pela autorização e pela conclusão da operação. Esta jornada é diferente do acesso administrativo ao painel CLP.

  1. Seu backend autentica a pessoa e avalia o acesso.
  2. Cria uma sessão MFA com os identificadores e horários verificados no servidor.
  3. A pessoa abre a etapa hospedada e informa o código do aplicativo.
  4. Seu backend consulta e consome a confirmação; só então aplica sua autorização e conclui a operação de forma idempotente.

Disponibilidade: o módulo precisa estar habilitado para o serviço e a conta precisa manter acesso à API. Consulte GET /public/mfa/capabilities para conferir enabled e os recursos disponíveis. Se retornar mfa_unavailable, mantenha a exigência de segundo fator e não conclua a operação protegida. Não converta indisponibilidade, recuperação ou revogação em aprovação.

Criar a sessão no backend

POST /v1/mfa/sessions
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND
Content-Type: application/json

{
  "kind": "verify",
  "subject_id": "usuario_0001",
  "session_id": "sessao_0001",
  "device_id": "dispositivo_0001",
  "action": "payment",
  "operation_id": "operacao_0001",
  "decision_id": "ID_DA_DECISAO_DE_RISCO",
  "primary_authenticated_at": "INSTANTE_UTC_REAL",
  "primary_expires_at": "VENCIMENTO_UTC_REAL"
}

Use a chave de avaliação ou administrativa da mesma aplicação. Os horários são marcadores: envie ISO 8601 UTC real. A CLP confia na declaração de autenticação primária do backend integrador; nunca a preencha diretamente com dados do navegador. A resposta contém session_id da sessão MFA, hosted_url e expires_at. Guarde no backend a associação com a sessão primária. O fator é isolado por empresa, aplicação e usuário.

Abra a URL hospedada sem registrá-la em logs ou analytics. O fragmento contém um token temporário de uso restrito. A página o remove da URL e não recebe sua chave de API. O prazo de verify também respeita o vencimento da decisão de risco, que pode ser de até 60 segundos; as demais jornadas têm prazo máximo de cinco minutos, limitado pela sessão primária.

Cadastro, troca e recuperação

JornadaO que a pessoa fazResultado
enrollAdiciona QR/chave manual ao autenticador e confirma um código.Fator cadastrado e dez códigos de recuperação, exibidos uma vez.
verifyConfirma um código do autenticador cadastrado.Confirmação para consulta e consumo no backend.
replaceConfirma o autenticador atual, cadastra e confirma o novo.Substituição; o fator anterior permanece até a confirmação.
recoverUsa um código de recuperação e cadastra um novo autenticador.Recadastro; não autoriza uma operação de negócio.
revokeConfirma o autenticador atual.Revogação do fator, sem dispensar as exigências do ERP.

Cada código de recuperação é de uso único. A pessoa pode copiar ou salvar o lote antes de concluir. Consultas posteriores não exibem os códigos novamente. Cancelar ou deixar vencer uma troca pendente preserva o fator anterior; um código de recuperação já consumido não volta a ficar disponível.

Conferir o resultado

GET /v1/mfa/sessions/ID_DA_SESSAO_MFA
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND

POST /v1/mfa/sessions/ID_DA_SESSAO_MFA/consume
Authorization: Bearer CHAVE_DA_APLICACAO_NO_BACKEND
Content-Type: application/json

{
  "subject_id": "usuario_0001",
  "session_id": "sessao_0001",
  "device_id": "dispositivo_0001",
  "action": "payment",
  "operation_id": "operacao_0001",
  "decision_id": "ID_DA_DECISAO_DE_RISCO"
}

A consulta retorna kind, state, expires_at, proof_ready e o identificador da sessão MFA. Somente verify permite consumir uma confirmação. O consumo confere o contexto original e retorna verified, method, factor_version, verified_at, context, policy_version. É de uso único e não produz uma recomendação de permitir acesso. Seu backend deve manter sua autorização e idempotência; a tela de sucesso, por si só, não libera uma operação. A integração deve exigir decisão aplicável em modo active, com enforceable: true, contexto e prazo válidos. deny mantém a recusa; shadow não autoriza a operação mesmo com TOTP confirmado. Estes endpoints não ativam MFA automaticamente nas integrações legadas.

Estados da página: awaiting_code, awaiting_confirmation, completed, cancelled, expired, invalidated. completed também ocorre em cadastro e recuperação, por isso não o trate como prova de uma operação. Se uma resposta se perder, consulte o estado; não reenvie códigos ou operações automaticamente.

Até cinco tentativas por sessão, além do limite persistido por usuário/aplicação. invalid_code permite nova tentativa dentro do orçamento; mfa_rate_limited exige espera. session_expired, session_invalidated, session_consumed encerram aquela jornada. mfa_storage_unavailable e mfa_key_unavailable mantêm a operação sem confirmação. A revogação da chave que criou a sessão invalida o fluxo hospedado.

Proteções operacionais padrão por aplicação: 5.000 registros de fator, incluindo revogados; 1.000 sessões não expiradas; 50.000 marcadores de operações consumidas e 100.000 eventos de auditoria MFA, ambos com retenção de 30 dias. São limites técnicos configuráveis, sem alteração do plano comercial. Capacidade esgotada retorna mfa_capacity_reached (503) e não libera a operação.

A limpeza é tentada a cada cinco minutos e na criação de sessão: remove sessões e segredos temporários expirados, contadores de limite vencidos, consumos e auditoria MFA com mais de 30 dias. Preserva o contador antirreplay do fator. O marcador de consumo impede nova confirmação da mesma operação por 30 dias; seu ERP deve manter sua própria idempotência. Uma confirmação verificada vence para consumo em até 30 segundos, também limitada pela sessão e decisão.

A origem hospedada exige HTTPS em produção. HTTP loopback é permitido somente nos ambientes Testing e Development. Erros de infraestrutura MFA exigem recusar a operação protegida.

QR, chave de configuração e códigos pertencem somente a esta jornada de segurança. Não os envie como eventos de risco, feedback, relatórios de IA ou chamados. TOTP não é resistente a phishing e não assina os detalhes da operação; o vínculo é conferido no backend. Este módulo não oferece SMS, passkeys, diretório de usuários ou SSO.