EtiQali API

Empezar en 3 pasos

Autenticación

Todas las peticiones a la API requieren una clave en la cabecera X-EtiQali-Key. Cada clave está autorizada para operar sobre un conjunto de empresas identificadas por CIF: una clave directa cubre una sola empresa (tu ERP emite lo tuyo); una clave de plataforma —una central de mercado, caja gremial o sistema que emite en nombre de varias empresas— cubre todo el conjunto que tiene autorizado. La regla es la misma en ambos casos: el cif_vendedor de cada albarán debe estar dentro del ámbito de la clave.

X-EtiQali-Key: etq_live_xxxxxxxxxxxxxxxxxxxxxxxx

Entornos

EtiQali ofrece dos entornos. Ambos comparten la misma especificación de API. Las llamadas al entorno de pruebas no generan trazabilidad real ni etiquetas oficiales.

Registrar un albarán

Registra un albarán de venta en EtiQali y obtén el número de lote único asignado a cada línea. La llamada debe realizarse en el momento de emisión del albarán por parte del vendedor.

Estructura de petición

El cuerpo de la petición debe ser un objeto JSON con los siguientes campos:

Campos de línea

Cada elemento del array linies describe un producto o lote vendido. Los campos opcionales aplican a sectores regulados específicamente (pesca, carne, etc.).

Campos comunes

Campos pesca (Reglamento UE 1379/2013)

Campos carne (RD 1698/2003, RD 142/2026)

Respuesta

Una respuesta exitosa devuelve HTTP 200 con un objeto JSON que confirma el registro y devuelve los números de lote generados.

{
  "ok": true,
  "num_albara": "ALB-2026-001234",
  "lots": [
    {
      "producte": "Merluza europea",
      "num_lot": "ALB-2026-001234-1",
      "qr_url": "https://app.etiqali.com/lot.html?lot=ALB-2026-001234-1"
    }
  ]
}

Campos de respuesta

Compradores con secciones

Un supermercado tiene una cuenta de EtiQali por cada sección de fresco — pescadería, carnicería, frutería, charcutería — porque cada una lleva su propia trazabilidad, sus propios lotes y su propia cartelería. Todas comparten el mismo CIF de la sociedad.

Si envías solo el cif_comprador, el albarán entra en la sección predeterminada. Para dirigirlo a la que corresponde, añade seccio:

Lo normal es enviarlo a nivel de albarán, porque un albarán suele ser de una sola sección. Si un albarán mezcla productos de varias, cada línea puede llevar su propio seccio, que prevalece sobre el del albarán:

{
  "num_albara": "A-1234",
  "data": "2026-09-01",
  "cif_vendedor": "B00000001",
  "cif_comprador": "B00000002",
  "seccio": "carn",
  "linies": [
    { "producte": "Solomillo de ternera", "cod_art": "512", "quantitat": 8 },
    { "producte": "Merluza", "cod_art": "235", "quantitat": 12, "seccio": "pesca" }
  ]
}

La respuesta incluye seccions con las secciones a las que ha ido el albarán, para que puedas verificar el encaminamiento desde tu ERP.

Una clave, varias empresas

Lo habitual es que una clave emita en nombre de una sola empresa. Pero hay casos en los que un mismo sistema centraliza los albaranes de muchas: un mercado mayorista cuyo software recibe los albaranes de todos sus asociados, un grupo de empresas, o un ERP en modo multiempresa.

Para esos casos, una clave puede estar autorizada sobre N empresas. No hace falta una clave por cada una, ni que cada empresa configure nada por su cuenta.

El funcionamiento es el mismo de siempre: en cada albarán envías el cif_vendedor correspondiente, y EtiQali comprueba que tu clave está autorizada para ese CIF.

// Un mismo sistema, dos vendedores distintos
{ "cif_vendedor": "B11111111", "num_albara": "1001", ... }
{ "cif_vendedor": "B22222222", "num_albara": "2001", ... }

Si envías un cif_vendedor para el que tu clave no está autorizada, la respuesta es empresa_not_authorized con código 422. La autorización se concede empresa por empresa, con su consentimiento, al dar de alta la clave.

Webhooks · recibir albaranes

Hasta aquí hemos visto cómo enviar lo que vendes. Los webhooks son el camino inverso: cuando un proveedor tuyo registra un albarán en EtiQali, EtiQali llama a tu ERP y le entrega la trazabilidad completa.

Tu sistema no tiene que preguntar nada ni programar ninguna sincronización. Solo necesita una URL que reciba peticiones POST.

Qué recibes

