API Antifraude — Comprobaciones previas a una operación (1.0)

Download OpenAPI specification:Download

INTRODUCCION

Comprobaciones que se hacen antes de dar por bueno un dato: dar de alta a alguien, mandarle un código de verificación o aceptarle un pago.

Todas las comprobaciones se piden por la misma llamada. El parámetro SERVICIO dice cuál se quiere, y los parámetros que no son de ese servicio se ignoran: puede mandar siempre la misma estructura y cambiar solo SERVICIO. Los servicios que se vayan añadiendo (correo, IP…) entrarán por aquí, sin que usted tenga que integrar otra URL.

SERVICIOS DISPONIBLES

SERVICIO	Qué comprueba
`DatosTelefono`	Quién hay detrás de un número: operadora que le da servicio, portabilidad (de qué operadora vino y cuándo se portó) y tipo de línea.
`DatosEmail`	Qué hay detrás de una dirección: si el dominio recibe correo y es gratuito, temporal o propio, si la cuenta es de una persona o de un departamento, y si el buzón existe.
`DatosIP`	Desde dónde se conecta alguien: país, ciudad, operador, si es la línea de una casa, un móvil o un centro de datos, y si llega por una red anónima.

POR QUE LA PORTABILIDAD Y EL TIPO DE LINEA

De todo lo que se puede saber de un número sin llamarlo, estos dos datos son los que de verdad cambian una decisión.

La fecha de portabilidad. Un número que cambió de operadora hace tres días, justo antes de una operación importante, es el patrón del secuestro de línea: el atacante se lleva el número de la víctima a otro operador y a partir de ahí recibe él los SMS de verificación. Si va a mandar un código a ese número, conviene verificar antes por otra vía.

El tipo de línea. Una línea por Internet (VoIP) donde debería haber un móvil suele ser un número de usar y tirar: se contratan en minutos y se abandonan igual de rápido. Y una numeración de tarificación adicional o de máquina a máquina no es el teléfono personal de nadie.

Con eso, la respuesta trae además un riesgo calculado de 0 a 100 con los motivos en texto. No es un veredicto y no decide por usted: es lo que los datos permiten decir, explicado, para que su sistema aplique su propia política.

QUE MIRA LA COMPROBACION DE UN CORREO

Es la misma comprobación que hacemos nosotros antes de cada envío de Email Certificado, puesta a su disposición. Va de lo barato a lo caro y para en cuanto tiene la respuesta:

1. Sintaxis de la dirección.
2. El dominio recibe correo: se consultan sus registros de correo en las DNS. Un dominio sin ellos no puede recibir nada, así que la dirección no existe —y esto se sabe sin preguntar a nadie.
3. Dominio temporal, de esos que se crean en un segundo y nadie vuelve a leer.
4. Dominio gratuito y tipo de cuenta: de una persona, de un departamento (info@, soporte@…) o un alias con etiqueta (juan+tienda@).
5. Si esa dirección ya nos rebotó un envío antes. Es información nuestra, y vale más que cualquier predicción: no es que probablemente falle, es que ya falló.
6. Y solo entonces, si el buzón existe, preguntándoselo al servidor de correo del destino.

El paso 6 usa dos verificadores distintos: hay servidores que dan lista gris, que cortan la conexión o que responden diferente según quién pregunte, y cuando el primero dice «no lo sé» se consulta al segundo. Aun así, hay dominios catch-all que aceptan cualquier dirección: ahí nadie puede confirmar que una cuenta concreta exista, y se lo decimos tal cual en vez de inventar un sí.

DE DONDE SALEN LOS DATOS

Para los móviles españoles se usa nuestro propio registro de portabilidad, que es lo que nos permite dar el operador del que venía el número y la fecha exacta del cambio. Para los fijos españoles y cualquier número extranjero se consulta la numeración internacional. Usted no tiene que elegir: manda el número y se resuelve por donde toque.

El campo Fuente de la respuesta le dice cuál se ha usado. El historial de portabilidad no lo publican todos los países: cuando no hay dato, Portabilidad.Consta viene a 0 —que no es lo mismo que «no se ha portado», y por eso se distinguen.

