Appearance
Rastreo de contacto (skip trace)
Generado desde
DialerDigital/corecommit0fc18008b3c8— especificaciónopenapi/dialer-v1.yamlv0.134.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.
Traducción en curso
Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.
Rastreo de contacto (F0): una consulta medida a un proveedor, detrás de un tope mensual por tenant con corte duro. Todavía no genera línea de factura.
Endpoints
| Método | Ruta | Resumen |
|---|---|---|
POST | /v1/skip-trace/lookups | Una consulta medida de rastreo de contacto (skip trace) |
GET | /v1/skip-trace/cap | Los límites mensuales de rastreo de contacto del tenant y el uso acumulado hasta ahora |
PUT | /v1/skip-trace/cap | Establecer o borrar los límites mensuales de rastreo de contacto del tenant |
Una consulta medida de rastreo de contacto (skip trace)
http
POST /v1/skip-trace/lookupsÁmbito de tenant (una clave dd_ o un inicio de sesión del dashboard). Orden de los rechazos, ninguno de los cuales cuesta nada: 503 not_configured cuando la plataforma no tiene proveedor configurado (nunca se llama al proveedor), 409 duplicate_request para un request_key que este tenant ya usó, 429 skip_trace_cap_exceeded cuando se alcanza el tope mensual del tenant (consultas o USD) — un corte DURO: la consulta rechazada ni se realiza ni se mide. Un fallo del proveedor es 502 provider_error y no se cobra. El sujeto y los resultados nunca se almacenan. Todavía no hay línea de factura: espera a la compuerta A3.
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
request_key | string | sí | La clave de idempotencia del cliente; una consulta por clave y por tenant. |
subject | object | sí | |
subject.name | string | no | |
subject.phone | string | no | |
subject.address | string | no | |
subject.email | string | no |
json
{
"request_key": "lookup-2026-10-06-0001",
"subject": {
"name": "Jane Doe",
"address": "1 Main St, Springfield"
}
}Respuestas
200
Las coincidencias del proveedor y lo que costó la consulta.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
results | arreglo de object | sí | |
cost_usd | string | sí | Cadena decimal, USD. |
json
{
"results": [
{
"match": "fake"
}
],
"cost_usd": "0.10"
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}409
Un request_key que este tenant ya usó (duplicate_request).
422 — Unprocessable
La forma es correcta, la semántica no (regla de dominio incumplida).
json
{
"error": {
"code": "unprocessable",
"message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
}
}429
Se alcanzó el tope mensual (skip_trace_cap_exceeded).
502
Falló el proveedor (provider_error); no se cobró nada.
503
No hay proveedor configurado (not_configured).
Los límites mensuales de rastreo de contacto del tenant y el uso acumulado hasta ahora
http
GET /v1/skip-trace/capLos límites de cap son null cuando no están definidos (sin límite). usage es el mes calendario UTC hasta la fecha; las consultas fallidas no cuentan.
Respuestas
200
Límites y uso del mes hasta la fecha.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
cap | object (SkipTraceCap) | sí | |
cap.max_queries_per_month | integer,null | no | |
cap.max_usd_per_month | string,null | no | Cadena decimal en (0, 100000000), con un máximo de 4 decimales. |
usage | object | sí | |
usage.queries | integer | sí | |
usage.spent_usd | string | sí |
json
{
"cap": {
"max_queries_per_month": 100,
"max_usd_per_month": "25.0000"
},
"usage": {
"queries": 3,
"spent_usd": "0.30"
}
}401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}Establecer o borrar los límites mensuales de rastreo de contacto del tenant
http
PUT /v1/skip-trace/capUna clave dd_ o un inicio de sesión account_admin (de lo contrario 403). Reemplaza ambos límites; un límite omitido o null se borra. Los valores no válidos dan 422 y no se almacena nada.
Cuerpo de la petición (JSON, obligatorio)
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
max_queries_per_month | integer,null | no | |
max_usd_per_month | string,null | no | Cadena decimal en (0, 100000000), con un máximo de 4 decimales. |
json
{
"max_queries_per_month": 100,
"max_usd_per_month": "25"
}Respuestas
200
Los límites almacenados.
| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
cap | object (SkipTraceCap) | sí | |
cap.max_queries_per_month | integer,null | no | |
cap.max_usd_per_month | string,null | no | Cadena decimal en (0, 100000000), con un máximo de 4 decimales. |
401 — Unauthorized
Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.
json
{
"error": {
"code": "unauthorized",
"message": "invalid or revoked API key"
}
}403 — Forbidden
El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (core#2406, indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS (core#2251, adenda del ADR #280). Ningún pago lo cambia.
json
{
"error": {
"code": "forbidden",
"message": "tenant is suspended"
}
}422 — Unprocessable
La forma es correcta, la semántica no (regla de dominio incumplida).
json
{
"error": {
"code": "unprocessable",
"message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
}
}