Saltar al contenido principal
Version: Guardian v0.5.3

Collect (Servidor a servidor)

v0.3.0+

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 SurtEl SDK (desde el dispositivo)Tu backend (servidor a servidor)
Requisito de JWTRequerido, uno nuevo para cada llamadaOpcional
Tu backend participaNoSí
RespuestaVerificationResult (permitido/denegado)CollectResult (payload cifrado)
Ideal paraIntegración sencilla, decisiones dirigidas por el frontendDecisiones 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-ip y 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​

CampoTipoRequeridoDescripción
customer_idstringNoTu 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_typestringSílogin, sign_up, deposit, withdrawal, o una cadena personalizada de hasta 64 caracteres. Consulta Tipos de transacción.
transaction_namestringNoEtiqueta legible para personas
namestringNoEl nombre del cliente
emailstringNoEl correo electrónico del cliente. Una cadena vacía cuenta como ausente. Una dirección inválida devuelve 400.
phonestringNoEl 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_idstringNoTu ID para este evento, único dentro de tu organización. De 1 a 128 caracteres: letras, dígitos, ., _, : y -. Consulta Idempotencia.
payload.typestringSíSiempre "encrypted"
payload.datastringSíEl payload cifrado de collect()
config.response.addressobjectNo{ "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_id devuelve 200 con 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_id y 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" }
}
}
}
CampoValoresPredeterminadoDescripció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.

CampoTipoPresenteDescripción
transaction_idstringSiempreEl ID de Surt para la transacción
event_idstringCuando enviaste unoEl event_id de la solicitud
created_atstringSiempreHora de creación, ISO 8601 en UTC
customer_idstringCuando enviaste unoAusente en una transacción anónima
transaction_typestringSiempreEl tipo de la solicitud
transaction_namestringCuando enviaste unoLa etiqueta de la solicitud
risk_levelstringSiemprelow, medium o high. Consulta Niveles de riesgo.
statusstringSiemprecompleted, o failed cuando Surt no pudo procesar la transacción
details.risk_levelstringCuando status es completedEl mismo valor que risk_level
details.addressobjectCuando status es completed, la solicitud la pidió y se resolvió una direcciónformatted_address (string, siempre), más street, city, state, country y postal_code (strings, cada uno presente cuando se conoce)
details.errorstringCuando status es failedPor qué falló el procesamiento. risk_level es high en este caso.
result.statusstringSiempreaccepted o rejected. Esta es la decisión.
result.reviewbooleanSiempretrue cuando la transacción está marcada para revisión manual
result.detailsobjectCuando result.status es rejectedPor 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.statusstringSiemprenot_analyzed, clear o detected
network_threat.threatsstring[]Cuando network_threat.status es detectedCualquiera de vpn, proxy, tor
deviceobjectSiempredevice_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ódigoCuándo
400JSON malformado, falta un campo requerido, email, phone, event_id o transaction_type inválidos, o un payload.data que Surt no puede descifrar
401La solicitud no tiene el encabezado Authorization
403La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización
409Otra solicitud con el mismo event_id todavía se está evaluando. Reintenta después de una espera breve.
503Fallo 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​

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 });
});