Buscar un proveedor
https://api.afer.pro/api/v1/suppliers/search
GET https://api.afer.pro/api/v1/suppliers/search
Encuentra un proveedor por como lo diría una persona, no por como está escrito en la ficha.
listarProveedores recorre la cartera; esto encuentra a alguien. La diferencia importa cuando hay que llegar al proveedorId para crear un documento:
- El orden da igual: «suministros levante» encuentra «SUMINISTROS DEL LEVANTE, S.L.». Todas las palabras tienen que aparecer, en cualquier campo y en cualquier orden.
- Los acentos y los signos, también: «Cànaves» = «canaves», «S.L.» = «SL».
- El CIF, sin puntuación:
B-07.123.456encuentraB07123456. Si lo que se busca tiene forma de CIF, no se buscan sus trozos sueltos. - Un teléfono, por sus dígitos, con prefijo o sin él.
Y si así no sale nada, busca por como SUENA. Hace falta cuando el nombre viene de una transcripción de voz: a «Suministros del Levante» el teléfono puede entender algo que no comparte ni una palabra con la ficha. Se reduce todo a su esqueleto fonético —b=v, c=k=qu, z=s, ll=y=i, la hache fuera, las dobles aplastadas, sin espacios— y se mide el parecido; por debajo del 68 % no se ofrece. 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 usarlo: ayudar a encontrar no es lo mismo que colar un documento a quien no era.
Devuelve pocos y ordenados por lo bien que encajan (encaje: 100 CIF exacto, 90 nombre clavado, 70 empieza por ahí, 50 lo contiene, 30 están todas las palabras). Y devuelve unico: true cuando el primero gana de calle, con su clienteId arriba del todo para poder seguir sin preguntar; false si hay empate, que es cuando conviene preguntar en vez de elegir por sorteo.
Respeta la cartera compartida con la empresa matriz, igual que el listado. Es el mismo motor que buscarCliente.
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 | Nombre, CIF o teléfono, tal como lo diría alguien. |
por_paginaintopcional | Cuántos devolver como mucho. Por defecto 5, máximo 25. |
Ejemplo de petición
curl -X GET 'https://api.afer.pro/api/v1/suppliers/search?busqueda=suministros+levante' \
-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/suppliers/search?busqueda=suministros+levante');
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/suppliers/search?busqueda=suministros+levante', {
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": "suministros levante",
"total": 1,
"hay_mas": false,
"unico": true,
"proveedorId": "aBc123XyZ…",
"proveedores": [
{
"proveedorId": "aBc123XyZ…",
"nombre_fiscal": "SUMINISTROS DEL LEVANTE, S.L.",
"nombre_comercial": "Levante",
"cif": "B07123456",
"poblacion": "Palma",
"telefono": "971123456",
"movil": "",
"encaje": 30
}
]
}
}
- Las palabras de una o dos letras y las formas societarias (SL, SA, CB…) no cuentan para buscar: no distinguen a nadie y dejarían fuera a quien no las tiene escritas igual.
hay_masdice que había más de los que se devuelven: pide un dato más (el CIF, la población) en vez de subirpor_pagina.- La pasada fonética solo entra cuando la primera no encuentra nada, y compara hasta 8.000 fichas de la cartera. Si no sale nada, vale la pena reintentar con MENOS texto: solo el apellido, solo la primera palabra.