CRM y marketing

Crear oportunidad

POST https://api.afer.pro/crearOportunidad

Crea una oportunidad en un funnel del CRM, resolviendo o creando el contacto asociado por email o móvil.

Convierte un lead (formulario, campaña, chatbot…) en una oportunidad de venta en el funnel y la etapa que indiques.

Si envías email_contacto, el contacto se resuelve automáticamente: se busca en tu cuenta por email o móvil y, si no existe, se crea con persona_contacto, empresa, email_contacto y movil_contacto. También puedes vincular directamente un contacto existente con contacto_fk.

Los identificadores de funnel, etapa y canal son los de tu configuración de CRM en Afer; puedes consultarlos en la pantalla de configuración del CRM o pedirlos al activar la integración.

Autenticación

Envía tus claves API en las cabeceras X-API-KEY y X-API-SECRET. La cuenta sobre la que se opera se resuelve automáticamente a partir de la clave. Cómo obtener tus claves →

Parámetros del cuerpo

El cuerpo de la petición es un objeto JSON con Content-Type: application/json.

`datos`object obligatorio	Datos de la oportunidad.
`funnel_fk`int obligatorio	Funnel del CRM donde se crea la oportunidad.
`etapa_fk`int obligatorio	Etapa inicial dentro del funnel.
`descripcion`string obligatorio	Título de la oportunidad.
`canal_fk`int opcional	Canal de captación.
`email_contacto`string opcional	Email del lead. Activa la resolución automática de contacto (buscar por email/móvil o crear).
`movil_contacto`string opcional	Móvil del lead. Se usa junto al email para buscar el contacto.
`persona_contacto`string opcional	Nombre de la persona, si hay que crear el contacto.
`empresa`string opcional	Empresa del lead, si hay que crear el contacto.
`contacto_fk`int opcional	Contacto existente al que vincular la oportunidad (alternativa a la resolución por email).
`cliente_facturacion_fk`int opcional	Cliente de facturación al que vincular la oportunidad.

Ejemplo de petición

curl -X POST 'https://api.afer.pro/crearOportunidad' \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET' \
  -d '{
    "datos": {
        "funnel_fk": 39,
        "etapa_fk": 219,
        "descripcion": "Solicitud de presupuesto — reforma local",
        "canal_fk": 12,
        "persona_contacto": "Alex Riera",
        "empresa": "Riera & Fills",
        "email_contacto": "alex@ejemplo.com",
        "movil_contacto": "+34600333444"
    }
}'

<?php

$data = [
  'datos' => [
    'funnel_fk' => 39,
    'etapa_fk' => 219,
    'descripcion' => 'Solicitud de presupuesto — reforma local',
    'canal_fk' => 12,
    'persona_contacto' => 'Alex Riera',
    'empresa' => 'Riera & Fills',
    'email_contacto' => 'alex@ejemplo.com',
    'movil_contacto' => '+34600333444',
  ],
];

$ch = curl_init('https://api.afer.pro/crearOportunidad');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-KEY: afer_tk_TU_TOKEN',
    'X-API-SECRET: afer_sk_TU_SECRET',
]);

$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);

const respuesta = await fetch('https://api.afer.pro/crearOportunidad', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  },
  body: JSON.stringify({
      "datos": {
          "funnel_fk": 39,
          "etapa_fk": 219,
          "descripcion": "Solicitud de presupuesto — reforma local",
          "canal_fk": 12,
          "persona_contacto": "Alex Riera",
          "empresa": "Riera & Fills",
          "email_contacto": "alex@ejemplo.com",
          "movil_contacto": "+34600333444"
      }
  })
});

const resultado = await respuesta.json();

Respuesta

Devuelve el identificador numérico de la oportunidad creada.

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": 18234
}

Errores

Caso	Resultado
Falta `funnel_fk`, `etapa_fk` o `descripcion`	`errorMsg` "Error on service call: Oportunidad no creada: Parámetros incompletos."

Notas

A diferencia de los endpoints de facturación, la oportunidad se devuelve con su ID numérico, no cifrado.
Cada llamada crea una oportunidad nueva; no hay deduplicación por contacto.