API de Scoutello
La API de Scoutello es una API de servidor a servidor para sincronizar en ambas direcciones los contactos, las tareas, los protocolos, las oportunidades, los proyectos, los hitos y los eventos de una organización. También expone el historial de correo saliente en modo de solo lectura, la consulta de miembros asignables y la detección de etiquetas según la entidad. Las rutas incrementales GET/list y las actualizaciones por lotes idempotentes son los mecanismos de sincronización de esta versión. No expone operaciones de eliminación ni webhooks.
La URL base de la API es:
https://admin.scoutello.com/api/v1
También se muestra en Configuración de la organización → Desarrollador/API. El documento de OpenAPI está disponible en:
https://admin.scoutello.com/api/v1/openapi.json
Crear y proteger una clave
En las organizaciones modulares, el módulo CRM debe estar activo además de contar con los permisos necesarios para la clave. Una clave válida no puede activar un módulo que falta. Las solicitudes devuelven HTTP 403 con el código de error module_not_active cuando el acceso al CRM no está disponible. Una persona con permisos de administración de la organización puede consultar o activar el CRM en Suscripción; volver a intentarlo cuando el acceso esté activo.
Una persona con permisos de administración de la organización puede crear una integración y una clave de API en Configuración de la organización → Desarrollador/API. La clave completa se muestra una sola vez. Copiarla en un gestor de secretos antes de cerrar el cuadro de diálogo; Scoutello no puede volver a mostrar la clave completa.
- Usar una integración y una clave independientes para cada sistema externo y entorno.
- Conceder únicamente los permisos que necesite cada sistema.
- No incluir nunca una clave en código del navegador, una URL, el control de versiones, registros, mensajes de soporte ni almacenamiento del lado del cliente.
- Rotar las claves periódicamente. Al rotar una integración activa, la clave de reemplazo funciona de inmediato y la clave anterior sigue siendo válida durante un máximo de 15 minutos para que el sistema externo pueda cambiar sin interrupciones. Si ya existía una fecha de caducidad anterior, esta se mantiene; por tanto, la clave anterior puede dejar de funcionar antes.
- Si una clave puede haberse expuesto, pausar la integración antes de rotarla. La pausa rechaza temporalmente todas las claves de la integración. Una rotación mientras está pausada no tiene período de solapamiento: la clave anterior permanece desactivada y la clave de reemplazo seguirá desactivada hasta reanudar la integración.
- Revocar permanentemente toda la integración al desconectar un sistema externo. La revocación desactiva todas sus claves y no se puede deshacer.
Enviar la clave en cada solicitud autenticada:
Authorization: Bearer YOUR_API_KEY
Se recomienda la autenticación mediante Bearer. Los clientes que no puedan establecer Authorization pueden usar x-api-key en su lugar. No enviar ambas cabeceras; las solicitudes con valores diferentes en ambas cabeceras se rechazan.
La API está destinada a clientes de backend y no habilita el acceso del navegador entre orígenes.
Usar GET /whoami después de configurar una clave para verificar la integración, la organización, los permisos y los límites de la clave sin obtener datos personales de las personas usuarias.
Permisos
| Ámbito | Permite |
|---|---|
contacts.read | Enumerar y recuperar contactos. Se excluyen los contactos de cuentas de la organización y los contactos de miembros con acceso. |
contacts.write | Validar y aplicar altas y actualizaciones de contactos. |
tasks.read | Enumerar y recuperar tareas no privadas. |
tasks.write | Validar y aplicar altas y actualizaciones de tareas. |
protocols.read | Enumerar y recuperar protocolos no privados. |
protocols.write | Validar y aplicar altas y actualizaciones de protocolos. |
opportunities.read | Enumerar y recuperar oportunidades. |
opportunities.write | Validar y aplicar altas y actualizaciones de oportunidades. |
projects.read | Enumerar y recuperar proyectos. |
projects.write | Validar y aplicar altas y actualizaciones de proyectos y participantes. |
milestones.read | Enumerar y recuperar hitos de proyectos. |
milestones.write | Validar y aplicar altas y actualizaciones de hitos. |
members.read | Enumerar miembros aceptados mostrando únicamente el ID de cliente del miembro, el ID de usuario y el nombre visible. |
events.read | Enumerar y recuperar eventos y calendarios principales. |
events.write | Validar y aplicar altas y actualizaciones de eventos. |
mails.read | Leer el historial de correo saliente de la organización, tanto enviado como fallido. |
mail-drafts.read | Leer los borradores independientes de aprobación de correo de esta integración y el estado de entrega. |
mail-drafts.write | Preparar o revisar borradores de correo para su aprobación humana; nunca aprobar ni enviar. |
tags.read | Descubrir etiquetas seleccionables para los tipos de entidades compatibles. |
Esta API nunca devuelve tareas ni protocolos privados. Si falta un ámbito, se devuelve un error de autorización; no se trata como un resultado vacío.
Un contacto de CRM que no sea miembro puede leerse y referenciarse incluso cuando está vinculado a un inicio de sesión de Scoutello. La respuesta contiene únicamente los campos de CRM de la organización, nunca datos de identidad ni de acceso del usuario. Los contactos con un rol, permisos, invitación, aceptación o estado de cuenta de la organización permanecen ocultos. Está prohibido editar un contacto vinculado a un inicio de sesión (protected_contact), incluidos los campos de CRM que, por lo demás, no hayan cambiado. Para referenciar un contacto existente y legible desde una tarea o un protocolo, contacts.write puede establecer su vínculo externo únicamente con externalId, scoutelloId y externalUpdatedAt opcional. Las actualizaciones posteriores que solo modifiquen los metadatos del vínculo utilizan externalId y externalUpdatedAt opcional; omitir scoutelloId de inicialización una vez establecido el vínculo. Esto nunca modifica el contacto ni su usuario. La asignación de miembros aceptados utiliza la proyección independiente members.read.
Las nuevas claves utilizan el prefijo sctl_api_ y comienzan únicamente con contacts.write. Cualquier otro ámbito requiere una autorización explícita que una persona con permisos de administración de la organización debe conceder al crear o rotar una clave. Las credenciales existentes conservan sus ámbitos actuales y siguen siendo válidas.
Contactos vinculados a proyectos y borradores de correo electrónico
Las operaciones de actualización o creación de contactos aceptan pares opcionales projectScoutelloId / projectExternalId y companyScoutelloId / companyExternalId (elegir uno por cada par). El contacto, la relación con la empresa y la pertenencia al proyecto se guardan atómicamente por elemento. Añadir la pertenencia a un proyecto requiere projects.write; omitir las referencias conserva las demás relaciones y pertenencias. Las respuestas de lectura de los detalles del contacto incluyen projectParticipations cuando se concede projects.read. Los agentes de proyectos de ventas deben incluir explícitamente la referencia del proyecto, incluso al reutilizar un contacto.
Los borradores independientes utilizan el sistema existente de aprobación humana, sin una ejecución de flujo de trabajo:
| Método | Ruta | Finalidad |
|---|---|---|
| GET | /mail-drafts | Borradores paginados propiedad de la integración; filtros opcionales projectScoutelloId y status. |
| GET | /mail-drafts/{scoutelloId} | Versión actual, enlace de revisión, hash del contenido, estado de aprobación/envío y eventual ID del correo. |
| GET | /mail-drafts/external/{externalId} | Buscar un ID externo estable de la integración. |
| POST | /mail-drafts/batch-upsert | Validar o aplicar la preparación del borrador. |
La preparación del borrador requiere mail-drafts.write, contacts.read y projects.write. El contacto referenciado se convierte en participante del proyecto. La persona aprobadora debe ser un miembro aceptado de la organización con permiso para editar correos electrónicos. La selección del remitente utiliza la configuración existente de remitente de la organización o personal permitida para ese miembro; no se aceptan direcciones arbitrarias en el campo From.
{
"mode": "validate",
"records": [{
"externalId": "sales:indoor:outreach:museum:v1",
"expectedVersion": 0,
"project": { "externalId": "sales:indoor" },
"contact": { "externalId": "sales:indoor:museum:person" },
"approverScoutelloUserId": "ACCEPTED_MEMBER_USER_ID",
"senderScope": "organization",
"content": {
"to": ["verified-recipient@example.com"],
"subject": "Indoor tour proposal",
"body": "The intended email copy only.",
"notes": "Internal research and review context; not sent."
}
}]
}
Revisar cada resultado de validación antes de repetir la operación con mode: "apply". Leer el ID resultante para obtener reviewUrl, draftVersion, contentHash, status, dispatchStatus y mailScoutelloId. Utilizar expectedVersion: 0 únicamente para la creación y la versión actual devuelta para las revisiones. El contexto y la persona aprobadora son inmutables; los borradores revisados o enviados rechazan el contenido modificado. Los reintentos idénticos devuelven el borrador original.
Los borradores aparecen en las pestañas Email del proyecto o contacto y en las notificaciones de aprobación del panel. La preparación mediante la API no envía ningún correo, incluidos los correos de notificación; el comportamiento existente de los correos de notificación del flujo de trabajo no cambia. La persona asignada puede editar destinatarios, asunto, cuerpo y archivos adjuntos compatibles, guardar la versión y, después, Aprobar y enviar. Las integraciones no pueden realizar la aprobación ni el envío. Las entregas fallidas o ambiguas nunca se reintentan a ciegas. Al convertir borradores basados en protocolos, conservar los protocolos y establecer referencias cruzadas con sus reemplazos.
Acceso a MCP
La misma clave de API y los mismos permisos de Scoutello pueden utilizarse con el endpoint MCP HTTP con streaming:
https://admin.scoutello.com/api/v1/mcp
Configurar el cliente MCP para que envíe Authorization: Bearer YOUR_API_KEY. La URL heredada /api/mcp sigue disponible como alias de compatibilidad de ruta, pero los clientes nuevos deben utilizar el endpoint versionado. Las credenciales sctl_mcp_ anteriores no se aceptan; sustituirlas por una clave de integración de API de Scoutello.
Las herramientas de MCP se corresponden directamente con el contrato REST y utilizan los mismos esquemas de ejecución, comprobaciones del espacio empresarial, ciclo de vida de la integración, límite de solicitudes y métodos de servicio. Por ejemplo, contacts_list, contacts_get, contacts_get_by_external_id y contacts_batch_upsert reflejan las cuatro rutas de contactos. El mismo patrón se aplica a tareas, protocolos, oportunidades, proyectos, hitos y eventos; el correo expone mails_list y mails_get, los miembros exponen members_list y las etiquetas exponen tags_list.
El servidor solo anuncia las herramientas permitidas por los permisos de la clave actual. Una clave con contacts.read puede descubrir las herramientas de lectura de contactos, pero no contacts_batch_upsert; una clave con contacts.write obtiene la herramienta de actualización por lotes, pero no las herramientas de lectura. whoami está siempre disponible. Las herramientas de escritura tienen los mismos efectos inmediatos que sus equivalentes REST, por lo que debe utilizarse mode: "validate" cuando se deba inspeccionar un lote sin aplicarlo.
MCP también funciona entre servidores y no habilita el acceso del navegador entre orígenes. Su transporte JSON-RPC necesita una URL específica, por lo que no puede compartir la URL de un recurso REST individual, aunque la autenticación y el comportamiento de los datos sean compartidos.
Para consultar la configuración completa del cliente, la verificación, la correspondencia de herramientas y las instrucciones de resolución de problemas, consultar la guía de integración de MCP.
Leer registros
Los contactos, las tareas, los protocolos, las oportunidades, los proyectos, los hitos y los eventos utilizan las mismas rutas de lectura:
GET /contacts?limit=50&updatedSince=2026-09-01T00:00:00.000Z
GET /contacts/{scoutelloId}
GET /contacts/external/{externalId}
Sustituir contacts por tasks, protocols, opportunities, projects, milestones o events para los demás recursos de sincronización. externalId aparece en un DTO de lectura cuando el registro ha sido vinculado por esta integración.
Una respuesta de lista tiene este sobre:
{
"data": [],
"page": {
"nextCursor": null,
"hasMore": false,
"snapshotAt": "2026-09-01T12:00:00.000Z"
},
"requestId": "request-id"
}
limit debe estar entre 1 y 100. Los resultados se ordenan por el momento efectivo en que cambió su representación en la API pública y, después, por el ID de Scoutello. Este momento efectivo puede ser posterior al updatedAt de la entidad devuelta cuando cambian los metadatos del enlace de integración. Los cursores son opacos: guárdalos y envíalos sin modificarlos, y no deduzcas su significado a partir de su contenido.
La primera respuesta fija snapshotAt para ese recorrido. Sigue nextCursor hasta que hasMore sea falso antes de iniciar otra lectura incremental. Esto evita que los cambios en los registros durante la paginación vuelvan inestable el recorrido actual.
Para la sincronización incremental, procesa todas las páginas del cursor y, después, guarda el snapshotAt de ese recorrido como marca de agua temporal superior. Pásalo como valor updatedSince en formato ISO 8601 en el siguiente recorrido. El límite inferior es inclusivo, por lo que repetir una instantánea completada puede devolver registros del límite, pero no puede omitirlos.
Una respuesta de un solo registro tiene este sobre:
{
"data": {},
"requestId": "request-id"
}
Las respuestas de un solo contacto también incluyen un array relations. Cada relación conserva su ID de relación de Scoutello, la hora de creación, el tipo, las notas y las referencias de contacto connectedFrom y
connectedTo. Las referencias de contacto contienen el ID de Scoutello y el ID externo de esta integración, si existe. Los contactos excluidos por el límite de privacidad de acceso de la organización de la API no se muestran a través de las relaciones.
La respuesta de lista de contactos es compacta y no incluye relaciones; utiliza cualquiera de las rutas de contacto individual cuando necesites detalles sobre las relaciones.
Filtros de trabajo y ámbito del cursor
Las listas de contactos aceptan search, type (person, company, supplier, other), status y tagIds. La búsqueda elimina los espacios sobrantes, no distingue entre mayúsculas y minúsculas y está limitada a 200 caracteres / 10 tokens separados por espacios en blanco. Cada token debe aparecer en al menos uno de firstName, lastName o companyName, incluidos los nombres de empresa antiguos almacenados en lastName. Caracteres como % y _ se comparan literalmente. Las etiquetas utilizan coincidencia cualquiera de con entre 1 y 50 IDs. Todos los filtros proporcionados se combinan con AND. REST codifica los IDs de etiquetas como parámetros repetidos; MCP proporciona un array:
GET /contacts?search=Hamburg%20Hotel&type=company&status=prospect&tagIds=tag-one&tagIds=tag-two
Los cursores de contactos están vinculados a la organización, la integración y todos los filtros. Mantén los filtros en cada página; cambiar un filtro invalida el cursor. El orden y los duplicados de las etiquetas, así como el orden, las mayúsculas, las minúsculas y los espacios en blanco de los tokens de búsqueda, no cambian el filtro efectivo.
Las rutas de listas de trabajo aceptan los siguientes filtros adicionales; se rechazan otras combinaciones de recursos y campos:
| Recurso | Filtros |
|---|---|
| Tareas | projectScoutelloId, milestoneScoutelloId, status, statusType, priority, parentState, blockedState, assignedScoutelloUserId, dueBefore, dueAfter |
| Protocolos | projectScoutelloId, milestoneScoutelloId, status (draft o final) |
| Oportunidades | projectScoutelloId, stage, ownerScoutelloUserId |
| Proyectos | status, assignedContactScoutelloId |
| Hitos | projectScoutelloId, status, assignedContactScoutelloId, dueBefore, dueAfter |
dueBefore es exclusivo; dueAfter es inclusivo. Se comparan la fecha de vencimiento de la tarea o la fecha de finalización del hito; los registros sin esa fecha no coinciden. Proporcionar fechas y horas ISO con zona horaria. Todos los filtros se aplican antes de la paginación. Continuar un cursor con exactamente los mismos filtros, incluido updatedSince, y la misma organización o integración. El tamaño de página puede cambiar. Los cursores antiguos sin ámbito deben reiniciarse desde la marca de tiempo de referencia guardada después de esta versión.
Proyectos, hitos, asignaciones y notas
GET /members (MCP members_list) utiliza la paginación estándar y requiere members.read. Devuelve scoutelloId (ID de miembro Customer), scoutelloUserId (ID de User) y displayName. Solo aparecen miembros de la organización aceptados que tienen un rol; la búsqueda no expone correos electrónicos ni permisos.
Las tareas aceptan assignedScoutelloUserIds; las oportunidades utilizan ownerScoutelloUserId. Los proyectos y los hitos utilizan assignedContacts: [{"scoutelloId":"member-customer-id"}]. Las asignaciones requieren miembros aceptados de la organización de la credencial. Omitir las asignaciones las mantiene sin cambios; [] las elimina. Las importaciones de proyectos, hitos, tareas y protocolos son silenciosas: no envían notificaciones de asignación ni comunicaciones.
El evento assignedContacts admite contactos de CRM identificables y miembros aceptados proporcionados mediante el ID de miembro de Customer. Los miembros aceptados no están disponibles como referencias de contactos de CRM normales ni como destinos de enlaces externos; utilizar el campo de asignación de miembros para indicar la responsabilidad del equipo.
Crear hitos con un name y projectScoutelloId o projectExternalId. Admiten description (Markdown), status (open, in_progress, completed, closed), startDate/endDate anulables, order (con valor predeterminado de 0) y assignedContacts. Las fechas no pueden finalizar antes de comenzar. Cada hito tiene un enlace externo estable con alcance limitado a la integración. Su proyecto no se puede cambiar mediante la API. Las operaciones de creación y actualización localizan el nombre y la descripción en el idioma de la organización.
Las tareas y los protocolos aceptan referencias a proyectos, hitos y oportunidades como <entity>ScoutelloId o <entity>ExternalId, por ejemplo, milestoneExternalId. Proporcionar una sola variante ortográfica por relación, también al borrar con null. Todas las relaciones deben pertenecer a la organización de la credencial. Una referencia que solo incluye el hito infiere el proyecto; se rechaza un proyecto en conflicto o el borrado explícito de un proyecto mientras se conserva su hito. Una oportunidad vinculada con un proyecto debe coincidir con el proyecto del trabajo. Omitir relaciones conserva los valores actuales; null explícito borra una relación cuando el contexto restante es válido. Las lecturas exponen ambas variantes de ID y las asignaciones de tareas.
Planificación de tareas y flujos de trabajo
Task status es la clave inmutable de un estado en el flujo de trabajo efectivo de la tarea, no un valor fijo de una enumeración. Leer los flujos de trabajo disponibles de la organización y del proyecto con GET /task-workflows usando el alcance tasks.read. Cada estado incluye su clave, etiqueta, ciclo de vida type (backlog, unstarted, started, completed o cancelled), color, orden, indicador predeterminado y estado de archivado. Las entradas de proyecto indican si se hereda el flujo de trabajo de la organización. La configuración del flujo de trabajo continúa administrándose desde el panel.
Las tareas aceptan priority anulable (low, medium, high o urgent) y estimatedEffortMinutes, además de startDate y dueDate anulables. Las lecturas de tareas incluyen statusType desnormalizado, la referencia al elemento principal, referencias compactas a subtareas y referencias blockedBy / blocks.
Crea o actualiza una subtarea de un nivel con parentTaskScoutelloId o parentTaskExternalId; null la convierte en una tarea de nivel superior. Las dependencias utilizan matrices de referencias { "scoutelloId": "..." } o { "externalId": "..." } en blockedBy y blocks. Omitir los campos de relación los conserva, mientras que una matriz de dependencias vacía elimina las dependencias en esa dirección. La API rechaza subtareas anidadas, dependencias entre elementos principales y secundarios, dependencias entre organizaciones, duplicados, autorreferencias y ciclos directos o transitivos.
Los filtros de la lista de tareas aceptan un flujo de trabajo exacto status, un ciclo de vida statusType, priority, parentState (top_level, subtask o parent) y blockedState (blocked, blocking o unblocked).
Los protocolos también aceptan status: "draft" | "final" (los registros nuevos toman final de forma predeterminada). Un protocolo nuevo requiere type, date y un contacto o un contexto válido de proyecto/hito. contactExternalId: null elimina su contacto solo cuando se conserva el contexto de proyecto/hito. Por tanto, las notas internas del proyecto pueden crearse y leerse sin inventar un cliente. Draft/final describe el estado de la nota y nunca envía una comunicación. Las tareas y los protocolos privados siguen siendo inaccesibles.
Participantes del proyecto
Project participants contiene operaciones de inserción o actualización aditivas identificadas mediante una referencia contact, por ejemplo:
{
"externalId": "gtm:hotels",
"participants": [{
"contact": {"scoutelloId": "prospect-contact-id"},
"role": "Potential pilot",
"notes": "Existing warm lead; qualify the next step.",
"groupScoutelloId": null
}]
}
Los participantes describen los prospectos o clientes asociados a un proyecto; las personas responsables se gestionan mediante asignaciones. Omitir los participantes, utilizar una matriz vacía u omitir campos de participantes conserva los datos existentes. null elimina role, notes o groupScoutelloId. Las referencias duplicadas a contactos resueltos en una misma carga se rechazan. Los grupos ya deben pertenecer al proyecto seleccionado; las lecturas incluyen participantGroups (ID/nombre), así como los ID de participantes, contactos, función, notas e ID del grupo. Actualmente, el panel permite eliminar participantes o crear grupos.
Inserción o actualización de registros por lotes
Escribe hasta 100 registros mediante la ruta por lotes del recurso:
POST /contacts/batch-upsert
Content-Type: application/json
{
"mode": "apply",
"records": [
{
"externalId": "record-123",
"externalUpdatedAt": "2026-09-01T11:45:00.000Z",
"type": "person",
"firstName": "Alex",
"lastName": "Example",
"email": "alex@example.com"
}
]
}
Los lotes de tareas resuelven sus registros de tareas antes de aplicar las relaciones principales y las dependencias. Este procesamiento en dos fases permite que una tarea principal, bloqueadora o bloqueada haga referencia a otra tarea creada en el mismo lote mediante su ID externo, independientemente del orden de los registros.
Utilice el documento OpenAPI para consultar los campos y las restricciones de validación de cada recurso. Cada registro debe tener un externalId estable de entre 1 y 200 caracteres. Trátelo como un identificador técnico opaco: no utilice una dirección de correo electrónico, un nombre, un secreto de API ni otros datos personales. externalUpdatedAt es opcional, pero se recomienda encarecidamente cuando el sistema de origen proporcione una marca de tiempo de modificación fiable.
El cuerpo de la solicitud está limitado a 1 MiB. mode tiene apply como valor predeterminado:
applyvalida y escribe los registros aceptados.validaterealiza la misma validación y asociación sin escribir datos, y devuelve resultadoswould_*.
Para las importaciones de contactos, matchByEmail puede establecerse en true en la solicitud. Su valor predeterminado es false; el ID externo es el límite de identidad más seguro.
Los campos omitidos conservan el valor actual. Un null explícito borra un campo que admite valores nulos, y una matriz de asignaciones o etiquetas vacía proporcionada borra esa relación. Los participants de proyectos son actualizaciones o inserciones aditivas: una matriz vacía no modifica la lista de integrantes. Las escrituras de etiquetas de contactos, tareas, oportunidades y eventos utilizan los ID de etiquetas de Scoutello. Los ID externos de las relaciones solo se resuelven mediante enlaces pertenecientes a la integración actual, mientras que los ID de usuario de Scoutello utilizados para la propiedad o la responsabilidad deben identificar a integrantes aceptados de la organización actual.
La creación de oportunidades requiere una cuenta o un contacto, y las oportunidades perdidas requieren un motivo de pérdida. Los importes monetarios utilizan céntimos enteros. Los nombres y las descripciones de proyectos y eventos se leen y escriben en el idioma configurado de la organización. Las escrituras de eventos admiten fechas explícitas y recurrencias diarias, semanales o mensuales con exclusiones; los niveles de visibilidad publicados siguen sujetos a los controles de preparación legal de Scoutello. La API no expone la venta de entradas para eventos, participantes, contenido multimedia, plantillas, boletines, colaboraciones ni otros controles avanzados de gestión de eventos.
Descubrir etiquetas
Utilice el endpoint de etiquetas antes de proporcionar tagIds:
GET /tags?entity=events&type=category
entity es obligatorio y acepta contacts, tasks, opportunities o events. Se asigna a la relevancia de etiqueta almacenada correspondiente. type es opcional y acepta category o attribute. Las categorías seleccionables pueden pertenecer a la organización o ser globales; los atributos seleccionables proceden del conjunto global de atributos seleccionado por Scoutello. Los resultados incluyen scoutelloId, el nombre localizado al idioma de la organización, type y relevancy. Los ID de etiquetas de otra organización, con una relevancia incorrecta o no seleccionables rechazan el elemento de lote afectado.
Leer el historial de correo saliente
El historial de correo es de solo lectura:
GET /mails?updatedSince=2026-09-01T00:00:00.000Z
GET /mails/{scoutelloId}
Solo se devuelve el correo propiedad de la organización con estado sent o failed. Las respuestas contienen encabezados y cuerpo almacenados comunes, BCC, estado y marcas de tiempo, referencias a proyectos/eventos/boletines, IDs y tipos de archivos adjuntos, así como estadísticas agregadas de entrega, apertura, clics, rebotes, reclamaciones y rechazos de destinatarios. Los correos en borrador, en cola o programados, las filas por destinatario, las instantáneas renderizadas, los errores sin procesar del proveedor y las URL de descarga de archivos adjuntos nunca se exponen. Una actualización posterior de la entrega a un destinatario adelanta la marca de tiempo de sincronización efectiva del correo, por lo que vuelve a aparecer en las lecturas incrementales. No existen rutas para escribir correos.
El resultado de una aplicación puede ser created, updated, linked, unchanged, stale_ignored o rejected. La validación utiliza would_create, would_update, would_link, would_leave_unchanged, would_ignore_stale o rejected. Una solicitud de lote válida devuelve HTTP 200 incluso cuando se rechazan registros individuales, por lo que siempre se deben revisar todos los elementos y el resumen de la respuesta. Conservar la respuesta requestId al solicitar al soporte de Scoutello que investigue un fallo.
Marcas de tiempo y conflictos
Cuando está presente externalUpdatedAt, Scoutello lo utiliza para rechazar cambios obsoletos sin que falle el resto del lote. Un resultado stale_ignored es terminal para esa carga útil antigua; obtener el registro actual antes de decidir si se envía una versión más reciente.
Tratar las marcas de tiempo como valores UTC ISO 8601. Conservar su precisión original y no sustituir la hora en que se ejecutó un trabajo de sincronización por la hora de modificación del registro de origen.
Idempotencia
El límite de idempotencia es la integración más externalId. Scoutello compara un hash canónico de la carga útil y el valor opcional externalUpdatedAt, por lo que reintentar el mismo registro no crea duplicados y puede devolver unchanged.
Con externalUpdatedAt, la misma marca de tiempo y carga útil es unchanged, una marca de tiempo anterior es stale_ignored y la misma marca de tiempo con una carga útil diferente constituye un conflicto de versión. Para un enlace que nunca ha aceptado una marca de tiempo, la misma carga útil sin marca de tiempo permanece unchanged, mientras que una carga útil modificada se aplica en el orden de llegada. Después de que un enlace haya aceptado una marca de tiempo, una carga útil modificada que omita externalUpdatedAt se rechaza como conflicto de versión, de modo que los datos sin versionar no puedan sobrescribir el estado versionado. Por eso se recomiendan encarecidamente las marcas de tiempo de modificación del origen.
Registro de auditoría
Las acciones de creación, actualización y sincronización solo de enlaces aceptadas por la API aparecen en los registros de cambios de Scoutello con Public API como origen y están vinculadas a la integración responsable. Los resúmenes operativos de las ejecuciones conservan los ID de solicitud y los recuentos agregados de resultados para la resolución de problemas; no conservan cargas útiles de registros ni secretos de API.
Errores y reintentos
Los errores a nivel de solicitud usan este formato:
{
"error": {
"code": "error_code",
"message": "Safe error message",
"requestId": "request-id",
"details": {}
}
}
Reintentar las respuestas HTTP 429 y las respuestas transitorias 5xx aplicando un retroceso exponencial con variación aleatoria. Respetar Retry-After cuando esté presente. Es posible que los fallos de red se hayan producido después de que Scoutello aceptara una solicitud; reenviar el mismo lote es seguro porque cada registro es idempotente según el ID externo y la carga útil canónica. No reintentar automáticamente los resultados de autenticación, autorización, validación, conflicto de versiones o rejected individuales sin modificar la solicitud.
Bucle de sincronización bidireccional recomendado
- Llamar a
/whoamidurante la configuración y verificar la organización y los permisos esperados. - Leer cada página modificada desde el último marcador de progreso completado y aplicar esos cambios al sistema externo de forma idempotente.
- Enviar los cambios externos a
/batch-upsertusando ID externos estables y marcas de tiempo de modificación de origen. - Guardar los puntos de control solo después de procesar todas las páginas y los resultados de los elementos.
- Resolver los conflictos según las reglas de propiedad del sistema de origen; no simular eliminaciones enviando registros vacíos.
Scoutello no ofrece deliberadamente ninguna ruta pública de eliminación en esta primera versión. Gestionar las políticas de eliminación o archivado fuera de la API hasta que se introduzca una operación de ciclo de vida documentada.
Publicaciones sociales para revisión humana
La API social prepara publicaciones para una persona revisora identificada. No puede aprobarlas ni publicarlas. REST y MCP usan los mismos permisos y el mismo servicio.
| Permiso | Endpoints en /api/v1 |
|---|---|
social-channels.read | GET /social-channels |
social-posts.read | GET /social-posts, GET /social-posts/{scoutelloId} |
social-post-drafts.read | GET /social-post-drafts, GET /social-post-drafts/{scoutelloId}, GET /social-post-drafts/external/{externalId} |
social-post-drafts.write | POST /social-post-drafts/batch-upsert, POST /social-media/uploads, POST /social-media/uploads/{assetId}/finalize |
Los nuevos permisos deben concederse explícitamente. Las credenciales existentes no obtienen acceso adicional. Usar members.read para descubrir los ID de usuario de los miembros y seleccionar una persona revisora con permiso de publicación (newsletter.edit). Los borradores no requieren un contacto de CRM ni un proyecto.
{
"mode": "apply",
"records": [{
"externalId": "campaign:autumn:launch",
"expectedVersion": 0,
"approverScoutelloUserId": "REVIEWER_USER_ID",
"content": {
"title": "Autumn launch",
"publishMode": "schedule",
"scheduledAt": "2026-10-01T09:00:00+02:00",
"variants": [{
"channelId": "CHANNEL_SCOUTELLO_ID",
"content": "Explore the autumn collection.",
"settings": {},
"mediaIds": ["FINALIZED_ASSET_ID"]
}]
}
}]
}
Usar publishMode: "now" y scheduledAt: null para publicar una vez aprobada. Cada
variante de canal contiene el texto completo, la configuración y los identificadores de medios ordenados.
La detección de canales devuelve los formatos compatibles, los límites y la configuración. Actualmente,
los canales compatibles son perfiles y páginas de LinkedIn, Facebook, Instagram y Threads.
Instagram requiere medios. Una variante admite hasta diez imágenes o vídeos.
Los lotes admiten hasta 100 identificadores externos únicos dentro del límite actual de 1 MiB por solicitud.
mode: "validate" comprueba las referencias y las versiones sin guardar borradores,
subir recursos, crear notificaciones ni poner trabajos en cola. Los resultados de la aplicación incluyen
identificadores, enlaces de revisión, versiones y resultados por registro. Los errores parciales no revierten
los registros relacionados que se hayan procesado correctamente. Un error de notificación devuelve una
advertencia con la URL de revisión guardada.
Recuperar el draftVersion actual antes de revisar un borrador pendiente. Los reintentos
idénticos son idempotentes y conservan las ediciones humanas posteriores. Las personas revisoras no se pueden
cambiar directamente. Después de aprobar o rechazar, usar un nuevo identificador externo para otra propuesta.
Las lecturas de borradores están limitadas a la integración que las solicita; el historial de publicaciones
incluye todas las campañas creadas por Scoutello y almacenadas en la organización, incluidas las publicaciones
creadas desde el panel, mediante script y con el Scoutello anterior. No importa el historial externo de los canales.
Las listas usan los parámetros estándar limit, cursor y updatedSince. Las publicaciones y
los borradores también aceptan channelId, status, after, before y search; conservar
todos los filtros en las páginas posteriores del cursor. Los filtros de fecha se aplican a la hora de publicación
(hora de creación en el caso de borradores pendientes inmediatos). El filtro status de borradores filtra por el estado de aprobación;
status de publicaciones coincide con el estado de entrega de una campaña o de un canal. Las lecturas muestran
el último estado de entrega conocido, los errores por canal, los enlaces públicos y las marcas de tiempo de conciliación.
Las lecturas incrementales de borradores también reflejan los cambios en la entrega de campañas.
Subir medios
- Llamar a
POST /social-media/uploadsconclientUploadId,filename,contentType,sizeen bytes y elsha256hexadecimal en minúsculas de los bytes originales. Los tipos compatibles son PNG, JPEG, WebP, MP4, WebM, QuickTime y M4V. El límite de carga es de 500 MiB. - Enviar los bytes originales mediante HTTP
PUTaupload.url, utilizando sus encabezados. Las URL de carga caducan después de 15 minutos. ReutilizarclientUploadIdpara reintentar la carga del mismo archivo; las sesiones caducadas o los archivos diferentes requieren un ID nuevo. - Llamar a
POST /social-media/uploads/{assetId}/finalizecon un cuerpo JSON de{}. La finalización comprueba el tamaño, el tipo, la firma y la suma de comprobación, congela una copia privada y devuelve el ID del recurso paramediaIds. Repetir la finalización es seguro.
La propiedad de la carga está vinculada a la organización y a la integración. Los borradores pueden hacer referencia a recursos finalizados de su organización. Las URL de vista previa son temporales; volver a obtener el borrador para actualizarlas. Nunca se emiten URL de carga para objetos finalizados.
Revisión humana y entrega
La persona revisora recibe una notificación en el panel y puede abrir la publicación desde Postings o mediante su URL de revisión. Editar crea otra versión inmutable. La aprobación utiliza la versión mostrada y el hash del contenido, vuelve a comprobar la pertenencia, los canales y los recursos, y crea atómicamente una única campaña duradera. Si la hora propuesta ya ha pasado, la persona revisora debe guardar una hora nueva explícita o seleccionar la publicación al aprobar.
Los reintentos de la cola reutilizan la campaña y los comprobantes de su plataforma. Las campañas aprobadas no se pueden editar directamente. Cancelarlas desde el panel conserva su historial de aprobación y sus archivos multimedia; la cancelación no puede interrumpir un envío activo. Consultar el borrador o la campaña para distinguir entre la aprobación y la entrega efectiva en la plataforma.