Casar líneas con el catálogo
https://api.afer.pro/api/v1/products/match
GET https://api.afer.pro/api/v1/products/match
Dime las líneas como las ha dicho alguien y te digo cuáles son productos del catálogo, con su precio y su stock.
Antes de crear un presupuesto, un pedido o un albarán, pasa por aquí todas las líneas de una vez. Para cada una devuelve qué producto del catálogo es, si lo es, y qué hacer con ella:
casar: un producto gana de calle (referencia, SKU o EAN clavados; el nombre clavado o que empieza así; o el único que tiene esas palabras). La línea debe ir con suarticuloId: es lo que descuenta el stock en el albarán y pone su precio.preguntar: hay dos o tres candidatos parecidos (candidatos), o solo se parece por como suena (aproximado: true). Alguien tiene que elegir.libre: no hay nada en el catálogo que se le parezca. Va como línea libre, con descripción y precio.
Busca como busca una persona, igual que buscarCliente: todas las palabras en cualquier orden y sin acentos; si no, la mayoría de las palabras («disco duro SSD de un tera» encuentra «Disco SSD 1TB Samsung»); referencia, SKU y EAN sin puntos ni guiones; y por como suena como último recurso (nunca casa solo: pregunta).
De cada producto devuelve el precio que llevaría la línea —el del cliente si se envía clienteId, con las mismas reglas que al crear el documento; si no, la tarifa 1—, el iva, si controla_stock, el stock actual y falta_stock cuando no llega para la cantidad.
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.
lineasarrayobligatorio | Las líneas (1 a 200). Cada una: descripcion (obligatoria), cantidad (por defecto 1) y precio si lo han dicho (se devuelve tal cual como precio_dictado). |
clienteIdstring|intopcional | El cliente del documento, para dar el precio que llevaría la línea para él. |
Ejemplo de petición
curl -X GET 'https://api.afer.pro/api/v1/products/match?clienteId=aBc123XyZ%E2%80%A6&lineas%5B0%5D%5Bdescripcion%5D=Mano+de+obra&lineas%5B0%5D%5Bcantidad%5D=2&lineas%5B1%5D%5Bdescripcion%5D=Fuente+de+alimentaci%C3%B3n+500W&lineas%5B1%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bdescripcion%5D=Pantalla+curva+34%22&lineas%5B2%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bprecio%5D=390' \
-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/products/match?clienteId=aBc123XyZ%E2%80%A6&lineas%5B0%5D%5Bdescripcion%5D=Mano+de+obra&lineas%5B0%5D%5Bcantidad%5D=2&lineas%5B1%5D%5Bdescripcion%5D=Fuente+de+alimentaci%C3%B3n+500W&lineas%5B1%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bdescripcion%5D=Pantalla+curva+34%22&lineas%5B2%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bprecio%5D=390');
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/products/match?clienteId=aBc123XyZ%E2%80%A6&lineas%5B0%5D%5Bdescripcion%5D=Mano+de+obra&lineas%5B0%5D%5Bcantidad%5D=2&lineas%5B1%5D%5Bdescripcion%5D=Fuente+de+alimentaci%C3%B3n+500W&lineas%5B1%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bdescripcion%5D=Pantalla+curva+34%22&lineas%5B2%5D%5Bcantidad%5D=1&lineas%5B2%5D%5Bprecio%5D=390', {
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": {
"lineas": [
{
"n": 1,
"dicho": "Mano de obra",
"cantidad": 2,
"decision": "casar",
"seguro": true,
"articuloId": "dEf456…",
"nombre": "Mano de obra técnico (hora)",
"referencia": "MO-01",
"precio": 45,
"iva": 21,
"controla_stock": false,
"stock": null,
"falta_stock": false,
"encaje": 70,
"aproximado": false,
"candidatos": []
},
{
"n": 2,
"dicho": "Fuente de alimentación 500W",
"cantidad": 1,
"decision": "preguntar",
"articuloId": null,
"nombre": "",
"encaje": 30,
"aproximado": false,
"candidatos": [
{
"articuloId": "gHi789…",
"nombre": "Fuente alimentación Corsair 500W",
"referencia": "FA-500C",
"precio": 59,
"iva": 21,
"controla_stock": true,
"stock": 2,
"falta_stock": false,
"encaje": 30
},
{
"articuloId": "jKl012…",
"nombre": "Fuente alimentación Tacens 500W",
"referencia": "FA-500T",
"precio": 39,
"iva": 21,
"controla_stock": true,
"stock": 0,
"falta_stock": true,
"encaje": 30
}
]
},
{
"n": 3,
"dicho": "Pantalla curva 34\"",
"cantidad": 1,
"precio_dictado": 390,
"decision": "libre",
"articuloId": null,
"nombre": "",
"encaje": 0,
"aproximado": false,
"candidatos": []
}
],
"casadas": 1,
"preguntar": 1,
"libres": 1
}
}
Errores
| Caso | Resultado |
|---|---|
| Sin credenciales de API key | errorCode 401. |
lineas vacío, más de 200 líneas o una línea sin descripcion |
errorCode 400. |
clienteId que no es de tu cuenta |
errorCode 404. |
- Es una consulta (GET):
lineasva en la query con la notación de array de PHP (lineas[0][descripcion]=Mano%20de%20obra&lineas[0][cantidad]=2); por MCP se manda como array normal. - No escribe nada. Con el
articuloIdde cada línea casada se llama a crearAlbaran (o presupuesto o pedido); si quien dicta dio un precio, se manda comoprecio_unitario; si no, se omite y sale el del catálogo para ese cliente. - Las palabras de una o dos letras no cuentan para buscar; una referencia se reconoce aunque se diga con guiones o espacios.
seguro: falseen una línea casada quiere decir que era el único producto con esas palabras, no que el nombre coincida: conviene decirlo al leer las líneas.