Colección de Postman

English version: Postman collection.

Una colección de Postman lista para importar que cubre la superficie de plano de control /v1: 27 carpetas, 163 peticiones, más un entorno con las dos variables que tienes que rellenar.

• Descargar la colección (dialer-core.postman_collection.json)
• Descargar el entorno (dialer-public.postman_environment.json)

Importar y ejecutar

1. En Postman, Import → suelta los dos ficheros.
2. Selecciona el entorno Dialer Digital — public en el selector de arriba a la derecha.
3. Fija estas dos variables:

Variable	Qué es
baseUrl	El ingress delante de core. Sale como https://api.usa.dialerdigital.com, el servidor de despliegue declarado en la especificación OpenAPI: apúntalo a tu propia celda si la tuya difiere.
api_token	Sale vacío a propósito. Pega tu propia clave; ver abajo.

La colección se autentica a nivel de colección con Bearer , de modo que cada petición lo hereda: no hay autenticación por petición que configurar.

Qué token va en api_token

Las claves de /v1 son del ámbito del tenant y viven en el carril dd_: emite una con POST /v1/api_keys y copia el token en claro, que se muestra una vez y nunca más. Las reglas completas (los tres carriles (dd_, ddu_, ddw_), qué puede alcanzar cada uno y cómo se deriva el tenant de la clave) están en Autenticación.

Dos carriles que puedes ver en otras partes de la documentación no pertenecen a esta variable: ddu_ (sesiones de usuario del dashboard) y ddw_ (widget). La colección ejercita la API del tenant.

El entorno publicado no lleva credencial

api_token está vacío en el fichero que descargas, y no es un descuido: un token enviado en un artefacto público es un token que alguien se queda. Rellénalo en local; Postman lo guarda en tu propio entorno, no en el fichero.

De dónde sale esto y qué lo mantiene honesto

La colección está vendorizada, no se escribe aquí. Su fuente de verdad es postman/dialer-core.postman_collection.json en DialerDigital/integration-tests, donde además hace de harness que ejercita un stack vivo. public/postman/SOURCE.json registra el commit exacto de integration-tests del que salió cada copia publicada.

Cinco cosas cambian por el camino, y el script falla en lugar de publicar si alguna deja de coincidir: la comprobación es sobre la salida, no sobre si la reescritura se disparó:

