Crear albarán

POST https://api.afer.pro/api/v1/delivery-notes

Alias en castellano (v0, sigue operativo): POST https://api.afer.pro/crearAlbaran

Crea un albarán de venta con sus líneas y sus movimientos de inventario, sin emitir factura.

Útil cuando la venta se entrega antes de facturar o cuando agrupas varias operaciones en una factura posterior. El albarán se crea revisado, con numeración automática y fecha de hoy.

El cliente se resuelve igual que en crearFactura: puedes enviar cliente.id si ya conoces el cliente de facturación, o el objeto cliente completo para buscarlo por CIF o darlo de alta.

Las líneas con artículo en modo venta generan su movimiento de inventario y consolidan stock, igual que la factura.

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 →

Parámetros del cuerpo

El cuerpo de la petición es un objeto JSON con Content-Type: application/json.

`cliente`object obligatorio	Cliente de facturación. Envía `{"id": 123}` para usar un cliente existente, o el objeto completo (mismos campos que en crearFactura) para alta/actualización por CIF.
`id`int opcional	ID de un cliente de facturación existente. Si se envía, se usa directamente.
`nombre_fiscal, cif, direccion…`string opcional	Datos de alta si no envías `id`. Mismos campos que el objeto `cliente` de crearFactura.
`pedido`object obligatorio	Cabecera de la operación.
`obra`string obligatorio	Concepto o referencia de la operación.
`detalles_operacion`string opcional	Observaciones. Admite HTML.
`promo_code`string opcional	Código promocional aplicado.
`detalles`array obligatorio	Líneas del albarán. Misma estructura que las líneas de crearFactura: `cantidad`, `descripcion`, `importe_unitario`, `iva`, `descuento`, `articulo_fk`, `variacion_articulo_fk`, `descripcion_ampliada`, `startDate`, `endDate`.
`formatoId`string\|int opcional	Solo en cuentas con stock multiformato. Formato comercial de la línea (el `formatoId` de consultarFormatos). `cantidad` sigue siendo la cantidad comercial —5 cajas son `5`—, y el stock se descuenta en unidad base aplicando el factor del formato. Sin este campo se usa el formato marcado por defecto para venta, o la unidad base.
`cantidad_base_real`decimal opcional	Cantidad real en unidad base, para formatos de peso variable. 50 cajas de 8 kg nominales que pesan 397,6 kg se envían como `cantidad: 50` y `cantidad_base_real: 397.6`, y el stock descuenta 397,6, no 400. El factor nominal se guarda igualmente como instantánea del movimiento.

Ejemplo de petición

curl -X POST 'https://api.afer.pro/api/v1/delivery-notes' \
  -H 'X-API-KEY: afer_tk_TU_TOKEN' \
  -H 'X-API-SECRET: afer_sk_TU_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
    "cliente": {
        "nombre_fiscal": "Inmaculada Calderón Puyol",
        "cif": "31696215N",
        "direccion": "Rioja, 1",
        "cp": "11407",
        "poblacion": "Jerez de la Frontera",
        "provincia": "Cádiz",
        "pais": "España",
        "email": "inma@ejemplo.com"
    },
    "pedido": {
        "obra": "Entrega pedido web 1786212236453"
    },
    "detalles": [
        {
            "cantidad": 2,
            "articulo_fk": 405171,
            "variacion_articulo_fk": 0,
            "descripcion": "Shower gel Fig fields of the island",
            "importe_unitario": 6.6115702,
            "iva": 21
        }
    ]
}'

<?php

$data = [
  'cliente' => [
    'nombre_fiscal' => 'Inmaculada Calderón Puyol',
    'cif' => '31696215N',
    'direccion' => 'Rioja, 1',
    'cp' => '11407',
    'poblacion' => 'Jerez de la Frontera',
    'provincia' => 'Cádiz',
    'pais' => 'España',
    'email' => 'inma@ejemplo.com',
  ],
  'pedido' => [
    'obra' => 'Entrega pedido web 1786212236453',
  ],
  'detalles' => [
    0 => [
      'cantidad' => 2,
      'articulo_fk' => 405171,
      'variacion_articulo_fk' => 0,
      'descripcion' => 'Shower gel Fig fields of the island',
      'importe_unitario' => 6.6115702,
      'iva' => 21,
    ],
  ],
];

$ch = curl_init('https://api.afer.pro/api/v1/delivery-notes');
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/api/v1/delivery-notes', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': 'afer_tk_TU_TOKEN',
    'X-API-SECRET': 'afer_sk_TU_SECRET'
  },
  body: JSON.stringify({
      "cliente": {
          "nombre_fiscal": "Inmaculada Calderón Puyol",
          "cif": "31696215N",
          "direccion": "Rioja, 1",
          "cp": "11407",
          "poblacion": "Jerez de la Frontera",
          "provincia": "Cádiz",
          "pais": "España",
          "email": "inma@ejemplo.com"
      },
      "pedido": {
          "obra": "Entrega pedido web 1786212236453"
      },
      "detalles": [
          {
              "cantidad": 2,
              "articulo_fk": 405171,
              "variacion_articulo_fk": 0,
              "descripcion": "Shower gel Fig fields of the island",
              "importe_unitario": 6.6115702,
              "iva": 21
          }
      ]
  })
});

const resultado = await respuesta.json();

Respuesta

Devuelve el identificador cifrado del albarán creado.

200 · application/json

{
    "errorCode": 200,
    "errorMsg": "",
    "data": "aBc123XyZ456…"
}

Notas

El albarán no genera cobros ni vencimientos: estos se crean al facturarlo desde Afer.
Las líneas con startDate/endDate computan como reservas en consultarDisponibilidadArticulos.
Acepta la cabecera X-IDEMPOTENCY-KEY contra dobles clicks y reintentos.
Stock multiformato: enviar formatoId a una cuenta que no lo tiene activado devuelve 400, igual que enviar un formato que no es de ese artículo o que no está permitido en ventas (un palé de solo compra, por ejemplo). Se prefiere el error a descontar stock con un factor equivocado.