Glosario

Los términos se definen tal como los usa la API. Cuando una palabra también tiene un significado cotidiano más laxo, se aplica el significado de la API.

Identificadores y productos

Término	Significado
identificador	La única cosa sobre la que trata una comprobación en tiempo real: un número de teléfono o una dirección de correo electrónico. Un envío masivo lleva una lista de ellos.
serie	Si un identificador es phone o email. Los productos, los endpoints y las solicitudes son específicos de una serie, y una solicitud solo puede mezclar series en el sentido de que no debe mezclarlas en absoluto.
producto	Un objetivo de detección — una plataforma, más el tipo de comprobación que se realiza contra ella. «WhatsApp Number Checker» y «WhatsApp Activity Details» son dos productos distintos, aunque ambos traten sobre WhatsApp.
producto en tiempo real	Un producto que se usa a través de los endpoints síncronos. Se direcciona por su ID numérico.
producto masivo	Un producto que se usa a través de los endpoints asíncronos. Se direcciona por su slug.
ID	El entero que identifica un producto en tiempo real, mostrado como #47 en el catálogo. Los ID son lo que acepta product_ids.
slug	La cadena que identifica un producto masivo, por ejemplo waValid. Los slugs son lo que acepta el campo product.
modo	realtime o async. Un producto pertenece exactamente a uno, y el modo decide qué endpoints lo aceptan.

Los ID y los slugs no son intercambiables

Un ID en tiempo real nunca se resuelve en un endpoint masivo, y un slug masivo nunca se resuelve en uno en tiempo real. Mezclarlos es el error de integración más común, y ninguno de los dos lados lo resuelve en silencio — pero fallan de forma distinta, porque los dos lados validan de forma distinta:

• product_ids se valida como un arreglo de enteros, así que un slug de tipo cadena se rechaza como 400 invalid_realtime_request antes de que ocurra cualquier búsqueda de producto.
• El campo product masivo se busca por slug, así que el slug de un producto en tiempo real se encuentra — y luego se rechaza como 422 product_mode_not_supported, porque los endpoints asíncronos aceptan solo productos asíncronos.

Veredictos

Término	Significado
registrado	Lo que la detección responde en realidad: ¿está este identificador registrado en esta plataforma? No es una afirmación sobre si el número o la dirección es sintácticamente válido, alcanzable o está en servicio.
valid	Confirmado como registrado. Cobrado.
invalid	Confirmado como no registrado. Cobrado — una respuesta negativa sigue siendo una respuesta.
unknown	El proveedor no pudo resolverlo. No cobrado; reembolsado.
en caché	El veredicto se sirvió desde un dato almacenado en lugar de preguntar a un proveedor. Un acierto de caché igualmente se cobra.
combinación	Una solicitud en tiempo real, un identificador y los de uno a diez productos contra los que se comprobó. Una combinación puede tener éxito parcial — consulta partial_succeeded.

Dinero

Término	Significado
reservar	Tomar el importe por adelantado antes de que se ejecute el trabajo. Todo envío se reserva contra el saldo de la cuenta.
liquidar	Decidir el cobro final de un elemento individual una vez conocido su veredicto.
reembolsar	Devolver el importe reservado de un elemento que no produjo ningún veredicto utilizable.
billing_status	Campo por elemento: charged o refunded. Lee esto en lugar de inferirlo del estado HTTP.
total_reserved	Reservado antes de que se ejecutara el trabajo. Siempre es igual a total_charged + total_refunded.
charged_amount	Cobro neto. refunded_amount es el reembolso neto.

Solicitudes y tareas

Término	Significado
request_id	UUID que identifica un envío en tiempo real. Cítalo en las solicitudes de soporte.
task_id	El token que identifica un envío masivo, devuelto al enviar. También es el parámetro de ruta {token} de los endpoints de tarea — un valor, dos nombres en la documentación.
Idempotency-Key	Un encabezado que aporta quien llama, obligatorio en las llamadas en tiempo real, que hace seguro un reintento: la misma clave con el mismo cuerpo devuelve el resultado almacenado en lugar de cobrar de nuevo.
repetido	La respuesta provino de un resultado almacenado y no de trabajo nuevo. replayed en una respuesta en tiempo real, idempotent_replay en un envío masivo. Una repetición nunca mueve dinero.
recovery_pending	La tarea masiva está en cola, pero su contabilidad todavía se está conciliando.

Contadores de tarea

Término	Significado
submitted	Filas que enviaste.
prefiltered	Filas descartadas antes de la detección — líneas mal formadas, por ejemplo.
deduped	Filas duplicadas eliminadas.
total	Filas realmente comprobadas: submitted menos prefiltered menos deduped.
processed	Filas que el canal de origen ha terminado hasta ahora.
unknown_unprocessed	Filas que nunca se resolvieron. Estas son las que se reembolsan.

Límites y retención

Término	Significado
límite por clave	El presupuesto asociado a tu clave API. Este es el que hay que tener en cuenta al planificar.
límite por IP	Un techo más grueso compartido por todas las claves detrás de una misma dirección. No es un control de acceso.
retención	Cuánto tiempo sobrevive un registro. Registros en tiempo real y resultados de repetición: 30 días. Archivos de resultados masivos: 7 días.

Relacionado

• Formato de respuesta — la envoltura, y cómo se codifican el dinero y las marcas de tiempo
• Códigos de error — el mismo vocabulario aplicado a los fallos