---
sidebar:
  order: 1
title: "API HTTP"
description: "Autentícate, descubre herramientas y confirma cambios mediante la API HTTP existente."
---

Envía las solicitudes al origen de Influence de confianza, como `https://influence.so`. El dominio de documentación no acepta solicitudes de la API del producto. Usa las rutas exactas siguientes, sin parámetros de consulta.

## Crea una clave con los permisos necesarios

En los [ajustes de Influence](https://influence.so/sign-in?next=%2Fapp%2Fsettings%2Faccount%23settings-developer), abre Aplicaciones y automatizaciones → Claves de API. Elige los permisos y una fecha de caducidad. La clave se muestra una sola vez: guárdala en tu almacén de secretos como `PUBLISH_API_TOKEN`. Envíala en `Authorization: Bearer …`, nunca en una URL, el cuerpo de una solicitud o un chat. Revócala cuando dejes de necesitarla.

## Descubre herramientas y consulta datos

Configura `PUBLISH_API_URL` con el origen de confianza. Los ejemplos suponen que el proceso ya tiene `PUBLISH_API_TOKEN`. `accountList` requiere `integrations:read`; usa sus campos de paginación para consultar las páginas siguientes.

```sh
export PUBLISH_API_URL="https://influence.so"
curl "$PUBLISH_API_URL/api/v1/tools" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN"

curl "$PUBLISH_API_URL/api/v1/tools/accountList/call" \
  -H "Authorization: Bearer $PUBLISH_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"input":{}}'
```

## Rutas de las solicitudes

| Método | Ruta | Finalidad |
| --- | --- | --- |
| `GET` | `/api/v1/tools` | Lista las herramientas disponibles para esta credencial. |
| `POST` | `/api/v1/tools/{tool}/call` | Ejecuta una herramienta de solo lectura. |
| `POST` | `/api/v1/tools/{tool}/prepare` | Prepara un cambio exacto sin ejecutarlo. |
| `POST` | `/api/v1/tools/{tool}/confirm` | Confirma el cambio preparado. |
| `POST` | `/api/v1/media/import` | Confirma una carga preparada de una imagen binaria pequeña. |

Las solicitudes JSON usan `Content-Type: application/json` y un cuerpo que contiene solo `input`: `{"input":{…}}`. Consulta el esquema de entrada de cada herramienta en el catálogo actual.

## Prepara y confirma cambios

1. Envía la entrada exacta a `/prepare`. La respuesta correcta incluye `status: "confirmation_required"`, `confirmationCapability`, `expiresAt`, `inputDigest` y, opcionalmente, `summary`.
2. Antes de que caduque, envía la misma entrada a `/confirm`. Incluye el valor recibido en `X-Publish-Confirmation` y una nueva clave generada por tu cliente en `Idempotency-Key`.
3. Conserva juntos la entrada, el valor de confirmación y la clave. Si la confirmación se interrumpe o su resultado es incierto, reutiliza los tres para esa misma solicitud. No prepares otra operación para recuperar un resultado incierto.

La clave de idempotencia contiene entre 16 y 200 caracteres de `A–Z`, `a–z`, `0–9`, `.`, `_`, `:` y `-`. El valor de confirmación es un secreto opaco. Enviar una clave a `/call` o `/prepare` no reserva un cambio confirmado.

Confirmar la solicitud no equivale a aprobar una publicación. Para publicar o cambiar una programación, crea y muestra la revisión completa y actual. El texto requiere una aprobación nueva después de mostrarla. Las imágenes y los vídeos requieren que la persona los apruebe visualmente en una interfaz compatible o en Influence con la sesión iniciada. Preparar una revisión no publica nada. Consulta el resultado guardado antes de continuar; `needs_review` requiere aclarar lo ocurrido, no volver a enviar.

## Gestiona errores y resultados inciertos

Comprueba el estado HTTP y el cuerpo. El éxito devuelve `{"ok":true,"toolName":"…","output":{…}}`. Un fallo de herramienta devuelve `{"ok":false,"toolName":"…","error":{"code":"…","message":"…","retryable":false}}` y puede llegar con HTTP 200. Los fallos de transporte usan `{"error":{"code":"…","message":"…","retryable":false}}`, sin `ok` ni `toolName`.

Un 401 requiere autenticación: comprueba la caducidad o revocación. Un permiso ausente requiere la autorización correspondiente, no repetir solicitudes. Un 503 indica que la API no está disponible en ese entorno. Respeta los errores y las indicaciones de reintento. Agotar el tiempo de espera no demuestra que el cambio haya fallado: conserva sus datos de confirmación y consulta el estado antes de reenviar. Aceptado, programado y publicado son resultados distintos.

## Carga archivos multimedia

Para archivos locales, usa preferentemente `uploadMedia` del SDK o `media:upload` de la CLI. Ambos usan las herramientas de carga por partes y conservan un `clientKey` estable para los reintentos. Solo puedes adjuntar un resultado listo con `assetId`. Para referencias HTTPS autorizadas usa `mediaImport`; una ruta local no es una URL de descarga.

`POST /api/v1/media/import` admite el transporte existente de imágenes pequeñas: prepara `mediaImport` con el descriptor exacto y envía los mismos bytes como `application/octet-stream`. Incluye `X-Publish-Confirmation`, `Idempotency-Key` y `X-Publish-Upload` con el descriptor JSON codificado para URI. Los bytes deben coincidir con su tamaño y SHA-256. El límite es 3 MiB; usa el asistente de carga para archivos mayores compatibles. Cargar un archivo nunca aprueba su publicación.

[Consulta la referencia de la API](/es/api-reference) o [descarga la especificación OpenAPI](/specs/influence.openapi.json).