Collect (Servidor a servidor)
Dos rutas de verificación
El SDK Guardian ofrece dos formas de verificar dispositivos. Elige según tu arquitectura:
verify() | collect() | |
|---|---|---|
| Quién llama a Surt | El SDK (desde el dispositivo) | Tu backend (servidor a servidor) |
| Requisito de JWT | Requerido, uno nuevo para cada llamada | Opcional |
| Tu backend participa | No | Sí |
| Respuesta | VerificationResult (permitido/denegado) | CollectResult (payload cifrado) |
| Ideal para | Integración sencilla, decisiones dirigidas por el frontend | Decisiones dirigidas por el backend, lógica personalizada, requisitos de auditoría |
Flujo de verify()
App → fetch fresh JWT from your backend → SDK.verify(jwt) → Surt backend → risk decision → App
El SDK llama a Surt directamente y devuelve allowed: true/false. Tu app actúa sobre la decisión de inmediato. Solicita un JWT nuevo para cada llamada.
Flujo de collect()
App → SDK.collect() → encrypted payload → App → Your backend → Surt /evaluate → Your backend → App
El SDK recopila los datos del dispositivo y los cifra en el dispositivo. collect() no envía el payload del dispositivo a Surt. Tu backend envía el payload al endpoint de evaluación de Surt, recibe la evaluación de riesgo y decide qué devolver a tu app.
Cuándo usar collect()
- Tu backend necesita los datos de riesgo antes de responder al cliente
- Quieres combinar el riesgo del dispositivo con tu propia lógica de negocio del lado del servidor
- Necesitas control total sobre lo que ve el cliente
Uso
1. Recopila en el 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
};
}
El JWT es opcional para collect(). Cuando pasas uno, el SDK hace dos cosas con él:
- Llama a
GET /geolocation/client-ipy agrega la IP pública del dispositivo al payload. - Aplica la configuración de atestación de tu organización: con qué frecuencia atesta un dispositivo y, en Android, tu propio proyecto de Play Integrity. Consulta Configuración de la atestación de dispositivo.
Sin un JWT, el payload no lleva una IP pública resuelta y el SDK atesta en cada llamada con la configuración predeterminada. Solicita un JWT nuevo para cada transacción. Un JWT expira 30 minutos después de emitirse.
2. Llama a Surt desde tu backend
Tu backend recibe el payload cifrado de la app y luego llama al endpoint de evaluación de 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 de la solicitud
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
customer_id | string | No | Tu identificador de usuario. Omítelo, o envía una cadena vacía, para una transacción anónima, por ejemplo antes del inicio de sesión. |
transaction_type | string | Sí | login, sign_up, deposit, withdrawal, o una cadena personalizada de hasta 64 caracteres. Consulta Tipos de transacción. |
transaction_name | string | No | Etiqueta legible para personas |
name | string | No | El nombre del cliente |
email | string | No | El correo electrónico del cliente. Una cadena vacía cuenta como ausente. Una dirección inválida devuelve 400. |
phone | string | No | El número de teléfono del cliente. Una cadena vacía cuenta como ausente. Un número que no se puede interpretar devuelve 400. |
event_id | string | No | Tu ID para este evento, único dentro de tu organización. De 1 a 128 caracteres: letras, dígitos, ., _, : y -. Consulta Idempotencia. |
payload.type | string | Sí | Siempre "encrypted" |
payload.data | string | Sí | El payload cifrado de collect() |
config.response.address | object | No | { "type": "include" } para obtener la dirección completa, omitida de forma predeterminada |
Idempotencia
Envía un event_id para que la solicitud se pueda reintentar de forma segura. Surt evalúa cada event_id una sola vez.
- Una solicitud repetida con el mismo
event_iddevuelve200con la respuesta de la primera evaluación. Surt no vuelve a puntuar el evento. - Una solicitud repetida que llega mientras la primera todavía se está evaluando devuelve
409. Reintenta después de una espera breve. - Si la primera evaluación falla, Surt libera el
event_idy un reintento se evalúa como una solicitud nueva.
Surt conserva un event_id durante al menos 24 horas. Sin un event_id, cada solicitud crea una transacción nueva.
Config
El objeto config controla qué datos opcionales se incluyen en la respuesta.
{
"config": {
"response": {
"address": { "type": "include" }
}
}
}
| Campo | Valores | Predeterminado | Descripción |
|---|---|---|---|
config.response.address.type | "include" u "omit" | "omit" | Indica si se incluye en la respuesta la dirección completa obtenida por geocodificación inversa (calle, ciudad, estado, país, código postal). Requiere datos GPS en el payload. |
Cuando address se omite (predeterminado), la respuesta no tiene el campo address, incluso si se recopilaron datos de ubicación. Establécelo en "include" si tu backend necesita la dirección física para cumplimiento, revisión de fraude o visualización.
Autenticación
Usa tu clave de API de Surt en el encabezado Authorization como token Bearer. Esta es una llamada de servidor a servidor. La clave de API nunca llega al dispositivo.
3. Maneja la respuesta
El endpoint de evaluación devuelve la transacción con su nivel de riesgo y su decisión. El ejemplo muestra los campos sobre los que puedes construir. El objeto transaction lleva más campos que estos, así que ignora cualquier campo que no esté en la tabla de abajo.
Con 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"
}
}
}
}
Con config.response.address.type: "omit" (predeterminado)
La misma respuesta, pero details no tiene el campo address:
"details": {
"risk_level": "low"
}
Campos de la respuesta
Todos los campos están dentro de data.transaction.
| Campo | Tipo | Presente | Descripción |
|---|---|---|---|
transaction_id | string | Siempre | El ID de Surt para la transacción |
event_id | string | Cuando enviaste uno | El event_id de la solicitud |
created_at | string | Siempre | Hora de creación, ISO 8601 en UTC |
customer_id | string | Cuando enviaste uno | Ausente en una transacción anónima |
transaction_type | string | Siempre | El tipo de la solicitud |
transaction_name | string | Cuando enviaste uno | La etiqueta de la solicitud |
risk_level | string | Siempre | low, medium o high. Consulta Niveles de riesgo. |
status | string | Siempre | completed, o failed cuando Surt no pudo procesar la transacción |
details.risk_level | string | Cuando status es completed | El mismo valor que risk_level |
details.address | object | Cuando status es completed, la solicitud la pidió y se resolvió una dirección | formatted_address (string, siempre), más street, city, state, country y postal_code (strings, cada uno presente cuando se conoce) |
details.error | string | Cuando status es failed | Por qué falló el procesamiento. risk_level es high en este caso. |
result.status | string | Siempre | accepted o rejected. Esta es la decisión. |
result.review | boolean | Siempre | true cuando la transacción está marcada para revisión manual |
result.details | object | Cuando result.status es rejected | Por qué se rechazó la transacción. type es scenarios (con un arreglo scenarios de { scenario_id, scenario_name }), blacklisted, blocked (con kind.type igual a deposits o withdrawals), o node_ids. |
network_threat.status | string | Siempre | not_analyzed, clear o detected |
network_threat.threats | string[] | Cuando network_threat.status es detected | Cualquiera de vpn, proxy, tor |
device | object | Siempre | device_id (string, siempre), más manufacturer, model y os_version (strings, cada uno presente cuando se conoce) |
risk_level y result.status son independientes: una transacción de riesgo high puede ser accepted. Decide según result.status, y usa risk_level, result.review, network_threat y details.address para tus propias reglas antes de responder al cliente.
Errores
| Código | Cuándo |
|---|---|
400 | JSON malformado, falta un campo requerido, email, phone, event_id o transaction_type inválidos, o un payload.data que Surt no puede descifrar |
401 | La solicitud no tiene el encabezado Authorization |
403 | La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización |
409 | Otra solicitud con el mismo event_id todavía se está evaluando. Reintenta después de una espera breve. |
503 | Fallo temporal. Reintenta la solicitud. |
Consulta Códigos de error para ver los cuerpos de respuesta.
Anulación de ubicación
Igual que con verify(), puedes anular la recopilación de ubicación por llamada:
// Collect with location
const { payload } = await collect(jwt, { collectLocation: true });
// Collect without location and without a JWT
const { payload } = await collect(undefined, { collectLocation: false });
En Android, collectLocation: true en una llamada solo tiene efecto cuando collectLocation también era true en la inicialización. En iOS habilita la ubicación para esa llamada.
CollectResult
interface CollectResult {
/** Base64-encoded encrypted payload. Pass as payload.data in the evaluate request. */
payload: string;
}
El payload está cifrado y solo puede descifrarlo el backend de Surt. Contiene la huella digital del dispositivo, señales de integridad del dispositivo, señales de seguridad y, opcionalmente, la ubicación.
El resultado de collect() también incluye un objeto opcional diagnostics que describe lo que el SDK observó en el dispositivo. React Native lo devuelve a partir de v0.5.2. Puedes ignorarlo.
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)
Consulta Códigos de error → Diagnósticos del resultado.
Ejemplo 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}