Formatos comerciales

POST https://api.afer.pro/consultarFormatos

Las presentaciones con las que se compra y se vende cada artículo (palé, caja, saco…) y su equivalencia con la unidad base del stock.

Para mayoristas que compran en un formato y venden en otro: se recibe en palés y se vende en cajas, en kilos o por unidades.

El stock se guarda y se descuenta SIEMPRE en la unidad base del artículo (kg para el tomate, unidad para la lechuga). Los formatos son solo la presentación comercial, y cada uno lleva su factor: cuántas unidades base vale uno de ellos.

El factor es plano contra la unidad base, nunca encadenado. Un palé de 60 cajas de 8 kg se declara como 480, no como 60: así no hay cadenas de conversión que puedan quedar descuadradas.

Los campos stock y coste que devuelven consultarProductos y consultarStock están en esa misma unidad base.

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.

`articuloId`string\|int opcional	Para pedir los formatos de un solo artículo. Acepta el id cifrado o el numérico legacy.
`uso`string opcional	`compra` o `venta`. Devuelve también los marcados como `ambos`. Sin este parámetro salen todos.
`pagina`int opcional	Página a devolver. Por defecto `1`.
`por_pagina`int opcional	Resultados por página. Por defecto `100`, máximo `500`.

Ejemplo de petición

curl -X POST 'https://api.afer.pro/consultarFormatos' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "uso": "compra"
}'

<?php

$data = [
  'uso' => 'compra',
];

$ch = curl_init('https://api.afer.pro/consultarFormatos');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
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',
    'Content-Type: application/json',
]);

$respuesta = json_decode(curl_exec($ch), true);
curl_close($ch);

const respuesta = await fetch('https://api.afer.pro/consultarFormatos', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  },
  body: JSON.stringify({
      "uso": "compra"
  })
});

const resultado = await respuesta.json();

Respuesta

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": {
        "multiformato": true,
        "total_formatos": 2,
        "pagina": 1,
        "por_pagina": 100,
        "num_paginas": 1,
        "formatos": [
            {
                "formatoId": "aBc123XyZ…",
                "articuloId": "dEf456…",
                "articulo": "TOMATE PERA",
                "titulo": "Palé",
                "factor": 480,
                "unidad_base": "kg",
                "uso": "compra",
                "peso_variable": false,
                "decimales": 0,
                "defecto_compra": true,
                "defecto_venta": false
            },
            {
                "formatoId": "gHi789…",
                "articuloId": "dEf456…",
                "articulo": "TOMATE PERA",
                "titulo": "Caja 8 kg",
                "factor": 8,
                "unidad_base": "kg",
                "uso": "ambos",
                "peso_variable": true,
                "decimales": 0,
                "defecto_compra": false,
                "defecto_venta": true
            }
        ]
    }
}

Notas

Si la cuenta no tiene el stock multiformato activado, la respuesta llega con multiformato: false y la lista vacía. No es un error: esa cuenta trabaja con una sola unidad por artículo.
peso_variable marca los formatos cuya equivalencia es orientativa: una caja de 8 kg nominales pesa lo que pesa. En esos casos, al crear un albarán conviene mandar la cantidad real además de la comercial (ver crearAlbaran), porque el peso real manda sobre el factor.
uso dice dónde se puede usar cada formato. El palé suele ser solo de compra: enviarlo en una línea de venta devuelve 400.
decimales es la precisión admitida en la cantidad comercial. Un formato con 0 no acepta 2,5 palés.