Saltar al contenido principal
POST
curl
Usa POST /v3/ip/risk/ cuando tu backend ya tiene una dirección IP y necesita una decisión de riesgo de servidor a servidor. La respuesta incluye geolocalización, propiedad de la red, indicadores de VPN/Tor y de centro de datos, datos de amenazas y country_mismatch cuando envías un país declarado.

Interpretar la respuesta

  • status es In Review cuando el país resuelto no coincide con claimed_country, o cuando la dirección está asociada a infraestructura de VPN, Tor o centro de datos. En caso contrario, es Approved.
  • ip.ip_country_code contiene el código del país resuelto. Compara los países mediante ip.country_mismatch en lugar de comparar tú mismo las cadenas de país sin procesar.
  • ip.latitude y ip.longitude son una geolocalización aproximada de la red, no una ubicación precisa del dispositivo.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type e ip.threat contienen evidencias de riesgo de red.
  • ip.asn_number, ip.asn_organization, ip.connection_type e ip.carrier describen la red a la que pertenece la dirección.
  • request_id es el ID de sesión de la API. Guárdalo junto con vendor_data si necesitas correlacionar el resultado con webhooks posteriores o con la actividad en la consola.
El enriquecimiento de IP se realiza en la medida de lo posible. Si ninguna fuente de enriquecimiento devuelve datos utilizables, el endpoint devuelve una respuesta aprobada con ip.ip_address: null, ip.country_mismatch: null y un objeto ip.threat vacío. Los campos de enriquecimiento individuales también pueden ser null cuando no están disponibles.

Inteligencia de dispositivo

La API de riesgo de IP es un endpoint exclusivamente de servidor a servidor. La huella digital del dispositivo no lo es, porque un backend no puede observar por sí solo las señales del navegador o del dispositivo. En las sesiones del flujo alojado y del SDK, Didit expone en la respuesta de la sesión los campos de dispositivo ya recopilados, incluidos device_fingerprint, los detalles del dispositivo y del navegador, user_agent, los datos sin procesar del dispositivo y las coincidencias entre sesiones.

Comportamiento en sandbox

Las claves de sandbox validan la solicitud y devuelven datos deterministas aprobados. No contactan con servicios de inteligencia externos, no consumen créditos, no crean una sesión ni contribuyen a Networks.

Facturación

Las llamadas a la API de riesgo de IP cuestan $0.02 a precio de lista. Una solicitud en producción se factura en cuanto se inicia la consulta.

Autorizaciones

x-api-key
string
header
requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

application/json
ip_address
string<ip>
requerido

Dirección IPv4 o IPv6 que se va a puntuar.

Ejemplo:

"8.8.8.8"

claimed_country
string

País ISO 3166-1 alfa-2 o alfa-3 opcional declarado por el usuario o la sesión. Se usa para calcular country_mismatch.

Maximum string length: 3
Ejemplo:

"ESP"

user_agent
string

User agent observado por tu backend. Se almacena como contexto de la solicitud; no proporciona huella digital del dispositivo.

Maximum string length: 512
vendor_data
string

Tu referencia estable para esta solicitud. Se guarda en la sesión de API y se devuelve en la respuesta.

metadata
object | null

Tus metadatos JSON no sensibles. Se almacenan en la sesión de API y se devuelven en la respuesta.

Respuesta

La evaluación de riesgo se completó. Consulta status para ver la decisión; el código HTTP siempre es 200 en las consultas completadas.

request_id
string<uuid>
requerido

ID de la sesión de API creada para esta solicitud. Guárdalo junto con vendor_data si necesitas relacionar el resultado con webhooks posteriores o con la actividad en la consola.

status
enum<string>
requerido

Decisión para esta sesión de API: In Review ante riesgo de red o de discrepancia de país; en caso contrario, Approved.

Opciones disponibles:
Approved,
In Review
created_at
string<date-time>
requerido

Marca de tiempo de esta respuesta.

vendor_data
string | null

Devuelve el vendor_data que enviaste, o null si no enviaste ninguno.

metadata
object | null

Devuelve el metadata que enviaste, o null si no enviaste ninguno.

ip
object

Resultado de riesgo de la IP. Los campos de enriquecimiento individuales pueden ser null cuando la consulta no devolvió datos utilizables.

Última modificación el 1 de noviembre de 2026