Base URL https://api.afer.pro Referencia aferapp.com Reservar demo

Buscar una oportunidad

GET https://api.afer.pro/api/v1/crm/opportunities/search
Alias en castellano (v0, sigue operativo): 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: true y confirmar: true, unico es siempre false y encaje es 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.

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 →

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.

busquedastring
obligatorio
La empresa, la persona, el título o el teléfono, tal como lo diría alguien.
incluir_cerradasbool
opcional
true para buscar también entre las ganadas y perdidas. Por defecto solo las abiertas.
incluir_importesbool
opcional
true para que cada oportunidad traiga su valor (valor de cierre). Por defecto no.
por_paginaint
opcional
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

200 · application/json
{
    "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

CasoResultado
Sin credenciales de API key errorCode 401.
busqueda vacía o sin nada con lo que buscar errorCode 400.
Notas
  • Las palabras de una o dos letras y las formas societarias (SL, SA, CB…) no cuentan para buscar, igual que en buscarCliente.
  • hay_mas dice que había más de las que se devuelven: pide un dato más (la persona, el título) en vez de subir por_pagina.
  • Con el oportunidadId en la mano, anotarOportunidad deja apuntado lo que ha pasado; moverOportunidadEtapa y cerrarOportunidad la hacen avanzar.