PRECIO

Se cobra por consulta resuelta. Si no se puede resolver, la llamada devuelve -4 y no se cobra nada.

La misma consulta repetida en menos de un minuto (un doble envío, un reintento de su sistema) devuelve el resultado anterior marcado con Repetida=1 y tampoco se cobra. Pasado ese minuto se vuelve a consultar de verdad y se vuelve a cobrar: el dato puede haber cambiado, y justo la portabilidad de ayer es la que le interesa.

AUTENTICACION

Igual que el resto de nuestras APIs: autenticación Basic con su usuario y su API Token, que encontrará en su panel en Sus datos → Configurar → Seguridad. Recuerde autorizar ahí también la IP pública desde la que llamará.

Consultar

/Consultar

Realiza una comprobación antifraude. El parámetro SERVICIO elige cuál: con DatosTelefono devuelve operadora, portabilidad y tipo de línea del número; con DatosEmail, el dominio, el tipo de cuenta y si el buzón existe; con DatosIP, desde dónde se conecta alguien y qué clase de conexión usa. En los tres casos, además, el riesgo calculado y sus motivos.

Los campos de la respuesta dependen del servicio: Numero, Linea, Operadora y Portabilidad solo vienen en DatosTelefono, Email, Dominio, Cuenta, Buzon, Historial y Reputacion solo en DatosEmail, y IP, Ubicacion, Operador, Conexion y ListasNegras solo en DatosIP. Res, Servicio, Consulta, Riesgo, Fuente, Creditos y Cred vienen siempre.

Authorizations:

basicAuth

query Parameters

Servicio	string Enum: "DATOSTELEFONO" "DATOSEMAIL" "DATOSIP" Example: Servicio=DatosTelefono Comprobación que quiere realizar. No distingue mayúsculas de minúsculas. `DatosTelefono` - Operadora, portabilidad y tipo de línea de un número. Necesita `TELEFONO`. `DatosEmail` - Dominio, tipo de cuenta y existencia del buzón de una dirección. Necesita `EMAIL`.
Telefono	string Example: Telefono=600000000 Número a comprobar, obligatorio con `SERVICIO=DatosTelefono`. Puede enviarlo nacional (`600000000`) acompañado de `PREFIJO`, o internacional completo (`+34600000000` o `0034600000000`), en cuyo caso `PREFIJO` sobra. Se ignoran espacios, guiones y paréntesis.
Prefijo	string Example: Prefijo=+34 Prefijo internacional del país del número, con o sin `+`. Solo se usa cuando `TELEFONO` viene en formato nacional.
Email	string Example: Email=nombre@dominio.com Dirección de correo a comprobar, obligatoria con `SERVICIO=DatosEmail`.
Listasnegras	string Enum: 0 1 Example: Listasnegras=1 Solo con `SERVICIO=DatosEmail`. Indique `1` para comprobar además si el dominio —o el servidor de correo desde el que sale— está en listas negras públicas de abuso. No cuesta créditos, pero la llamada tarda bastante más: hay que preguntar a varios servidores externos y esperarles.
Filtraciones	string Enum: 0 1 Example: Filtraciones=1 Solo con `SERVICIO=DatosEmail`. Indique `1` para comprobar si la dirección ha aparecido en filtraciones de datos conocidas. Cuesta un extra sobre el precio de la consulta. Léalo al derecho: aparecer en una filtración no es una mancha del dueño —el que perdió los datos fue el servicio donde estaba registrado—. Lo que aporta es lo contrario: demuestra desde cuándo existe esa dirección, y por eso en el cálculo de riesgo resta cuando la filtración más antigua tiene ya unos años. Una dirección creada esta mañana para una estafa no puede tener ese rastro. Si no se puede consultar (el servicio limita el ritmo de peticiones), la llamada devuelve el resto de la comprobación, lo explica en `Aviso` y no se le cobra el extra.
Ip	string Example: Ip=80.24.10.5 Dirección IPv4 a comprobar, obligatoria con `SERVICIO=DatosIP`. Las direcciones de redes privadas o reservadas se rechazan: no identifican una conexión a Internet.
Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Tipo de respuesta a mostrar como resultado de la llamada. `JSON` - La respuesta la obtendrá en JSON `XML` - La respuesta la obtendrá en XML `TXT` - La respuesta la obtendrá en formato Texto