{
  "event": "compra.proposada",
  "estat": "pendent_acceptacio",
  "versio": 2,
  "rectificacio": true,
  "albara": { "num_albara": "A-1234", "data": "2026-09-01" },
  "proveidor": { "cif": "B11111111", "nom": "Mayorista Ejemplo, S.L." },
  "comprador": { "cif": "B22222222", "nom": "Pescadería Ejemplo" },
  "linies": [
    {
      "producte": "Merluza",
      "cod_art": "235",
      "quantitat": 12,
      "num_lot": "LNK-B11111111-A-1234-1",
      "nom_cientific": "Merluccius merluccius",
      "zona_fao": "27",
      "art_pesca": "Arrastre",
      "qr_url": "https://app.etiqali.com/lot.html?lot=..."
    }
  ],
  "emes_at": "2026-09-01T06:12:00.000Z"
}

Dos eventos posibles

El campo versio

Un albarán puede rectificarse varias veces antes de darse por bueno — en el sector mayorista es lo habitual. Cada envío lleva un número de versión que siempre crece.

Tu ERP debe guardar la última versión aplicada de cada albarán y descartar cualquier mensaje con versión igual o menor. Es la única forma de garantizar que un reintento retrasado no sobrescriba una rectificación posterior.

Verificar que la llamada es nuestra

Cada petición incluye estas cabeceras:

Calcula el HMAC con tu secreto y compáralo con la cabecera. Si no coincide, descarta la petición. Rechaza también las que lleguen con un timestamp de más de cinco minutos.

Qué debe responder tu ERP

Cualquier código 2xx se considera entregado. Responde rápido —lo ideal es aceptar y procesar después—: si tardas más de 15 segundos, se considera fallido.

Si tu servidor no responde, EtiQali reintenta al minuto, a los 5, a los 15, a la hora, a las 6 horas y a las 24. Un servidor apagado durante la noche no pierde ningún albarán.

Consultar el estado de tus entregas

GET https://api.etiqali.com/api/v1/webhooks/entregues
X-EtiQali-Key: tu_clave

Devuelve las últimas entregas con su estado (pendent, entregat, fallit), el número de intentos y el último error. Acepta ?estat=fallit para filtrar y ?cif= si tu clave cubre varias empresas.

Aceptar una compra

Cuando un proveedor registra un albarán a tu nombre, EtiQali no da por hecho que lo asumes. La compra queda a la espera de que la aceptes.

No es burocracia: el artículo 18 del Reglamento (UE) 178/2002 hace que tu trazabilidad sea tu responsabilidad, y no es delegable. Si un tercero registrara compras a tu nombre sin que tú intervengas, estaría firmando declaraciones por ti. Tu aceptación —con fecha y autor— es lo que convierte una información recibida en un registro tuyo, defendible ante una inspección.

Aceptar o rechazar

POST https://api.etiqali.com/api/v1/compres/acceptar
X-EtiQali-Key: tu_clave
Content-Type: application/json

{
  "cif": "B00000002",
  "num_albara": "A-1234",
  "accepta": true,
  "usuari": "id-del-responsable"
}

Para rechazar —mercancía que no llegó, cantidades que no cuadran— envía "accepta": false y un "motiu". El rechazo también queda registrado: es una declaración tan válida como la aceptación, y suele ser la que interesa conservar.

Aceptación automática por proveedor

Si recibes a diario del mismo proveedor y no quieres confirmar cada albarán, puedes declarar una sola vez que aceptas sus compras por adelantado. Esa declaración queda registrada con fecha y autor, y es revocable en cualquier momento.

A partir de entonces sus albaranes llegan como compra.registrada y no requieren ninguna acción. Sigue siendo una declaración tuya —hecha antes, no dejada de hacer—, que es lo que la sostiene.

Idempotencia y rectificaciones

El campo num_albara actúa como clave de idempotencia. Puedes reenviar el mismo albarán múltiples veces sin riesgo de duplicación:

• Mismo albarán, mismas líneas: EtiQali devuelve la respuesta original sin reprocesar. Útil para reintentos en caso de error de red.
• Mismo albarán, líneas distintas: EtiQali interpreta que se trata de una rectificación y actualiza el contenido manteniendo el identificador.

Ejemplo básico

Ejemplo mínimo en tres lenguajes:

curl -X POST https://api.etiqali.com/api/v1/albara \
  -H "Content-Type: application/json" \
  -H "X-EtiQali-Key: etq_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "num_albara": "ALB-2026-001234",
    "data": "2026-06-24",
    "cif_vendedor": "B00000001",
    "cif_comprador": "B00000002",
    "linies": [
      { "producte": "Merluza europea", "cod_art": "MER-EUR-1", "quantitat": 12.5 }
    ]
  }'

const response = await fetch('https://api.etiqali.com/api/v1/albara', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-EtiQali-Key': 'etq_live_xxxxxxxxxxxxxxxxxxxxxxxx'
  },
  body: JSON.stringify({
    num_albara: 'ALB-2026-001234',
    data: '2026-06-24',
    cif_vendedor: 'B00000001',
    cif_comprador: 'B00000002',
    linies: [
      { producte: 'Merluza europea', cod_art: 'MER-EUR-1', quantitat: 12.5 }
    ]
  })
});
const data = await response.json();
// data.lots[0].num_lot → imprimir en el albarán físico

