DaraMex Docs

Appearance

Meta Instagram — Conexión Manual ​

Esta página documenta el flujo manual para conectar una cuenta de Instagram Business a DaraMex. Es una alternativa a Facebook Login para Empresas para clientes que no pueden o no quieren usar el OAuth interactivo.

Resumen ​

El flujo manual permite que el cliente genere un token de larga duración (System User token, "Nunca expira") en su propio Meta Business Manager y lo pegue en el wizard del panel junto con el ID de su Facebook Page. La API valida el token, verifica la vinculación de la cuenta de Instagram Business, y registra la conexión.

Cuándo es útil:

  • El cliente opera en un entorno corporativo donde los viajes OAuth interactivos requieren aprobaciones adicionales de TI.
  • El Facebook Login para Empresas de DaraMex aún no está aprobado por Meta para el Business Manager del cliente.
  • El cliente prefiere gestionar sus propios tokens en lugar de delegar el consentimiento OAuth.

Cuándo usar el flujo manual vs Facebook Login ​

CriterioFacebook Login (OAuth)Conexión Manual
Configuración inicialBaja — el cliente solo hace clic en "Conectar con Facebook"Alta — requiere crear un System User en Business Manager y generar un token manualmente
Gestión del tokenDaraMex renueva internamenteEl cliente es responsable de regenerar el token si lo revoca
Duración del tokenToken de Sistema de Usuario (SUAT), no expira"Nunca expira" — siempre que el cliente no lo revoque manualmente
Riesgo de interrupciónBajoAlto si el cliente rota sus tokens sin actualizar la conexión
Recomendado paraLa mayoría de los clientesClientes con restricciones corporativas o técnicas

Prerequisitos ​

El cliente debe tener activos y configurados los siguientes recursos antes de iniciar el flujo manual:

  1. Meta Business Manager activo — el cliente debe ser administrador de un Business Portfolio en business.facebook.com.

  2. Facebook Page administrada por ese Business Manager — el cliente debe ser administrador de la Page con acceso completo a la misma.

  3. Instagram Business Account vinculada a la Facebook Page (CRÍTICO — es el modo de falla más común). La cuenta de Instagram debe ser de tipo Business o Creator (no Personal). Para vincularla:

    • Ir a Meta Business Suite → Configuración → Cuentas → Cuentas de Instagram → Agregar.
    • Seguir el proceso para vincular la cuenta IG a la Page específica.

  4. System User creado en el Business Manager — con la Facebook Page asignada como asset con control total ("Administrar la Página"). Para crearlo: Business Manager → Usuarios → Usuarios del sistema → Agregar.

  5. La app de DaraMex asignada al System User — como asset de la app. El equipo de DaraMex debe haber proporcionado el App ID correspondiente.

  6. Token generado con expiración "Nunca expira" — al generar el token del System User, se debe seleccionar explícitamente la opción "Nunca" en el campo de expiración y marcar los scopes requeridos (ver sección siguiente).

Scopes requeridos ​

El token del System User debe tener todos los siguientes permisos:

ScopePara qué se usa
pages_show_listListar las Facebook Pages administradas por el token para verificar que pageId sea accesible.
pages_messagingEnviar y recibir mensajes de Messenger Platform en la Page. Requerido aunque se conecte Instagram — la Page es el carrier.
pages_manage_metadataSuscribir la Page al webhook de la app (/{pageId}/subscribed_apps) para recibir eventos de Instagram.
pages_read_engagementLeer metadatos de la Page (nombre, estado) durante el proceso de conexión.
instagram_basicAcceder a datos básicos de la cuenta de Instagram Business vinculada (ID, username).
instagram_manage_messagesEnviar y recibir mensajes de Direct de Instagram desde DaraMex.

Endpoint ​

POST /connections/meta/instagram/manual

Autenticación: sesión de panel activa (@Auth()). El usuario debe tener permiso CASL connections.connection:create.

Body:

json
{
  "accessToken": "EAABcde...",
  "pageId": "123456789",
  "displayName": "Mi Tienda IG"
}
CampoTipoRequeridoDescripción
accessTokenstringSíSystem User token generado en Business Manager con "Nunca expira".
pageIdstringSíID de la Facebook Page que tiene la cuenta de Instagram Business vinculada.
displayNamestringNoNombre visible de la conexión en DaraMex. Si se omite, se usa el username de la cuenta de Instagram.

