API de Informes de Llamadas
Todo lo que muestra el Informe del Centro de Atención está disponible como JSON: métricas principales, cuadro de calidad, tendencia de cumplimiento, motivos de contacto, desempeño de agentes, llamadas ejemplares y comparación de turnos, además de las buenas prácticas extraídas de las llamadas ejemplares y una tabla de llamadas que puedes recorrer y detallar.
Los usos habituales son llevar las cifras de cumplimiento a tu propia herramienta de BI, replicar las puntuaciones por llamada en un sistema de gestión de personal, y consultar el progreso mientras se analiza un lote de subidas.
Todos los endpoints aceptan una sesión de navegador o una clave API — consulta Autenticación. Los resultados se limitan a lo que puede ver quien llama, igual que en la aplicación web: tus proyectos, los proyectos compartidos contigo y todos los proyectos de los equipos que administras.
Parámetros de consulta comunes
Sección titulada «Parámetros de consulta comunes»| Parámetro | Tipo | Descripción |
|---|---|---|
project_id | int | Limita a un solo proyecto. Omítelo para agregar todos los proyectos de llamadas que puedas ver |
team | int | Id del equipo, para acceso por equipo. Se ignora si no eres miembro de ese equipo |
start_date | date | Inicio de la ventana, YYYY-MM-DD (inclusive) |
end_date | date | Fin de la ventana, YYYY-MM-DD (inclusive, hasta las 23:59:59) |
date_range | string | Rango predefinido en lugar de fechas explícitas: mtd, last_month, last_30_days, last_90_days, ytd |
project_id y team se aplican a todos los endpoints de esta página. Los parámetros de fecha se aplican al informe, a las buenas prácticas, a la exportación en PDF y a la lista de llamadas; los endpoints de detalle, estado del análisis, preguntas personalizadas y reagrupación se limitan por proyecto y los ignoran.
date_range tiene prioridad cuando se envía junto con fechas explícitas. Sin ningún parámetro de fecha se devuelve todo el histórico, a diferencia del informe web, que usa los últimos 30 días por defecto.
Los días y los meses empiezan a medianoche en la zona horaria configurada en el perfil del usuario cuando llamas con una cookie de sesión, como en la aplicación web. Las solicitudes hechas con una clave de API usan UTC.
GET /calls/api/report/
Sección titulada «GET /calls/api/report/»El informe agregado para los proyectos y la ventana seleccionados.
Parámetro de consulta adicional:
| Parámetro | Tipo | Descripción |
|---|---|---|
exemplary_limit | int | Largo máximo de la lista exemplary_calls, de 1 a 50. Por defecto 5; un valor fuera de rango vuelve al valor por defecto |
granularity | string | Tamaño de los cubos de trend: day, week o month. Por defecto week; cualquier otro valor devuelve 400 |
agent | int | Id de agente en Uspeech, para el informe personal de ese agente |
Respuesta (200 OK) — abreviada, con los arrays largos recortados a una entrada:
{ "scope": "team", "agent_name": null, "date_range": { "start": "2026-05-01T00:00:00+00:00", "end": "2026-07-30T00:00:00+00:00", "preset": "last_90_days", "previous_start": "2026-01-31", "previous_end": "2026-04-30" }, "total_calls_all_time": 57, "unanalyzed_calls": 0, "headline": { "total_calls": 57, "analyzed_hours": 7.3, "analyzed_seconds": 26280, "average_score": 74.2, "weighted_compliance": 78.4, "scored_calls": 57, "critical_error_pct": 7.0, "negative_sentiment_pct": 32.5, "goal_reached_pct": 75.0, "calls_with_metadata": 57 }, "scorecard": [ { "criterion_id": "verification", "name": "Verificación de identidad", "section": "Apertura", "weight_pct": 15.4, "average_pct": 75.4, "previous_pct": 71.0, "delta_pct": 4.4, "critical_errors": 0, "calls": 40, "evaluated_calls": 31, "not_applicable_calls": 9 } ], "trend": [ { "period": "2026-06-29", "calls": 10, "average_score": 65.0, "negative_sentiment_pct": 30.0 } ], "contact_reasons": [ { "topic": "Disputa de facturación", "calls": 8, "volume_pct": 20.0 } ], "agents": [ { "agent": "Ana Diaz", "agent_id": 1, "calls": 26, "average_score": 72.7, "critical_error_pct": 7.7, "negative_sentiment_pct": 50.0, "goal_reached_pct": 76.9 } ], "exemplary_calls": [ { "id": 31, "file_id": 461, "file_name": "call_030.mp3", "call_datetime": "2026-07-21T10:39:32Z", "agent": "Ana Diaz", "direction": "inbound", "campaign": "Retention", "topic": "Billing dispute", "sentiment": "positive", "score_percentage": 100.0, "has_critical_error": false, "mistake_count": null, "missing_prompt_count": null, "goal_reached": true, "evaluated_score_pct": 100.0, "criteria_evaluated": 8, "criteria_total": 9, "strengths": ["Identity verification", "Adherence to the resolution script", "Objection handling and tone"] } ], "shifts": [ { "shift": "day", "total_calls": 46, "average_score": 74.8, "calls_with_metadata": 46 } ], "shift_hours": { "day_start": 8, "day_end": 20 }}Cómo leer cada sección:
| Campo | Significado |
|---|---|
scope, agent_name | team y null, o agent y el nombre del agente en un informe personal |
total_calls_all_time | Llamadas dentro del alcance antes del filtro de fechas. Si headline.total_calls es 0 y este no lo es, tu ventana está mal elegida |
unanalyzed_calls | Llamadas transcritas de la ventana que ningún análisis ha cubierto todavía, normalmente subidas con el análisis automático desactivado. No forman parte de ninguna otra cifra. Las llamadas en cola para el análisis automático no se cuentan |
headline | Resumen de volumen y calidad de la ventana. average_score es la media simple de las puntuaciones; weighted_compliance son los puntos obtenidos sobre los posibles, para que las rúbricas largas no se diluyan. analyzed_hours se redondea a la décima de hora; analyzed_seconds es la duración exacta del audio |
scorecard | Una fila por criterio de la rúbrica. previous_pct y delta_pct comparan con el período anterior de date_range.previous_start–previous_end: el mismo número de meses completos anteriores cuando la ventana son meses completos del calendario, los mismos días del mes anterior cuando empieza el día 1 dentro de un mes y, en otro caso, una ventana de la misma duración justo antes. Son null para una ventana sin límites y para un criterio sin puntuaciones en el período anterior. not_applicable_calls cuenta las llamadas en las que el criterio se omitió y recibió sus puntos completos; esas llamadas están incluidas en average_pct, así que un criterio con un not_applicable_calls alto se lee alto porque rara vez aplicó. evaluated_calls + not_applicable_calls es menor que calls cuando la ventana incluye llamadas analizadas antes de que Uspeech registrara la aplicabilidad |
trend | Cubos del tamaño de granularity; period es el primer día de cada uno, el lunes en el caso de las semanas |
contact_reasons | Motivos principales por volumen. Una fila final con topic vacío y un recuento other_topics es el grupo «todo lo demás» |
agents | Resumen por agente. agent_id es el id interno del agente en Uspeech —el que se pasa al filtro agent del explorador— no tu propio agent_id de los metadatos |
exemplary_calls | Las mejores llamadas de la ventana, de mejor a peor: la sección Llamadas ejemplares del informe. Cada entrada es una fila del explorador más evaluated_score_pct (la puntuación en los criterios que aplicaron), criteria_evaluated de criteria_total criterios aplicados y hasta tres strengths: los criterios de mayor peso cumplidos por completo. Como máximo exemplary_limit llamadas y dos por agente; la lista nunca se completa con relleno, así que puede ser más corta o estar vacía |
shifts | La misma forma que headline más shift (day / night). Solo se clasifican las llamadas con fecha y hora reales |
shift_hours | La franja de turno día utilizada, según la configuración del proyecto |
Los campos porcentuales son null en lugar de 0 cuando no había nada que medir en la ventana: ninguna llamada puntuada, ningún sentimiento, ningún resultado conocido.
goal_reached_pct y todos los campos goal_reached provienen del criterio objetivo de la llamada de la rúbrica cuando lo tiene, y del Análisis de Llamadas en caso contrario.
Ejemplo:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/report/?project_id=312&date_range=last_30_days"import osimport requests
BASE_URL = "https://app.uspeech.io"HEADERS = {"Authorization": f"Api-Key {os.environ['USPEECH_KEY']}"}
report = requests.get( f"{BASE_URL}/calls/api/report/", headers=HEADERS, params={"project_id": 312, "date_range": "last_30_days"}, timeout=60,).json()print(report["headline"])const BASE_URL = 'https://app.uspeech.io';const HEADERS = { Authorization: `Api-Key ${process.env.USPEECH_KEY}` };
const params = new URLSearchParams({ project_id: '312', date_range: 'last_30_days' });const report = await fetch(`${BASE_URL}/calls/api/report/?${params}`, { headers: HEADERS,}).then((r) => r.json());console.log(report.headline);Informes personales de un agente
Sección titulada «Informes personales de un agente»Agrega agent al informe o al PDF para obtener el informe personal de un agente en lugar del informe del equipo: el mismo que ve un agente con su propio acceso. Sirve para comprobar lo que ve un agente o para enviarle su PDF.
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/report/?agent=59&date_range=last_30_days"agent es el id interno de Uspeech, el de agents[].agent_id en el informe del equipo. Todas las cifras cubren entonces solo las llamadas de ese agente, y la respuesta cambia en estos campos:
| Campo | Informe del equipo | Informe personal |
|---|---|---|
scope | team | agent |
agent_name | null | El nombre del agente |
agents | Resumen por agente | Vacío |
unanalyzed_calls | Recuento de la ventana | 0 |
El PDF tiene su propia narrativa, dirigida al agente a partir de sus propias cifras, y omite la tabla de agentes y las buenas prácticas.
| Estado | Cuándo |
|---|---|
400 | agent no es un número |
404 | El agente no tiene llamadas en los proyectos que puedes ver |
GET /calls/api/calls/
Sección titulada «GET /calls/api/calls/»Una tabla paginada y filtrable de las llamadas analizadas, que abarca todos los lotes de análisis de los proyectos seleccionados.
Parámetros adicionales:
| Parámetro | Tipo | Descripción |
|---|---|---|
agent | int / none | Id de agente en Uspeech (el agents[].agent_id del informe), o none para llamadas sin agente |
sentiment | string | positive, neutral o negative |
direction | string | inbound u outbound |
critical | bool | true devuelve solo las llamadas con error crítico |
exemplary | bool | true devuelve solo las llamadas que alcanzan el nivel de llamada ejemplar, de mejor a peor, e ignora ordering. A diferencia de exemplary_calls del informe, no tiene tope por agente ni por exemplary_limit |
search | string | Busca en nombre de archivo, tema, motivo de contacto, número del cliente y campaña |
ordering | string | call_datetime, score_percentage, mistake_count o agent__name, con - opcional delante. Por defecto -call_datetime |
page | int | Número de página; el tamaño de página es 25 |
Los valores desconocidos de sentiment, direction y ordering se ignoran en lugar de rechazarse. Las llamadas sin valor en el campo de ordenamiento —por ejemplo, las llamadas sin puntuación al ordenar por score_percentage— siempre van al final, en ambas direcciones.
Respuesta (200 OK):
{ "count": 57, "next": "https://app.uspeech.io/calls/api/calls/?page=2", "previous": null, "results": [ { "id": 28, "file_id": 458, "file_name": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "agent": "Luis Gomez", "direction": "inbound", "campaign": "Retencion", "topic": "Cambio de dirección", "sentiment": "positive", "score_percentage": 66.3, "has_critical_error": false, "mistake_count": 0, "missing_prompt_count": 1, "goal_reached": true } ]}goal_reached es true, false o null cuando se desconoce. id es el id de la llamada para el endpoint de detalle; file_id es el archivo subido, que es lo que usan los endpoints de Subir Grabaciones y Metadatos de llamadas. topic es el motivo de contacto codificado una vez agrupado, y el tema extraído en bruto antes de eso.
Ejemplo — las llamadas entrantes peor puntuadas del mes:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/calls/?date_range=mtd&direction=inbound&ordering=score_percentage"calls = requests.get( f"{BASE_URL}/calls/api/calls/", headers=HEADERS, params={ "date_range": "mtd", "direction": "inbound", "ordering": "score_percentage", }, timeout=60,).json()for call in calls["results"]: print(call["file"], call["score_percentage"])const params = new URLSearchParams({ date_range: 'mtd', direction: 'inbound', ordering: 'score_percentage',});const calls = await fetch(`${BASE_URL}/calls/api/calls/?${params}`, { headers: HEADERS,}).then((r) => r.json());for (const call of calls.results) console.log(call.file, call.score_percentage);GET /calls/api/calls/{id}/
Sección titulada «GET /calls/api/calls/{id}/»Todo lo que se sabe de una llamada, combinado entre tipos de análisis.
Respuesta (200 OK):
{ "record": { "id": 28, "file_id": 458, "file_name": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "call_datetime_source": "manifest", "agent": "Luis Gomez", "direction": "inbound", "campaign": "Retencion", "caller_number": "+34600111222", "ended_by": "customer", "topic": "Cambio de dirección", "sentiment": "positive", "score_percentage": 66.3, "total_points": 19.89, "max_possible_points": 30.0, "has_critical_error": false, "mistake_count": 0, "missing_prompt_count": 1, "goal_reached": true }, "copc": { "…": "puntuaciones por criterio, justificaciones y citas" }, "no_protocol": { "…": "errores detectados y preguntas omitidas" }, "custom_questions": { "…": "respuestas a las preguntas personalizadas del proyecto" }}record es la fila del explorador más el número del cliente, quién colgó primero (ended_by: customer, agent o "" si no se sabe), los puntos en bruto y call_datetime_source. Las otras tres claves contienen el texto libre de cada tipo de análisis y son null cuando ese análisis no se ha ejecutado para la llamada. Su estructura interna sigue el formato de resultados del análisis y conviene inspeccionarla sobre una llamada real.
Cada entrada de copc.criterion_scores lleva un campo applicability, con valor "evaluated" o "not_applicable":
{ "criterion_id": "closing_summary", "justification": "El cliente colgó antes de que la agente pudiera resumir el acuerdo.", "quote": "[04:12] Cliente: Tengo que irme, hasta luego.", "applicability": "not_applicable", "score": 15, "max_points": 15, "is_critical_error": false}Un criterio que no aplicó recibe sus max_points completos, así que por score es indistinguible de una puntuación perfecta: applicability es el único campo que los separa. Un paso de cierre eximido porque el cliente colgó antes de la despedida del agente también lleva "override": "customer_hangup"; consulta Pasos de cierre cuando el cliente cuelga. Si calculas tus propios promedios por criterio, filtra antes las filas not_applicable; de lo contrario un criterio condicional se lee alto simplemente porque rara vez aplicó. Consulta Cómo Funciona la Puntuación.
Errores: 404 cuando la llamada no existe o pertenece a un proyecto que no puedes ver.
GET /calls/api/analysis-status/
Sección titulada «GET /calls/api/analysis-status/»Progreso del análisis automático de los proyectos seleccionados, pensado para consultarlo periódicamente mientras se procesan las subidas.
Respuesta (200 OK):
{ "analysis_status": { "calls_analysis_copc": { "completed": 54, "queued": 3 }, "calls_analysis_no_protocol": { "completed": 57 } }, "analyzed_calls": 57, "duplicate_uploads": 2, "in_progress": true, "reclustering": false, "last_analyzed_at": "2026-07-29T02:50:11.127124+00:00"}| Campo | Significado |
|---|---|
analysis_status | Por tipo de análisis, el número de llamadas en cada estado (queued, processing, completed, failed) |
analyzed_calls | Llamadas con resultados, sin aplicar filtro de fechas. Una llamada que solo tiene metadatos no se cuenta hasta que se analiza |
duplicate_uploads | Archivos subidos con un nombre que el proyecto ya tenía. Son la misma llamada, así que un registro sustituye al anterior — por eso el número de archivos puede superar al de llamadas |
in_progress | true mientras haya análisis en cola o en curso — consulta hasta que sea false y vuelve a pedir el informe |
reclustering | true mientras se reagrupan los motivos de contacto |
last_analyzed_at | Marca de tiempo del resultado más reciente, o null |
while :; do resp=$(curl -sS "https://app.uspeech.io/calls/api/analysis-status/?project_id=312" \ -H "Authorization: Api-Key $USPEECH_KEY") [ "$(echo "$resp" | jq -r .in_progress)" = "false" ] && break sleep 30doneimport time
while True: status = requests.get( f"{BASE_URL}/calls/api/analysis-status/", headers=HEADERS, params={"project_id": 312}, timeout=30, ).json() if not status["in_progress"]: break time.sleep(30)const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
while (true) { const status = await fetch( `${BASE_URL}/calls/api/analysis-status/?project_id=312`, { headers: HEADERS }, ).then((r) => r.json()); if (!status.in_progress) break; await sleep(30_000);}Consulta Subir Grabaciones para el recorrido completo de subida y sondeo.
GET /calls/api/custom-questions/
Sección titulada «GET /calls/api/custom-questions/»Respuestas por llamada a las preguntas personalizadas del proyecto, reunidas de todos los lotes.
Respuesta (200 OK):
{ "questions": ["¿Se ofreció una devolución de llamada?", "¿Se mencionó el descuento?"], "calls": [ { "call_analysis_id": 904, "file": "call_027.mp3", "call_datetime": "2026-07-28T09:15:00Z", "agent": "Luis Gomez", "answers": { "¿Se ofreció una devolución de llamada?": { "answer": "Sí — el agente ofreció llamar el martes.", "quotes": 2 } } } ], "count": 12}questions es la unión de las preguntas encontradas en las llamadas devueltas, en orden de aparición: úsala como lista de columnas. Una llamada analizada con un conjunto de preguntas anterior simplemente no tiene entrada para las nuevas. quotes cuenta las citas de la transcripción que respaldan la respuesta.
Los proyectos sin preguntas personalizadas devuelven arrays vacíos y count: 0.
POST /calls/api/recluster/
Sección titulada «POST /calls/api/recluster/»Reagrupa bajo demanda los motivos de contacto abiertos, la misma acción que Actualizar motivos de contacto en el informe.
La reagrupación se encola para todos los proyectos abiertos accesibles; los proyectos con códigos predefinidos congelados clasifican cada llamada al llegar y se omiten, por lo que nunca aparecen en la respuesta. El trabajo se ejecuta en segundo plano: consulta reclustering en analysis-status para saber cuándo termina.
Respuesta (202 Accepted):
{ "reclustering": [312, 318], "count": 2 }reclustering lista los ids de proyecto encolados. Las peticiones solapadas se descartan, así que llamar a este endpoint mientras ya hay una reagrupación en curso es inofensivo.
Ejemplo:
curl -X POST -H "Authorization: Api-Key $USPEECH_KEY" \ "https://app.uspeech.io/calls/api/recluster/?project_id=312"response = requests.post( f"{BASE_URL}/calls/api/recluster/", headers=HEADERS, params={"project_id": 312}, timeout=30,)response.raise_for_status()const response = await fetch( `${BASE_URL}/calls/api/recluster/?project_id=312`, { method: 'POST', headers: HEADERS },);if (!response.ok) throw new Error(await response.text());GET /calls/api/report/best-practices/
Sección titulada «GET /calls/api/report/best-practices/»Las buenas prácticas extraídas de las llamadas ejemplares del informe: de tres a cinco conductas que otros agentes deberían imitar, cada una con una cita de la llamada de la que proviene.
Acepta los parámetros de consulta compartidos y exemplary_limit, igual que el informe, y trabaja sobre las mismas llamadas ejemplares que el informe devuelve con ellos. La generación tarda unos minutos, así que nunca ocurre en un GET: la inicias con POST y consultas el estado.
Respuesta (200 OK):
{ "status": "ready", "practices": [ { "title": "Confirmar la identidad del cliente antes de hablar de la cuenta", "description": "El agente pide el nombre completo y el número de guía antes de dar cualquier dato del envío. Protege al cliente y evita hablar con la persona equivocada.", "quote": "Speaker Ana: ¿Me indica su nombre completo, por favor?\nSpeaker 2: Laura Medina.\nSpeaker Ana: Gracias. ¿Y el número de guía?", "turns": [ { "speaker": "Ana", "text": "¿Me indica su nombre completo, por favor?" }, { "speaker": "2", "text": "Laura Medina." }, { "speaker": "Ana", "text": "Gracias. ¿Y el número de guía?" } ], "call_id": 31, "file_name": "call_030.mp3", "agent": "Ana Diaz", "call_datetime": "2026-07-21T10:39:32+00:00" } ]}status | Significado |
|---|---|
none | Todavía no se generó nada para estas llamadas. Envía POST para comenzar |
pending | La generación está en curso. Consulta cada pocos segundos |
ready | practices contiene el resultado |
failed | La generación falló, o lleva más de unos 25 minutos pendiente. Envía POST de nuevo para reintentar |
unavailable | Ninguna llamada de la ventana alcanza el nivel de llamada ejemplar, así que no hay de dónde aprender |
practices es null salvo que status sea ready. quote se copia palabra por palabra de la llamada; turns la divide en turnos de diálogo. speaker es el nombre que da la transcripción, o un número cuando no se pudo distinguir a los hablantes. call_id es el id para el endpoint de detalle de llamada.
El resultado se guarda por conjunto de llamadas ejemplares y por idioma. Cuando la lista cambia —otra ventana, otro exemplary_limit o una llamada reanalizada— el estado vuelve a none para el nuevo conjunto. Las prácticas se redactan en inglés salvo que envíes Accept-Language: es; las citas se mantienen en el idioma de la llamada.
POST /calls/api/report/best-practices/
Sección titulada «POST /calls/api/report/best-practices/»Inicia la generación de buenas prácticas para las mismas llamadas. Sin cuerpo en la petición.
Respuesta: 202 Accepted con {"status": "pending", "practices": null} cuando la generación comienza. Si ya existe un resultado o ya se está generando, no se inicia nada nuevo y recibes 200 OK con el estado actual; una ventana unavailable también devuelve 200 OK. Un resultado failed se reintenta.
URL="https://app.uspeech.io/calls/api/report/best-practices/?project_id=312&date_range=last_30_days"curl -sS -X POST -H "Authorization: Api-Key $USPEECH_KEY" -H "Accept-Language: es" "$URL"while :; do resp=$(curl -sS -H "Authorization: Api-Key $USPEECH_KEY" -H "Accept-Language: es" "$URL") [ "$(echo "$resp" | jq -r .status)" != "pending" ] && break sleep 15doneecho "$resp" | jq '.practices[].title'import time
params = {"project_id": 312, "date_range": "last_30_days"}url = f"{BASE_URL}/calls/api/report/best-practices/"headers = {**HEADERS, "Accept-Language": "es"}state = requests.post(url, headers=headers, params=params, timeout=30).json()while state["status"] == "pending": time.sleep(15) state = requests.get(url, headers=headers, params=params, timeout=30).json()for practice in state["practices"] or []: print(practice["title"], "—", practice["agent"])const params = new URLSearchParams({ project_id: '312', date_range: 'last_30_days' });const url = `${BASE_URL}/calls/api/report/best-practices/?${params}`;const headers = { ...HEADERS, 'Accept-Language': 'es' };let state = await fetch(url, { method: 'POST', headers }).then((r) => r.json());while (state.status === 'pending') { await new Promise((resolve) => setTimeout(resolve, 15_000)); state = await fetch(url, { headers }).then((r) => r.json());}for (const practice of state.practices ?? []) console.log(practice.title, '—', practice.agent);GET /calls/api/report/pdf/
Sección titulada «GET /calls/api/report/pdf/»El mismo PDF listo para el cliente que genera el botón Exportar PDF del informe, con el resumen ejecutivo escrito por IA, para los filtros actuales.
Acepta exemplary_limit igual que el informe, y agent para el PDF personal de un agente; su sección de llamadas ejemplares lista las mismas llamadas. Las buenas prácticas se incluyen solo si ya se generaron para esas llamadas y ese idioma: el PDF nunca las genera, así que si las quieres en el documento envía primero un POST al endpoint de buenas prácticas y espera a ready.
Respuesta (200 OK): application/pdf como descarga de archivo. La generación es síncrona e incluye una llamada al modelo para las secciones narrativas, así que tarda bastante más que el endpoint JSON; si la narrativa falla, el PDF se devuelve igualmente con sus tablas y un aviso.
El documento se redacta en inglés por defecto. Envía Accept-Language: es para obtenerlo en español: una petición autenticada con clave API no tiene sesión de navegador, por lo que el idioma del perfil del usuario no se aplica aquí.
Ejemplo:
curl -H "Authorization: Api-Key $USPEECH_KEY" \ -o informe_llamadas.pdf \ "https://app.uspeech.io/calls/api/report/pdf/?project_id=312&date_range=last_month"response = requests.get( f"{BASE_URL}/calls/api/report/pdf/", headers=HEADERS, params={"project_id": 312, "date_range": "last_month"}, timeout=600,)response.raise_for_status()with open("informe_llamadas.pdf", "wb") as fh: fh.write(response.content)import { writeFile } from 'node:fs/promises';
const params = new URLSearchParams({ project_id: '312', date_range: 'last_month' });const response = await fetch(`${BASE_URL}/calls/api/report/pdf/?${params}`, { headers: HEADERS,});if (!response.ok) throw new Error(await response.text());await writeFile('informe_llamadas.pdf', Buffer.from(await response.arrayBuffer()));Errores
Sección titulada «Errores»| Estado | Cuándo |
|---|---|
401 / 403 | Clave API ausente, mal formada, revocada o de un usuario inactivo |
404 | En los endpoints de informe, buenas prácticas y PDF, cuando project_id apunta a un proyecto que no existe o que no puedes ver; en el de detalle, lo mismo con la llamada |
Ojo con la asimetría: un project_id inalcanzable da 404 en el informe, en las buenas prácticas y en el PDF, pero en los endpoints de lista, estado, preguntas personalizadas y reagrupación simplemente no coincide con nada y obtienes un resultado vacío y a cero. Un resultado vacío nunca es un error en sí mismo: un proyecto que puedes ver sin llamadas analizadas se ve igual. Consulta Códigos de estado y errores para la estructura general de los errores.