Pular para o conteúdo principal
Versão: Guardian v0.5.3

Collect (Servidor para Servidor)

v0.3.0+

Dois caminhos de verificação​

O Guardian SDK oferece duas formas de verificar dispositivos. Escolha de acordo com a sua arquitetura:

verify()collect()
Quem chama a SurtO SDK (a partir do dispositivo)Seu backend (servidor para servidor)
Exigência de JWTObrigatório, um novo para cada chamadaOpcional
Seu backend participaNãoSim
RespostaVerificationResult (permitido/negado)CollectResult (payload criptografado)
Ideal paraIntegração simples, decisões tomadas no frontendDecisões tomadas no backend, lógica personalizada, requisitos de auditoria

Fluxo de verify()​

App → fetch fresh JWT from your backend → SDK.verify(jwt) → Surt backend → risk decision → App

O SDK chama a Surt diretamente e retorna allowed: true/false. Seu app age sobre a decisão imediatamente. Solicite um novo JWT para cada chamada.

Fluxo de collect()​

App → SDK.collect() → encrypted payload → App → Your backend → Surt /evaluate → Your backend → App

O SDK coleta os dados do dispositivo e os criptografa no dispositivo. collect() não envia o payload do dispositivo à Surt. Seu backend envia o payload ao endpoint evaluate da Surt, recebe a avaliação de risco e decide o que retornar ao seu app.

Quando usar collect()​

  • Seu backend precisa dos dados de risco antes de responder ao cliente
  • Você quer combinar o risco do dispositivo com sua própria lógica de negócio no lado do servidor
  • Você precisa de controle total sobre o que o cliente vê

Uso​

1. Coletar no dispositivo​

import { useGuardian } from '@surtai/guardian-rn';

function PaymentScreen() {
const { collect } = useGuardian();

const handlePayment = async () => {
// The JWT is optional for collect(). Pass collect(jwt) to resolve the
// device's public IP into the payload and to apply your organization's
// attestation settings.
const { payload } = await collect();

// Send payload to YOUR backend
const response = await fetch('https://your-api.com/verify-device', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
payload,
amount: 500,
currency: 'USD',
}),
});

const result = await response.json();
// Your backend already made the risk decision
};
}

O JWT é opcional para collect(). Quando você passa um, o SDK faz duas coisas com ele:

  • Chama GET /geolocation/client-ip e adiciona o IP público do dispositivo ao payload.
  • Aplica as configurações de atestação da sua organização: com que frequência um dispositivo atesta e, no Android, seu próprio projeto de Play Integrity. Veja Configuração da atestação de dispositivo.

Sem um JWT, o payload não leva um IP público resolvido e o SDK atesta em toda chamada com as configurações padrão. Solicite um novo JWT para cada transação. Um JWT expira 30 minutos após ser emitido.

2. Chamar a Surt a partir do seu backend​

Seu backend recebe o payload criptografado do app e então chama o endpoint evaluate da Surt:

POST https://api.surt.com/geolocation/transactions/evaluate
Content-Type: application/json
Authorization: Bearer YOUR_SURT_API_KEY
{
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"name": "Jane Doe",
"email": "jane@example.com",
"phone": "+15555550100",
"event_id": "withdrawal-8841",
"payload": {
"type": "encrypted",
"data": "<payload from SDK>"
},
"config": {
"response": {
"address": { "type": "include" }
}
}
}

Campos da requisição​

CampoTipoObrigatórioDescrição
customer_idstringNãoSeu identificador do usuário. Omita-o, ou envie uma string vazia, para uma transação anônima, por exemplo antes do login.
transaction_typestringSimlogin, sign_up, deposit, withdrawal ou uma string personalizada de até 64 caracteres. Veja Tipos de Transação.
transaction_namestringNãoRótulo legível por humanos
namestringNãoO nome do cliente
emailstringNãoO e-mail do cliente. Uma string vazia conta como ausente. Um endereço inválido retorna 400.
phonestringNãoO número de telefone do cliente. Uma string vazia conta como ausente. Um número que não pode ser interpretado retorna 400.
event_idstringNãoSeu ID para este evento, único dentro da sua organização. De 1 a 128 caracteres: letras, dígitos, ., _, : e -. Veja Idempotência.
payload.typestringSimSempre "encrypted"
payload.datastringSimO payload criptografado de collect()
config.response.addressobjectNão{ "type": "include" } para obter o endereço completo, omitido por padrão