Respuesta exitosa (200 OK):

json
{
  "connectionId": "01927bef-..."
}

Flujo ​

sequenceDiagram
    participant U as Usuario (Panel)
    participant P as Panel (UI)
    participant A as API
    participant M as Meta Graph API

    U->>P: Abre el wizard "Conexión manual" desde el catálogo de Instagram
    U->>P: Rellena accessToken + pageId + displayName (opcional)
    P->>A: POST /connections/meta/instagram/manual { accessToken, pageId, displayName? }

    A->>M: debug_token(accessToken)
    M-->>A: { expiresAt, dataAccessExpiresAt, scopes }
    note over A: Verifica expiresAt === 0 && dataAccessExpiresAt === 0<br/>Verifica 6 scopes requeridos

    A->>M: getMyAccountsWithIg(accessToken)
    M-->>A: [{ id, name, accessToken, igBusinessAccount? }]
    note over A: Busca page.id === pageId<br/>Verifica page.igBusinessAccount existe

    note over A: MetaAssetUniquenessPolicy.enforce('instagram', igBusinessAccount.id, agencyId)<br/>— el mismo IG Business Account no puede conectarse en dos orgs<br/>de la misma agency. Distintos IG accounts del mismo<br/>Business Manager SÍ pueden ir a orgs distintas.

    note over A: Persiste Connection con:<br/>accessToken = page.accessToken (Page Access Token, NO el SUSER)<br/>tokenType = system_user_manual<br/>channel = instagram

    A->>M: subscribePageToApp(pageId, page.accessToken)
    M-->>A: OK

    note over A: Emite MetaConnectionEstablishedIntegrationEvent<br/>→ CommunicationsModule crea ChannelAccount<br/>  externalAccountId = igBusinessAccount.id

    A-->>P: { connectionId }
    P-->>U: Conexión establecida

Errores y modos de falla ​

Código de errorHTTPCuándo ocurre
META_CONNECTION.TOKEN_WILL_EXPIRE400El token tiene fecha de expiración (expiresAt !== 0 o dataAccessExpiresAt !== 0). El cliente debe regenerar el token seleccionando "Nunca" como expiración.
META_CONNECTION.TOKEN_LACKS_SCOPES400Al token le faltan uno o más de los 6 scopes requeridos. La respuesta incluye la lista de scopes faltantes en metadata.missing.
META.PAGE_NOT_ACCESSIBLE400El pageId proporcionado no aparece en la lista de Pages administradas por el token. Verificar que el System User tenga la Page asignada como asset.
META.INSTAGRAM_ACCOUNT_NOT_LINKED400La Facebook Page existe y es accesible, pero no tiene una cuenta de Instagram Business vinculada. Ver la sección de prerequisitos.
META.ASSET_ALREADY_CONNECTED409Ya existe una conexión para ese igBusinessAccountId dentro de la misma agency (en cualquiera de sus orgs). Distintas cuentas de IG del mismo Business Manager SÍ pueden conectarse en orgs distintas.
META_CONNECTION.INVALID_ACCESS_TOKEN400El token proporcionado es inválido o fue revocado antes de la validación.

Decisión de diseño: por qué se almacena el Page Access Token y no el SUSER ​

El token que se persiste en la base de datos es el Page Access Token (page.accessToken del Graph API), no el System User token que el cliente pegó en el formulario.

Razón técnica: los endpoints de la Graph API que DaraMex usa para operar IG Business Messaging requieren un token scoped a la Page:

  • POST /{igBusinessAccountId}/messages — enviar mensajes de Direct. Requiere el Page token (no el SUSER).
  • POST /{pageId}/subscribed_apps — suscribir la Page al webhook para recibir eventos de Instagram. Requiere el Page token.

El SUSER es un token a nivel de usuario de sistema, útil para llamadas de administración, pero los endpoints de mensajería y webhooks exigen el token de la Page específica. Este mismo razonamiento aplica al flujo OAuth — ver complete-meta-instagram-connect.command.ts para el comentario en el paso 7.

Páginas relacionadas ​