# Sincronización con CRM

> Envíe contactos, empresas y membresías de listas a HubSpot, Salesforce, Pipedrive, Zoho o SugarCRM

Source: https://docs.graph8.com/es/developers/crm-syncs/

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](https://be.graph8.com/api/v1/docs).

---

## 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**

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

### Respuesta

```json
{
  "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**

```bash
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": "jane@acme.com", "firstname": "Jane", "lastname": "Smith"},
      {"email": "bob@acme.com", "firstname": "Bob", "lastname": "Jones"}
    ]
  }'
```

### Respuesta

```json
{
  "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**

```bash
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**

```bash
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

```json
{
  "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**

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

### Respuesta

```json
{
  "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**

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

### Respuesta

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