import requests

response = requests.post(
    "https://api.etiqali.com/api/v1/albara",
    headers={
        "Content-Type": "application/json",
        "X-EtiQali-Key": "etq_live_xxxxxxxxxxxxxxxxxxxxxxxx",
    },
    json={
        "num_albara": "ALB-2026-001234",
        "data": "2026-06-24",
        "cif_vendedor": "B00000001",
        "cif_comprador": "B00000002",
        "linies": [
            {"producte": "Merluza europea", "cod_art": "MER-EUR-1", "quantitat": 12.5}
        ],
    },
)
data = response.json()
# data["lots"][0]["num_lot"] → imprimir en el albarán físico

$ch = curl_init('https://api.etiqali.com/api/v1/albara');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-EtiQali-Key: etq_live_xxxxxxxxxxxxxxxxxxxxxxxx',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'num_albara'    => 'ALB-2026-001234',
        'data'          => '2026-06-24',
        'cif_vendedor'  => 'B00000001',
        'cif_comprador' => 'B00000002',
        'linies'        => [
            ['producte' => 'Merluza europea', 'cod_art' => 'MER-EUR-1', 'quantitat' => 12.5],
        ],
    ]),
]);
$data = json_decode(curl_exec($ch), true);
// $data['lots'][0]['num_lot'] → imprimir en el albarán físico

Ejemplo sector pesquero

Albarán completo con campos normativos según Reglamento UE 1379/2013:

{
  "num_albara": "ALB-2026-001235",
  "data": "2026-06-24",
  "cif_vendedor": "B00000001",
  "cif_comprador": "B00000002",
  "linies": [{
    "producte": "Merluza europea",
    "cod_art": "MER-EUR-1",
    "lot": "LL-2026-00871",
    "nom_cientific": "Merluccius merluccius",
    "quantitat": 18.5,
    "unitat": "kg",
    "zona_fao": "27",
    "metode_produccio": "Captura",
    "art_pesca": "Arrastre de fondo",
    "llotja": "Vigo",
    "barco_nom": "Nuevo Galicia",
    "barco_matricula": "3-VI-2-1-08",
    "data_captura": "2026-06-22",
    "estat": "Fresc",
    "conservacio": "0–4 °C",
    "data_caducitat": "2026-06-28"
  }]
}

Ejemplo sector cárnico

Albarán completo con campos normativos según RD 1698/2003 y RD 142/2026:

{
  "num_albara": "ALB-2026-001236",
  "data": "2026-06-24",
  "cif_vendedor": "B00000001",
  "cif_comprador": "B00000002",
  "linies": [{
    "producte": "Jarrete Vacuno Añojo",
    "cod_art": "JAR-VAC-1",
    "quantitat": 8.2,
    "unitat": "kg",
    "especie": "Vacuno",
    "pais_nacimiento": "España",
    "pais_engorde": "España",
    "pais_sacrificio": "España",
    "matadero_id": "ES10.00001/B",
    "despiece_id": "ES10.00002/B",
    "lote_sacrificio": "S-26-06-001",
    "conservacio": "Refrigerado 0–4 °C",
    "data_caducitat": "2026-07-01"
  }]
}

Códigos de error

La API utiliza códigos de estado HTTP estándar. En caso de error, la respuesta incluye un objeto JSON con detalle:

{
  "ok": false,
  "error": "Campos obligatorios manquen",
  "detail": "Falta el campo cif_comprador"
}

Límites de uso

Para garantizar el servicio a todos los integradores, la API aplica límites razonables:

Si tu volumen previsto supera estos límites, contacta con soporte para revisar una configuración a medida.

Buenas prácticas

• Envía el albarán en el momento de emisión. Cuanto antes se registre, antes está disponible la trazabilidad para tu comprador.
• Usa siempre cod_art. Mantener el código de artículo de tu ERP en cada línea facilita el cruce posterior y la generación de etiquetas coherentes.
• Implementa reintentos. Para errores 5xx usa espera exponencial. Para 4xx no reintentes: revisa la petición.
• Guarda el num_lot devuelto. Es el identificador que vincula tu albarán físico con la trazabilidad de EtiQali.
• Trata la clave API como una contraseña. Almacénala en variables de entorno o un gestor de secretos, nunca en código fuente.

Versionado

La versión está incluida en la URL del endpoint (/api/v1/...). Cualquier cambio que rompa la compatibilidad dará lugar a una nueva versión (/api/v2/...) manteniendo la versión anterior durante al menos 12 meses.

Los cambios compatibles con la versión actual (nuevos campos opcionales, nuevos códigos de error) se introducen sin cambio de versión. Te recomendamos ignorar campos desconocidos en las respuestas.

Soporte para integradores

Para solicitar acceso, abrir una incidencia o consultar el estado del servicio: