Collect (Servidor para Servidor)
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 Surt | O SDK (a partir do dispositivo) | Seu backend (servidor para servidor) |
| Exigência de JWT | Obrigatório, um novo para cada chamada | Opcional |
| Seu backend participa | Não | Sim |
| Resposta | VerificationResult (permitido/negado) | CollectResult (payload criptografado) |
| Ideal para | Integração simples, decisões tomadas no frontend | Decisõ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-ipe 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
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
customer_id | string | Não | Seu identificador do usuário. Omita-o, ou envie uma string vazia, para uma transação anônima, por exemplo antes do login. |
transaction_type | string | Sim | login, sign_up, deposit, withdrawal ou uma string personalizada de até 64 caracteres. Veja Tipos de Transação. |
transaction_name | string | Não | Rótulo legível por humanos |
name | string | Não | O nome do cliente |
email | string | Não | O e-mail do cliente. Uma string vazia conta como ausente. Um endereço inválido retorna 400. |
phone | string | Não | O número de telefone do cliente. Uma string vazia conta como ausente. Um número que não pode ser interpretado retorna 400. |
event_id | string | Não | Seu ID para este evento, único dentro da sua organização. De 1 a 128 caracteres: letras, dígitos, ., _, : e -. Veja Idempotência. |
payload.type | string | Sim | Sempre "encrypted" |
payload.data | string | Sim | O payload criptografado de collect() |
config.response.address | object | Nã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_idretorna200com 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_ide 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" }
}
}
}
| Campo | Valores | Padrão | Descriçã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.
| Campo | Tipo | Presente | Descrição |
|---|---|---|---|
transaction_id | string | Sempre | O ID da Surt para a transação |
event_id | string | Quando você enviou um | O event_id da requisição |
created_at | string | Sempre | Momento da criação, ISO 8601 em UTC |
customer_id | string | Quando você enviou um | Ausente em uma transação anônima |
transaction_type | string | Sempre | O tipo da requisição |
transaction_name | string | Quando você enviou um | O rótulo da requisição |
risk_level | string | Sempre | low, medium ou high. Veja Níveis de Risco. |
status | string | Sempre | completed, ou failed quando a Surt não conseguiu processar a transação |
details.risk_level | string | Quando status é completed | Mesmo valor de risk_level |
details.address | object | Quando status é completed, a requisição o pediu e um endereço foi resolvido | formatted_address (string, sempre), mais street, city, state, country e postal_code (strings, cada uma presente quando conhecida) |
details.error | string | Quando status é failed | Por que o processamento falhou. risk_level é high nesse caso. |
result.status | string | Sempre | accepted ou rejected. Esta é a decisão. |
result.review | boolean | Sempre | true quando a transação é sinalizada para revisão manual |
result.details | object | Quando result.status é rejected | Por 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.status | string | Sempre | not_analyzed, clear ou detected |
network_threat.threats | string[] | Quando network_threat.status é detected | Qualquer um de vpn, proxy, tor |
device | object | Sempre | device_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ódigo | Quando |
|---|---|
400 | JSON 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 |
401 | A requisição não tem o cabeçalho Authorization |
403 | A chave de API é inválida ou está inativa, ou o Guardian não está habilitado para a sua organização |
409 | Outra requisição com o mesmo event_id ainda está sendo avaliada. Tente novamente após uma breve espera. |
503 | Falha 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
- Node.js
- Java
- Python
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 });
});
@PostMapping("/verify-device")
public ResponseEntity<Map<String, Object>> verifyDevice(@RequestBody Map<String, Object> body) {
String payload = (String) body.get("payload");
String userId = (String) body.get("userId");
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("Authorization", "Bearer " + System.getenv("SURT_API_KEY"));
Map<String, Object> request = Map.of(
"customer_id", userId,
"transaction_type", "login",
"payload", Map.of("type", "encrypted", "data", payload),
"config", Map.of("response", Map.of("address", Map.of("type", "include")))
);
ResponseEntity<Map> response = restTemplate.exchange(
"https://api.surt.com/geolocation/transactions/evaluate",
HttpMethod.POST,
new HttpEntity<>(request, headers),
Map.class
);
Map data = (Map) response.getBody().get("data");
Map transaction = (Map) data.get("transaction");
String risk = (String) transaction.get("risk_level");
Map result = (Map) transaction.get("result");
boolean accepted = "accepted".equals(result.get("status"));
return ResponseEntity.ok(Map.of("allowed", accepted, "risk", risk));
}
@app.post("/verify-device")
async def verify_device(request: Request):
body = await request.json()
surt_response = requests.post(
"https://api.surt.com/geolocation/transactions/evaluate",
headers={
"Content-Type": "application/json",
"Authorization": f"Bearer {os.environ['SURT_API_KEY']}",
},
json={
"customer_id": body["userId"],
"transaction_type": "login",
"payload": {"type": "encrypted", "data": body["payload"]},
"config": {"response": {"address": {"type": "include"}}},
},
)
surt_response.raise_for_status()
data = surt_response.json()["data"]
risk = data["transaction"]["risk_level"]
accepted = data["transaction"]["result"]["status"] == "accepted"
return {"allowed": accepted, "risk": risk}