Buscar una oportunidad
https://api.afer.pro/api/v1/crm/opportunities/search
GET https://api.afer.pro/api/v1/crm/opportunities/search
Encuentra una oportunidad por como la nombra una persona: la empresa, el contacto o el título.
consultarOportunidades cuenta el embudo; esto encuentra una. La diferencia importa cuando hay que llegar al oportunidadId para anotar en ella o decir cómo va, sobre todo desde un asistente de voz o de chat:
- Por lo que diría alguien: la empresa del contacto, la persona, el título de la oportunidad o el cliente de facturación que lleve enganchado. Todas las palabras tienen que aparecer, en cualquier campo y en cualquier orden, sin acentos ni signos: «Mixin Media» encuentra «MIXING MEDIA SL».
- Por el teléfono del contacto, por sus dígitos.
- Y si así no sale nada, por como SUENA: la misma pasada fonética de buscarCliente. Entonces la respuesta trae
aproximado: trueyconfirmar: true,unicoes siemprefalseyencajees el porcentaje de parecido. Eso hay que leerlo en voz alta y esperar un sí antes de anotar nada.
Devuelve pocas y ordenadas por lo bien que encajan (encaje: 90 nombre clavado, 70 empieza por ahí, 50 lo contiene, 30 están todas las palabras), y a igual encaje primero las abiertas y luego la más reciente. Cada una viene con lo que hace falta para hablar de ella sin otra consulta: nombre (cómo decirla: la empresa, si no la persona, si no el título), embudo, etapa, estado, el proxima_accion previsto y la ultima_nota. Y unico: true cuando la primera gana de calle, con su oportunidadId arriba del todo.
Por defecto busca solo entre las abiertas: una nota va casi siempre a algo vivo. Los importes (valor) solo salen con incluir_importes.
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 →
Este endpoint requiere autenticación con API key: sin credenciales responde 401.
Parámetros del cuerpo
El cuerpo de la petición es un objeto JSON con Content-Type: application/json.
busquedastringobligatorio | La empresa, la persona, el título o el teléfono, tal como lo diría alguien. |
incluir_cerradasboolopcional | true para buscar también entre las ganadas y perdidas. Por defecto solo las abiertas. |
incluir_importesboolopcional | true para que cada oportunidad traiga su valor (valor de cierre). Por defecto no. |
por_paginaintopcional | Cuántas devolver como mucho. Por defecto 5, máximo 25. |
Ejemplo de petición
curl -X GET 'https://api.afer.pro/api/v1/crm/opportunities/search?busqueda=Mixing+Media' \
-H 'X-API-KEY: afer_tk_TU_TOKEN' \
-H 'X-API-SECRET: afer_sk_TU_SECRET'
<?php
$ch = curl_init('https://api.afer.pro/api/v1/crm/opportunities/search?busqueda=Mixing+Media');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'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/api/v1/crm/opportunities/search?busqueda=Mixing+Media', {
method: 'GET',
headers: {
'X-API-KEY': 'afer_tk_TU_TOKEN',
'X-API-SECRET': 'afer_sk_TU_SECRET'
}
});
const resultado = await respuesta.json();
Respuesta
{
"errorCode": 200,
"errorMsg": "",
"data": {
"buscado": "Mixing Media",
"total": 1,
"hay_mas": false,
"unico": true,
"aproximado": false,
"confirmar": false,
"solo_abiertas": true,
"oportunidadId": "aBc123XyZ…",
"oportunidades": [
{
"oportunidadId": "aBc123XyZ…",
"nombre": "MIXING MEDIA SL",
"titulo": "Consultoría IA",
"empresa": "MIXING MEDIA SL",
"contacto": "Aina Torres",
"telefono": "600112233",
"embudo": "Consultorías IA",
"etapa": "Reunión discovery",
"estado": "abierta",
"creada": "2026-09-30",
"proxima_accion": {
"texto": "Llamar · Consultoría IA",
"fecha": "2026-10-22 00:00",
"medio": "llamada"
},
"ultima_nota": {
"fecha": "2026-10-16 20:21",
"texto": "WhatsApp de Aina: se disculpa por no contestar ayer. La propuesta va por buen camino."
},
"encaje": 50
}
]
}
}
Errores
| Caso | Resultado |
|---|---|
| Sin credenciales de API key | errorCode 401. |
busqueda vacía o sin nada con lo que buscar |
errorCode 400. |
- Las palabras de una o dos letras y las formas societarias (SL, SA, CB…) no cuentan para buscar, igual que en buscarCliente.
hay_masdice que había más de las que se devuelven: pide un dato más (la persona, el título) en vez de subirpor_pagina.- Con el
oportunidadIden la mano, anotarOportunidad deja apuntado lo que ha pasado; moverOportunidadEtapa y cerrarOportunidad la hacen avanzar.