• baseUrl pasa del harness local (http://127.0.0.1:4000) al marcador de despliegue, y las peticiones que el harness envía a su segundo listener (publicBase, http://127.0.0.1:4001, las dos rutas click-to-call /v1/public/*) también apuntan a baseUrl, de modo que la única variable que fijas las mueve todas;
• la descripción de la colección deja de nombrar el token de demostración que siembra el harness local;
• el ejemplo de registro del proveedor de SMS apunta a un nombre reservado para documentación en lugar del mock del harness, y sale con un webhook_secret vacío. Ambos pertenecían al harness (un puntero a un mock local y el secreto que siembra el harness) y ninguno pertenece a una descarga pública. La API rechazaría de todos modos ese loopback: base_url es entrada del tenant a la que el plano de control luego firma peticiones, así que se comprueba contra una guarda SSRF (ver la descripción del campo en el openapi/dialer-v1.yaml vendorizado). Quitarlo aquí trata de lo que publicamos, no de lo que la API acepta;
• se elimina la petición de buzón sumidero exclusiva del harness, junto con la variable que la alimentaba. Leía un buzón servido por el stack local, así que nunca hubo nada que pudiera alcanzar desde fuera. Las dos peticiones password-reset/confirm esperan por tanto que pegues en reset_token el token del correo que realmente recibiste;
• las dos escrituras de administrador de plataforma de la secuencia de MFA forzada también se eliminan, junto con la variable de host admin_base y el admin_api_token sembrado por el harness que las alimentaban. Llegan al mismo core que baseUrl pero con el bearer que la plataforma se reserva, así que solo funcionan dentro del harness. El resto de esa secuencia no necesita ese bearer y se queda, pero parte del estado que creó la primera escritura: el POST /v1/auth/login que la abre espera mfa_required con purpose: "enroll", que solo devuelve un tenant donde la plataforma haya encendido MFA forzada, y las peticiones de inscripción y confirmación posteriores leen el mfa_enroll_challenge que fija ese login. Ejecuta ese tramo contra un tenant así, o espera que sus pruebas fallen. Dejar el par fue lo que una lista de descarte de un solo nombre dejó pasar; la comprobación que cierra por seguridad cazó el segundo host loopback y no publicó nada (docs#313).

Refréscala con un checkout hermano de integration-tests:

npm run docs:sync-postman              # rewrite the published copy
node scripts/sync-postman.mjs --check  # report drift without rewriting

--check avisa por defecto y falla en serio con POSTMAN_SYNC_STRICT=1. El propio sanitizador cierra por seguridad: si su reescritura deja de coincidir con la fuente, aborta en lugar de publicar, de modo que un sanitizador que dejó de sanitizar sin avisar no pueda salir.

--check también acepta --anchor=pinned|moving, que indica a qué apunta el checkout hermano y por tanto qué es comparable. Por defecto es moving, la respuesta correcta para el comando de arriba, donde tu checkout de integration-tests está donde lo dejaste. El CI lo pasa de forma explícita, elegido según el evento: en pull_request/push el checkout está en el commit que declara public/postman/SOURCE.json, así que --anchor=pinned comprueba además que el checkout de verdad esté en ese commit y compara SOURCE.json por completo; en schedule el checkout está en la rama por defecto del repo fuente, donde commit se mueve con cada commit ajeno, así que --anchor=moving deja fuera ese único campo.

En schedule hay una entrada más, y es lo que evita que el nocturno dé falsas alarmas. La misma ejecución tiene también el job contract-refresh, que abre (o actualiza) un pull request con la copia refrescada siempre que la fuente se haya movido: así que un desvío que ve el paso de frescura es muy a menudo un desvío cuyo arreglo ya está abierto, esperando revisión. Los dos jobs no tienen orden entre sí, así que el paso primero espera a que termine contract-refresh, y luego toma --refresh-prs=<json>: la lista de pull requests abiertos de este repo con el commit que cada uno declara en su propio public/postman/SOURCE.json. Si uno de ellos declara exactamente el commit contra el que se compara, el desvío es conocido: el paso imprime un ::notice:: que nombra ese pull request, escribe en el resumen del job qué consideró y por qué, y se queda en verde. Sin tal pull request, el paso está en rojo exactamente como antes: ese rojo es de alguien, o de un job de sincronización que no corrió o de un commit fuente que nadie ha traído aún. La coincidencia es deliberadamente estrecha: un pull request abierto y el commit exacto; uno cerrado, o que vendoriza un commit más antiguo, no silencia nada, y una lista que el paso no puede leer tampoco. La bandera se rechaza con --anchor=pinned: en pull_request/push un desvío es un fallo de integridad y ningún pull request abierto lo excusa.

Alineación con el contrato /v1

Las peticiones siguen la especificación OpenAPI de core: la misma que este sitio renderiza como Referencia de la API y vendoriza en openapi/dialer-v1.yaml. La versión vendorizada es el spec_version que registra openapi/SOURCE.json, junto al tag y el commit de core del que la copió scripts/sync-openapi.mjs. En integration-tests, una puerta de desvío (.ci/qa/check_openapi_postman_drift.py) evita que la colección y la especificación se separen.

Una diferencia que conviene conocer antes de buscarla: la colección incluye GET /healthz, la sonda de vida sin autenticación, y la especificación no la describe: la especificación cubre solo /v1. Es un endpoint real; simplemente no tiene esquema contra el que comprobarlo.

Ver también

• API REST: la narrativa escrita a mano de la superficie
• Referencia de la API (en inglés): generada desde la especificación en cada compilación
• Autenticación: los carriles, completos