Request Body schema:
application/json

Los parámetros se envían en el cuerpo de la petición POST, como objeto JSON (Content-Type application/json, RECOMENDADO) o como formulario application/x-www-form-urlencoded. En el formato formulario, los parámetros de tipo array u objeto se envían como string JSON-codificado. Los nombres de los parámetros no distinguen mayúsculas de minúsculas. La descripción detallada de cada parámetro está en la sección de parámetros de esta operación.

Servicio	string
Telefono	string
Prefijo	string
Email	string
Listasnegras	string
Filtraciones	string
Ip	string
Resp	string

Responses

Response Schema:
application/json

Array

Res required	integer <int32> Resultado de la llamada `1` Consulta realizada. `-1` Error de autenticación o IP no autorizada. `-2` No dispone de créditos suficientes. `-3` Error en los parámetros. Obtendrá el detalle en Error. `-4` No se ha podido resolver la consulta. No se ha cobrado nada; reinténtelo en unos minutos. `-5` El SERVICIO indicado no existe.
Servicio	string Comprobación que se ha realizado.
Consulta	string El dato consultado, ya normalizado a formato internacional.
Email	Array of arrays Solo con `SERVICIO=DatosEmail`. La dirección desmontada. `Sugerencia` trae la corrección cuando parece un error de escritura (`gmial.com` → `gmail.com`) y viene vacía el resto de las veces.
Dominio	Array of arrays Solo con `SERVICIO=DatosEmail`. `RecibeCorreo` a `0` significa que el dominio no tiene el correo configurado en sus DNS: la dirección no existe. `Tipo` es el valor estable para su código: `gratuito`, `temporal` o `propio`. `AntiguedadDias` es `-1` cuando no se ha podido averiguar.
Cuenta	Array of arrays Solo con `SERVICIO=DatosEmail`. Qué hay detrás de la parte anterior a la arroba. `Tipo`: `personal`, `rol` (buzón de un departamento: `info@`, `soporte@`…, que leen varias personas y no identifica a nadie) o `alias` (dirección con etiqueta, `juan+tienda@`: del mismo buzón salen infinitas).
Buzon	Array of arrays Solo con `SERVICIO=DatosEmail`. `Estado`: `valido`, `noexiste`, `catchall` (el dominio acepta cualquier dirección y nadie puede confirmar que esta cuenta exista), `desconocido` (el servidor de destino no ha dejado comprobarlo) o `nocomprobado` (no hizo falta: el dominio no recibe correo o es temporal, y por eso no se ha gastado en verificarlo).
Historial	Array of arrays Solo con `SERVICIO=DatosEmail`. Si esa dirección ya rebotó un envío nuestro anteriormente, con el motivo que dio el servidor de destino. Es un hecho, no una predicción.
Reputacion	Array of arrays Solo en los servicios de correo. `Trampa` a `1` significa que la dirección está catalogada como trampa antispam o como origen de denuncias: escribirle perjudica la entrega de todos sus correos.
Numero	Array of arrays Solo con `SERVICIO=DatosTelefono`. El número en sus distintos formatos y su país. `Nacional` son los dígitos sin prefijo, que es lo que su programa querrá guardar; `Formato` es la versión legible para enseñar en pantalla y puede venir vacía. `Valido` a `0` significa que el número no está asignado o no es válido en su país.
Linea	Array of arrays Solo con `SERVICIO=DatosTelefono`. Tipo de línea. `Tipo` es el valor estable para su código: `movil`, `fijo`, `voip`, `gratuito`, `compartido`, `premium`, `personal`, `m2m` o `desconocido`. `TipoTexto` es la versión legible.
Operadora	Array of arrays Solo con `SERVICIO=DatosTelefono`. Operadora que presta servicio al número. `MCC`/`MNC` identifican la red móvil y vienen vacíos en fijos.
Portabilidad	Array of arrays Solo con `SERVICIO=DatosTelefono`. Historial de portabilidad. `Consta` a `0` significa que ese país no publica el dato, que no es lo mismo que no haberse portado. `Dias` son los días transcurridos desde el cambio (`-1` si no se sabe): es el dato clave para detectar un secuestro de línea.
IP	Array of arrays Solo con `SERVICIO=DatosIP`. La dirección consultada.
Ubicacion	Array of arrays Solo con `SERVICIO=DatosIP`. Dónde está la dirección. Con cuidado: la ubicación la cambia cualquiera con una VPN, así que no decide por sí sola; el dato que decide es `Conexion.Tipo`.
Operador	Array of arrays Solo con `SERVICIO=DatosIP`. Quién es el dueño de la dirección: el operador, su red (sistema autónomo) y el bloque al que pertenece, con la fecha en que se asignó. Un bloque asignado hace nada no acusa a nadie, pero de ahí salen muchos de los rangos que se alquilan para abusar.
Conexion	Array of arrays Solo con `SERVICIO=DatosIP`. Lo más importante de esta consulta. `Tipo`: `domestica`, `movil`, `centrodatos`, `anonima` o `desconocida`. Una persona se conecta desde su casa o desde su móvil; detrás de un `centrodatos` hay un servidor, que puede ser una VPN de empresa legitima o algo automatizado haciéndose pasar por alguien. `InversoConfirmado` vale `1` si el nombre inverso de la IP lleva de vuelta a esa misma dirección, `0` si no cuadra —un nombre que no corresponde lo pone quien no manda en ese rango— y `-1` si no hay nombre inverso.
ListasNegras	Array of arrays Listas negras públicas de abuso. En `DatosIP` se consulta la propia dirección; en `DatosEmail`, el dominio y las IPs de sus servidores de correo —un dominio limpio cuyo correo sale de una máquina fichada no es un dominio limpio—. `SinComprobar` es el número de listas que no han permitido la consulta. Importa: `Listada=0` con `SinComprobar>0` no es lo mismo que un «no está» limpio, y por eso se dice. Algunas listas rechazan a quien pregunta sin acuerdo previo y responden con un código que un sistema descuidado leería como «listada»: aquí se distinguen.
Filtraciones	Array of arrays Solo con `SERVICIO=DatosEmail` y `FILTRACIONES=1`. `Consultado` a `0` significa que no se pidió o no se pudo. `AnosVisible` son los años que la dirección lleva demostrablemente en uso, contados desde la filtración más antigua: es el dato útil de aquí.
Aviso	string Advertencia sobre la propia consulta cuando la hay: por ejemplo, que las filtraciones no se han podido consultar y por eso no se ha cobrado ese extra. Vacío o ausente el resto de las veces.
Riesgo	Array of arrays Riesgo calculado de 0 a 100, su `Nivel` (`BAJO` por debajo de 25, `MEDIO` hasta 49, `ALTO` a partir de 50) y los `Motivos` que lo explican, en texto. Es información para su política, no una decisión.
Fuente	string De dónde salen los datos: `propia` (nuestro registro de portabilidad, móviles españoles) o `proveedor` (consulta de numeración internacional).
Repetida	integer A `1` cuando es la misma consulta hecha hace menos de un minuto: se devuelve el resultado anterior y no se ha cobrado.
Creditos	number Créditos cobrados por esta llamada.
Cred	number Créditos que le quedan tras la consulta.
Error	string Descripción del problema cuando Res es negativo.

Request samples

Content type

application/json

{"Servicio": "DatosTelefono",
"Telefono": "600000000",
"Prefijo": "+34",
"Email": "nombre@dominio.com",
"Listasnegras": "1",
"Filtraciones": "1",
"Ip": "80.24.10.5",
"Resp": "JSON"
}

Response samples