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.

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: