Sincronización con CRM

Envíe registros de graph8 a un CRM conectado. Se admiten cinco proveedores:

Proveedor	URL
hubspot	hubspot.com
salesforce	salesforce.com
pipedrive	pipedrive.com
zoho	zoho.com (CRM)
sugarcrm	sugarcrm.com

Primero debe conectar el CRM en Configuración -> Integraciones. El parámetro de ruta {provider} se resuelve con la conexión Nango existente para la organización. Si no existe ninguna conexión, recibirá 404 Not Found.

Endpoint	Método	Descripción
/crm-syncs	GET	Listar integraciones de CRM configuradas
/crm-syncs/{provider}/contacts/push	POST	Enviar contactos
/crm-syncs/{provider}/companies/push	POST	Enviar empresas
/crm-syncs/{provider}/lists/push	POST	Modificar membresías de listas (agregar o eliminar)
/crm-syncs/{provider}/fields	GET	Descubrir campos disponibles para un tipo de entidad
/crm-syncs/{provider}/status	GET	Verificar el estado de la conexión

Para los esquemas en formato legible por máquina, consulte la documentación interactiva de la API.

---

Listar sincronizaciones de CRM

GET /crm-syncs

Devuelve los proveedores de CRM conectados para la organización. No se incluyen los proveedores desconectados.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/crm-syncs" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": [
    {
      "provider": "hubspot",
      "status": "connected",
      "connection_id": "nango-conn-abc123",
      "last_sync_at": null,
      "connected_at": null
    }
  ]
}

---

Enviar contactos

POST /crm-syncs/{provider}/contacts/push

Crea contactos en masa en el CRM. El endpoint procesa cada registro de forma individual e informa los errores por registro en la respuesta. Un registro con errores no provoca el fallo del lote completo.

Cuerpo de la solicitud

Campo	Tipo	Requerido	Descripción
records	object[]	Sí	Datos de contacto en el formato de campo nativo del CRM (p. ej., email, firstname, lastname para HubSpot)
provider_fields	object	No	Configuraciones opcionales de mapeo de campos

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/crm-syncs/hubspot/contacts/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"email": "[email protected]", "firstname": "Jane", "lastname": "Smith"},
      {"email": "[email protected]", "firstname": "Bob", "lastname": "Jones"}
    ]
  }'

Respuesta

{
  "data": {
    "pushed_count": 2,
    "failed_count": 0,
    "errors": []
  }
}

Cuando un registro falla, errors[] contiene { "record": "<email>", "error": "<message>" }.

Errores

Estado	Significado
404	No hay una conexión {provider} activa. Conéctela primero en Integraciones

---

Enviar empresas

POST /crm-syncs/{provider}/companies/push

Misma estructura que el envío de contactos. Cada registro corresponde a los datos de una empresa (p. ej., name, domain, industry para HubSpot).

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/crm-syncs/salesforce/companies/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"Name": "Acme Inc", "Website": "acme.com", "Industry": "Technology"}
    ]
  }'

---

Enviar membresías de listas

POST /crm-syncs/{provider}/lists/push

Agrega o elimina contactos en listas del CRM. Cada entrada de records[] corresponde a una lista.

Cuerpo de la solicitud

Cada elemento en records[] debe tener la siguiente estructura:

Campo	Tipo	Descripción
list_id	string	Identificador de lista del CRM
add_contact_ids	string[]	IDs de contactos del CRM que se agregarán
remove_contact_ids	string[]	IDs de contactos del CRM que se eliminarán

Ejemplo

cURL

curl -X POST "https://be.graph8.com/api/v1/crm-syncs/hubspot/lists/push" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [{
      "list_id": "42",
      "add_contact_ids": ["101", "102"],
      "remove_contact_ids": ["999"]
    }]
  }'

Respuesta

{
  "data": {
    "added": 2,
    "removed": 1,
    "errors": []
  }
}

---

Descubrir campos

GET /crm-syncs/{provider}/fields

Devuelve el esquema (campos personalizados y estándar) de un tipo de entidad en el CRM. Resulta útil antes de un envío para validar de forma dinámica los nombres de los campos.

Parámetros de consulta

Parámetro	Tipo	Valor predeterminado	Descripción
entity_type	string	contacts	Uno de contacts, companies, leads, deals

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/crm-syncs/hubspot/fields?entity_type=contacts" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "fields": [
      {
        "name": "First Name",
        "slug": "firstname",
        "type": "string",
        "required": false,
        "label": "First Name"
      }
    ]
  }
}

Errores

Estado	Significado
502	El CRM rechazó la solicitud de descubrimiento. Consulte message para conocer el error del sistema externo

---

Obtener estado

GET /crm-syncs/{provider}/status

Verifica el estado de la conexión mediante una lectura pequeña. Devuelve connected: false (con un message) si la conexión está interrumpida o si el token OAuth expiró. Este endpoint nunca genera errores 5xx por fallos de conexión.

Ejemplo

cURL

curl "https://be.graph8.com/api/v1/crm-syncs/hubspot/status" \
  -H "Authorization: Bearer $API_KEY"

Respuesta

{
  "data": {
    "provider": "hubspot",
    "connected": true,
    "connection_id": "nango-conn-abc123",
    "crm_type": "hubspot",
    "message": "Connection is healthy",
    "last_sync_at": null
  }
}