POST
https://api.nexscope.ai/api/skill-api/v1/skills/amazon-ads-reporting/runEjecutar esta API
Envía una solicitud JSON para ejecutar esta API y recibir los datos de respuesta documentados.
Endpoint
| Método | POST |
| Ruta | https://api.nexscope.ai/api/skill-api/v1/skills/amazon-ads-reporting/run |
| Autenticación | Bearer API key |
| Content-Type | application/json |
Guía de operaciones de Amazon Ads
Este endpoint admite tres etapas de informes con un connectionId que te pertenezca: omite reportId y documentToken para crear un informe, proporciona reportId para consultarlo o un documentToken emitido por el backend para descargar un informe completado. La creación requiere startDate y endDate, además de una configuration completa o el tipo de informe, producto publicitario, agrupación y columnas documentados.
Consulta el informe existente en lugar de crear otra solicitud mientras esté pendiente. Los tokens de descarga son opacos; no se devuelven las URL ni las credenciales del proveedor.
Parámetros de la solicitud
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
connectionId | integer | obligatorio | Propiedad de Amazon Ads ID de conexión. Ejemplo: 123 |
reportId | string | opcional | ID de informe existente; cuando presente el API encuesta ese informe. Ejemplo: report-id |
reportTypeId | string | opcional | Tipo de informe requerido por un nuevo informe a menos que la configuración lo suministre. Ejemplo: spCampaigns |
adProduct | string | opcional | Producto de anuncio requerido por un nuevo informe a menos que la configuración lo suministre. Ejemplo: SPONSORED_PRODUCTS |
groupBy | array | opcional | Informar de campos de agrupación. Ejemplo: [
"campaign"
] |
columns | array | opcional | Columnas de informes solicitadas. Ejemplo: [
"campaignId",
"impressions",
"clicks"
] |
name | string | opcional | Nombre opcional del informe. Ejemplo: Campaign report |
startDate | string | opcional | Fecha de inicio del informe inclusivo para un nuevo informe. Ejemplo: 2026-07-01 |
endDate | string | opcional | Fecha de finalización del informe inclusivo para un nuevo informe. Ejemplo: 2026-07-31 |
timeUnit | string | opcional | Unidad de tiempo de informe opcional. Ejemplo: DAILY |
format | string | opcional | Formato opcional del informe. Ejemplo: GZIP_JSON |
filters | array | opcional | Filtros opcionales de informes. Ejemplo: [] |
configuration | object | opcional | Configuración completa de informes de Amazon Ads; puede reemplazar reportTypeId/adProduct/groupBy/columns. Ejemplo: {} |
documentToken | string | opcional | Token de motor para descargar un informe completo. Ejemplo: opaque-document-token |
Respuesta de ejemplo
Estructura de respuesta de la plataforma. code 0 indica éxito o aceptación; data contiene el resultado de negocio.
{
"code": 0,
"cost": "-1",
"data": {
"content": {},
"contentType": "application/json",
"documentToken": "opaque-document-token",
"reportId": "report-id",
"status": "PENDING"
},
"msg": null,
"time": "2026-01-01 00:00:00",
"traceId": null,
"ts": "0"
}Campos de respuesta
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
code | integer | obligatorio | 0 significa aceptado o exitoso; no cero es un error de plataforma. |
cost | string | obligatorio | Se pasó milisegundos, nunca créditos; -1 peticiones externas de la web. |
data | any | obligatorio | Valor de Data usado por esta operación de API. |
msg | string | null | obligatorio | Valor de Msg usado por esta operación de API. |
time | string | obligatorio | Hora local del servidor: aaaa-mm-dd HH:mm:ss. |
traceId | string | null | obligatorio | Valor de Trace id usado por esta operación de API. |
ts | string | obligatorio | Epoch milisegundos. |
Opción 1 de cualquier alternativa
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
data | object | obligatorio | Valor de Data usado por esta operación de API. |
data.content | object | opcional | El contenido del informe descargado cuando está disponible. Ejemplo: {} |
data.contentType | string | opcional | Tipo de contenido del informe descargado. Ejemplo: application/json |
data.costTime | integer | opcional | Tiempo de ejecución comunicado por el proveedor de aguas arriba. Ejemplo: null |
data.costToken | integer | opcional | Coste de la señal comunicado por el proveedor de aguas arriba. Ejemplo: null |
data.dataSnapshotMonth | string | opcional | Mes de instantánea de datos devuelto por el proveedor de aguas arriba. Ejemplo: null |
data.documentToken | string | opcional | Token opaco seguro utilizado para descargar. Ejemplo: opaque-document-token |
data.page | integer | opcional | Página actual devuelta por el proveedor de aguas arriba. Ejemplo: null |
data.pageItemCount | integer | opcional | El artículo cuenta con la página actual devuelta por el proveedor de aguas arriba. Ejemplo: null |
data.pageSize | integer | opcional | Tamaño de página devuelto por el proveedor de aguas arriba. Ejemplo: null |
data.reportId | string | opcional | Identificación del proveedor. Ejemplo: report-id |
data.sourceTool | string | opcional | Nombre de la herramienta de fuente específica del proveedor. Ejemplo: null |
data.sourceType | string | opcional | Tipo de plataforma de origen específico para el proveedor. Ejemplo: null |
data.status | string | opcional | Informe de situación. Ejemplo: PENDING |
data.title | string | opcional | Título de respuesta específico del proveedor. Ejemplo: null |
data.totalPage | integer | opcional | El total de páginas devueltas por el proveedor de aguas arriba. Ejemplo: null |
data.type | string | opcional | Rendición específica del proveedor o tipo de carga útil. Ejemplo: null |
Opción 2 de cualquier alternativa
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
data | null | obligatorio | Valor de Data usado por esta operación de API. |
Respuestas
| Código | Descripción |
|---|---|
| 200 | Respuesta HTTP predeterminada tanto para el éxito como para muchos errores de negocio. Solo el código JSON externo 0 indica éxito o aceptación asíncrona; consulta data para obtener el resultado. |
| 429 | Límite de admisión de ejecuciones; respeta Retry-After cuando esté presente. |
| 503 | La admisión de ejecuciones no está disponible temporalmente; respeta Retry-After cuando esté presente. |
| Opcional | X-Nexscope-Http-Status: semantic asigna estados HTTP a los errores de negocio gestionados por el controlador en las rutas de ejecución y tareas. Los fallos previos a la autenticación, como la ausencia de una clave API (code 11209), pueden seguir devolviendo HTTP 200 antes de esta asignación. Comprueba siempre el código JSON externo; las solicitudes malformadas y los fallos de infraestructura también pueden devolver respuestas HTTP distintas de 200. |
Fuente de datos, vigencia y limitaciones
La fuente, la vigencia, la cobertura, los límites de frecuencia y las notas de estimación no se especifican en esta definición de API salvo que aparezcan en la documentación de campos de solicitud o respuesta anterior. No supongas datos oficiales del mercado ni actualización en tiempo real cuando no estén documentados explícitamente.