Idempotência​

Envie um event_id para tornar a requisição segura para novas tentativas. A Surt avalia cada event_id uma única vez.

  • Uma requisição repetida com o mesmo event_id retorna 200 com a resposta da primeira avaliação. A Surt não pontua o evento novamente.
  • Uma requisição repetida que chega enquanto a primeira ainda está sendo avaliada retorna 409. Tente novamente após uma breve espera.
  • Se a primeira avaliação falhar, a Surt libera o event_id e uma nova tentativa é avaliada como uma nova requisição.

A Surt mantém um event_id por pelo menos 24 horas. Sem um event_id, cada requisição cria uma nova transação.

Config​

O objeto config controla quais dados opcionais são incluídos na resposta.

{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
CampoValoresPadrãoDescrição
config.response.address.type"include" ou "omit""omit"Se o endereço completo obtido por geocodificação reversa (rua, cidade, estado, país, código postal) deve ser incluído na resposta. Requer dados de GPS no payload.

Quando address é omitido (padrão), a resposta não tem o campo address, mesmo que dados de localização tenham sido coletados. Defina-o como "include" se o seu backend precisar do endereço físico para conformidade, revisão de fraude ou exibição.

Autenticação​

Use sua chave de API da Surt no cabeçalho Authorization como um token Bearer. Esta é uma chamada servidor para servidor. A chave de API nunca chega ao dispositivo.

3. Tratar a resposta​

O endpoint evaluate retorna a transação com seu nível de risco e sua decisão. O exemplo mostra os campos nos quais se basear. O objeto transaction traz mais campos além desses, então ignore qualquer campo que não esteja na tabela abaixo.

Com config.response.address.type: "include"​

{
"status_code": 200,
"message": "Transaction evaluated successfully",
"data": {
"transaction": {
"transaction_id": "1775514112-f2e3034b891e4c6a9d0b7a1c5e8f20",
"event_id": "withdrawal-8841",
"created_at": "2026-04-06T22:21:52Z",
"customer_id": "user_123",
"transaction_type": "withdrawal",
"transaction_name": "User Payment",
"risk_level": "low",
"status": "completed",
"details": {
"risk_level": "low",
"address": {
"street": "Main St",
"city": "San Francisco",
"state": "California",
"country": "United States",
"postal_code": "94103",
"formatted_address": "123 Main St, San Francisco, CA 94103, USA"
}
},
"result": {
"status": "accepted",
"review": false
},
"network_threat": {
"status": "clear"
},
"device": {
"device_id": "5b1f0c1e-8a43-5c0e-9d55-2f6c1d7a9b10",
"manufacturer": "Apple",
"model": "iPhone 15",
"os_version": "18.0"
}
}
}
}

Com config.response.address.type: "omit" (padrão)​

Mesma resposta, mas details não tem o campo address:

"details": {
"risk_level": "low"
}

Campos da resposta​

Todos os campos ficam dentro de data.transaction.

CampoTipoPresenteDescrição
transaction_idstringSempreO ID da Surt para a transação
event_idstringQuando você enviou umO event_id da requisição
created_atstringSempreMomento da criação, ISO 8601 em UTC
customer_idstringQuando você enviou umAusente em uma transação anônima
transaction_typestringSempreO tipo da requisição
transaction_namestringQuando você enviou umO rótulo da requisição
risk_levelstringSemprelow, medium ou high. Veja Níveis de Risco.
statusstringSemprecompleted, ou failed quando a Surt não conseguiu processar a transação
details.risk_levelstringQuando status é completedMesmo valor de risk_level
details.addressobjectQuando status é completed, a requisição o pediu e um endereço foi resolvidoformatted_address (string, sempre), mais street, city, state, country e postal_code (strings, cada uma presente quando conhecida)
details.errorstringQuando status é failedPor que o processamento falhou. risk_level é high nesse caso.
result.statusstringSempreaccepted ou rejected. Esta é a decisão.
result.reviewbooleanSempretrue quando a transação é sinalizada para revisão manual
result.detailsobjectQuando result.status é rejectedPor que a transação foi rejeitada. type é scenarios (com um array scenarios de { scenario_id, scenario_name }), blacklisted, blocked (com kind.type definido como deposits ou withdrawals) ou node_ids.
network_threat.statusstringSemprenot_analyzed, clear ou detected
network_threat.threatsstring[]Quando network_threat.status é detectedQualquer um de vpn, proxy, tor
deviceobjectSempredevice_id (string, sempre), mais manufacturer, model e os_version (strings, cada uma presente quando conhecida)

risk_level e result.status são independentes: uma transação de risco high pode ser accepted. Decida com base em result.status e use risk_level, result.review, network_threat e details.address para suas próprias regras antes de responder ao cliente.

Erros​

CódigoQuando
400JSON malformado, um campo obrigatório ausente, email, phone, event_id ou transaction_type inválido, ou um payload.data que a Surt não consegue descriptografar
401A requisição não tem o cabeçalho Authorization
403A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização
409Outra requisição com o mesmo event_id ainda está sendo avaliada. Tente novamente após uma breve espera.
503Falha temporária. Repita a requisição.

Veja Códigos de Erro para os corpos de resposta.

Substituição de localização​

Assim como em verify(), você pode substituir a coleta de localização por chamada:

// Collect with location
const { payload } = await collect(jwt, { collectLocation: true });

// Collect without location and without a JWT
const { payload } = await collect(undefined, { collectLocation: false });

No Android, collectLocation: true em uma chamada só tem efeito quando collectLocation também era true na inicialização. No iOS, ele habilita a localização para aquela chamada.

CollectResult​

interface CollectResult {
/** Base64-encoded encrypted payload. Pass as payload.data in the evaluate request. */
payload: string;
}

O payload é criptografado e só pode ser descriptografado pelo backend da Surt. Ele contém a impressão digital do dispositivo, sinais de integridade do dispositivo, sinais de segurança e, opcionalmente, a localização.

O resultado de collect() também inclui um objeto diagnostics opcional que descreve o que o SDK observou no dispositivo. O React Native o retorna a partir da v0.5.2. Você pode ignorá-lo.

const { payload, diagnostics } = await collect();
// diagnostics?.location: 'collected' | 'denied' | 'unavailable' | 'timeout' | 'not_requested' | 'error'
// diagnostics?.attestation: 'collected' | 'unavailable' | 'failed' | 'not_supported' | 'not_requested'
// diagnostics?.networkIntel: 'collected' | 'unavailable' | 'not_requested'
// diagnostics?.warnings: { code, signal, detail? }[]
// diagnostics?.timings: { [phase]: ms } (Android; iOS from v0.5.3)

Veja Códigos de Erro → Diagnóstico do resultado.

Exemplo de backend​

app.post('/verify-device', async (req, res) => {
const { payload, userId } = req.body;

const surtResponse = await fetch(
'https://api.surt.com/geolocation/transactions/evaluate',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${process.env.SURT_API_KEY}`,
},
body: JSON.stringify({
customer_id: userId,
transaction_type: 'login',
payload: { type: 'encrypted', data: payload },
config: { response: { address: { type: 'include' } } },
}),
}
);

if (!surtResponse.ok) {
return res.status(502).json({ allowed: false });
}

const { data } = await surtResponse.json();
const risk = data.transaction.risk_level;
const accepted = data.transaction.result.status === 'accepted';

res.json({ allowed: accepted, risk });
});