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

Casar líneas con el catálogo

GET https://api.afer.pro/api/v1/products/match
Alias en castellano (v0, sigue operativo): 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 su articuloId: 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.

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.

lineasarray
obligatorio
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|int
opcional
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

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

CasoResultado
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.
Notas
  • Es una consulta (GET): lineas va 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 articuloId de cada línea casada se llama a crearAlbaran (o presupuesto o pedido); si quien dicta dio un precio, se manda como precio_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: false en 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.