La API de TRAZZA.

Cada petición lleva una clave de API en la cabecera Authorization: Bearer trz_…. Las claves se crean en Ajustes → Conexiones para desarrolladores; el secreto se enseña una sola vez al crearla (guardamos solo su huella, no la clave) y se puede revocar en cualquier momento. Usa una clave por integración: así puedes cortar una sin tocar las demás.

curl "https://trazza.newtex.es/api/v1/products?limit=20" \
  -H "Authorization: Bearer trz_TU_CLAVE"

Todo lo que devuelve una clave es de su cuenta y solo de su cuenta: no hay forma de leer ni escribir datos de otra, y un identificador ajeno responde como si no existiera. Lo que registras por la API no se atribuye a ninguna persona: el operario queda vacío y el registro de actividad dice qué clave lo hizo.

La API y los webhooks salientes son del plan Enterprise. Una clave válida de una cuenta en otro plan recibe un 403 con details.code: PLAN_REQUIRED; es un 403 a propósito, para que tu programa pare en lugar de reintentar. Al bajar de plan las claves se revocan.

{
  "error": "La función claves de API y webhooks es exclusiva del plan Enterprise. Contacta con NEWTEX para ampliar tu plan.",
  "code": "FORBIDDEN",
  "details": { "code": "PLAN_REQUIRED", "plan": "PRO", "feature": "apiAccess", "requiredPlan": "ENTERPRISE" },
  "requestId": "…"
}

Límite de peticiones

120 peticiones por minuto por clave. Cada respuesta correcta lleva X-RateLimit-Limit y X-RateLimit-Remaining; al pasarte recibes un 429 con Retry-After (segundos que faltan). Para traer mucho histórico, pagina con limit=100 en lugar de lanzar peticiones en paralelo.

Formato de error

Todos los errores son JSON con el mensaje en castellano, un code estable para tu código, un details opcional y el requestId, que también va en la cabecera X-Request-Id de toda respuesta. Si nos escribes por un fallo, ese identificador nos lleva directos a tu petición. Puedes mandar tu propio X-Request-Id y lo respetamos.

{
  "error": "Datos de entrada inválidos.",
  "code": "VALIDATION_ERROR",
  "details": {
    "issues": [
      { "path": "limit", "message": "No puede pasar de 100.", "code": "too_big" }
    ]
  },
  "requestId": "6f1c2a8e-3b4d-4e5f-9a0b-1c2d3e4f5a6b"
}

Regla para reintentar: un 4xx dice que la petición está mal y repetirla igual no la arregla; un 429 o un 5xx sí se reintentan, con espera.

CORS

Las respuestas llevan Access-Control-Allow-Origin: * y cada ruta contesta la consulta previa OPTIONS admitiendo Authorization, Content-Type y X-Request-Id. Aun así, no pongas la clave en código que se descarga en un navegador público: quien la lea puede usarla. Llama a la API desde tu servidor o desde una aplicación interna.

Identificadores en formato cuid (cm1p3x7a2…), fechas en ISO 8601 UTC y cantidades enteras. Los listados paginan con page y limit y devuelven el mismo bloque pagination: page, limit, total, totalPages, hasNext y hasPrev.

curl "https://trazza.newtex.es/api/v1/products?search=filtro&page=1&limit=50" \
  -H "Authorization: Bearer trz_TU_CLAVE"

{
  "items": [
    {
      "id": "cm1p3x7a20004qw81kd9e2f1b",
      "sku": "FIL-0412",
      "name": "Filtro de aceite",
      "category": "Filtros",
      "unit": "u",
      "barcode": "8412345678905",
      "price": 9.9,
      "threshold": 5,
      "hasLots": false,
      "tags": ["mantenimiento"],
      "totalStock": 14,
      "isLowStock": false
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

curl "https://trazza.newtex.es/api/v1/stock" \
  -H "Authorization: Bearer trz_TU_CLAVE"

{
  "items": [
    {
      "sku": "FIL-0412",
      "productName": "Filtro de aceite",
      "warehouseCode": "MAIN",
      "warehouseName": "Almacén principal",
      "warehouseArchived": false,
      "quantity": 14,
      "threshold": 5,
      "isLow": false,
      "valorTotal": 89.6
    }
  ]
}

curl "https://trazza.newtex.es/api/v1/movements?from=2026-09-01&to=2026-09-30&order=165PE&sort=asc&limit=100" \
  -H "Authorization: Bearer trz_TU_CLAVE"

{
  "items": [
    {
      "id": "cm1q8z0k40007ab12cd34ef56",
      "type": "OUT",
      "direction": "DECREASE",
      "quantity": 2,
      "product": { "id": "cm1p3x7a20004qw81kd9e2f1b", "sku": "FIL-0412", "name": "Filtro de aceite", "unit": "u" },
      "warehouseFrom": { "id": "cm1p2k0a10001qw81aa0b1c2d", "code": "MAIN", "name": "Almacén principal" },
      "warehouseTo": null,
      "reference": null,
      "orderRef": "165PE",
      "lotCode": null,
      "reason": null,
      "unitCost": null,
      "totalCost": null,
      "createdAt": "2026-09-30T08:12:44.000Z",
      "operator": "Nombre del operario"
    }
  ],
  "pagination": { "page": 1, "limit": 100, "total": 1, "totalPages": 1, "hasNext": false, "hasPrev": false }
}

curl -X POST "https://trazza.newtex.es/api/v1/movements" \
  -H "Authorization: Bearer trz_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "IN",
    "productId": "cm1p3x7a20004qw81kd9e2f1b",
    "warehouseToId": "cm1p2k0a10001qw81aa0b1c2d",
    "quantity": 10,
    "unitCost": 6.4,
    "reference": "ALB-2026-0412",
    "clientKey": "4b0f2c3e-8d1a-4f5e-9b7c-2a6d1e0f3c48"
  }'

{
  "movement": {
    "id": "cm1q9a4b50009ab12xy34zt78",
    "type": "IN",
    "productId": "cm1p3x7a20004qw81kd9e2f1b",
    "quantity": 10,
    "warehouseToId": "cm1p2k0a10001qw81aa0b1c2d",
    "unitCost": "6.4",
    "totalCost": "64",
    "reference": "ALB-2026-0412",
    "operatorId": null,
    "createdAt": "2026-09-30T09:01:12.000Z"
  },
  "productTotalStock": 24
}

curl "https://trazza.newtex.es/api/v1/work-orders/165PE" \
  -H "Authorization: Bearer trz_TU_CLAVE"

{
  "order": { "ref": "165PE", "number": "165", "type": "PE" },
  "lines": [
    {
      "id": "cm1q8z0k40007ab12cd34ef56",
      "type": "OUT",
      "quantity": 2,
      "product": { "id": "cm1p3x7a20004qw81kd9e2f1b", "sku": "FIL-0412", "name": "Filtro de aceite", "unit": "u" },
      "unitCost": 6.4,
      "totalCost": 12.8,
      "estimatedCost": true,
      "createdAt": "2026-09-30T08:12:44.000Z",
      "operator": "Nombre del operario",
      "loadId": "cm1q8y9z00005ab12gh56ij78",
      "deliveryNote": null
    }
  ],
  "loads": [
    {
      "id": "cm1q8y9z00005ab12gh56ij78",
      "status": "SENT",
      "operator": "Nombre del operario",
      "openedAt": "2026-09-30T08:12:44.000Z",
      "closedAt": "2026-09-30T08:17:46.000Z",
      "closeReason": "INACTIVITY",
      "emailSentAt": "2026-09-30T08:17:48.000Z",
      "attempts": 1,
      "lastError": null,
      "recipients": ["recambios@tu-taller.es"]
    }
  ],
  "totals": { "unitsLoaded": 2, "loadedCost": 12.8, "purchasedCost": 0, "linesWithoutCost": 0 }
}

En Ajustes → Conexiones para desarrolladores das de alta la dirección de tu servidor y eliges los eventos. Cada evento sale como un POST JSON con el sobre { id, event, data, tenantId }.

En stock.movement, productTotalStock llega cuando el movimiento se registra de uno en uno (no en las entradas en lote ni en los albaranes).

Ejemplo: material cargado en una orden

Cuando un operario termina de cargar material en una orden (pulsa «Terminar carga» o pasan 5 minutos sin lecturas), sale un único evento con todo lo cargado, sumado por producto. operator es el nombre de quien lo cargó.

POST /webhooks/trazza HTTP/1.1
Content-Type: application/json
X-Trazza-Event: material.cargado_en_orden
X-Trazza-Delivery-Id: 9c1f4e7a2b8d40c6a5e3f1b2c7d8e9f0
X-Trazza-Timestamp: 1759219068
X-Trazza-Signature: 3f6b…(HMAC-SHA256 del cuerpo, en hex)
X-Trazza-Signature-256: t=1759219068,v1=8a2e…(HMAC-SHA256 de "t.cuerpo", en hex)

{
  "id": "9c1f4e7a2b8d40c6a5e3f1b2c7d8e9f0",
  "event": "material.cargado_en_orden",
  "data": {
    "loadId": "cm1q8y9z00005ab12gh56ij78",
    "order": "165PE",
    "orderNumber": "165",
    "orderType": "PE",
    "operator": "Nombre del operario",
    "from": "2026-09-30T08:12:44.000Z",
    "to": "2026-09-30T08:16:02.000Z",
    "lines": [
      { "sku": "FIL-0412", "name": "Filtro de aceite", "quantity": 2 },
      { "sku": "TOR-M6-20", "name": "Tornillo M6 x 20", "quantity": 8 }
    ]
  },
  "tenantId": "cm1p1a0b20000qw81zz9y8x7w"
}

Cabeceras

Entrega y reintentos

Responde con un 2xx en menos de 8 segundos y procesa después: pasado ese tiempo el intento se da por fallido. Si tu servidor no responde, responde 408, 429 o un 5xx, lo volvemos a intentar solos con espera creciente; cualquier otro 4xx se da por rechazado y no se repite (repetirlo no cambiaría la respuesta).

Cada reintento lleva el mismo X-Trazza-Delivery-Id y el mismo cuerpo, con un X-Trazza-Timestamp y una firma X-Trazza-Signature-256 nuevos: tu comprobación de los 5 minutos sigue valiendo para un reintento que llega horas después. Si se agotan los intentos, la entrega queda como fallida en Ajustes, con su código y el motivo, y desde ahí se puede reenviar (otra vez con el mismo id). Avisamos a la administración de tu cuenta una vez, no por cada entrega.

Idempotencia

La entrega es al menos una vez: si tu 2xx se pierde por el camino, el mismo evento puede llegar dos veces. Guarda el id de cada evento procesado y, si vuelve a llegar, responde 2xx sin aplicarlo otra vez: es tu garantía de no imputar dos veces lo mismo. Si tu servidor estuvo caído más de lo que cubren los reintentos, recupera lo que falte con GET /movements o GET /work-orders/{ref}. Solo enviamos a direcciones públicas; no se siguen redirecciones.

Cada endpoint tiene su secreto (whsec_…), que ves en Ajustes. Para comprobar un envío: separa t y v1 de X-Trazza-Signature-256, rechaza si t se aleja más de 5 minutos de tu reloj (así un envío capturado no se puede repetir más tarde), calcula el HMAC-SHA256 de `${t}.${cuerpo}` con el secreto sobre el cuerpo crudo, tal cual llegó, y compáralo con v1 en tiempo constante.

Node.js (Express)

import crypto from "node:crypto";
import express from "express";

const SECRETO = process.env.TRAZZA_WEBHOOK_SECRET; // whsec_…
const VENTANA_SEGUNDOS = 300;

function firmaValida(cabecera, cuerpo) {
  const partes = Object.fromEntries(
    String(cabecera ?? "").split(",").map((p) => p.trim().split("=", 2)),
  );
  const t = partes.t;
  if (!/^\d+$/.test(t ?? "") || !partes.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > VENTANA_SEGUNDOS) return false;
  const esperada = crypto.createHmac("sha256", SECRETO).update(`${t}.${cuerpo}`).digest();
  const recibida = Buffer.from(partes.v1, "hex");
  return recibida.length === esperada.length && crypto.timingSafeEqual(recibida, esperada);
}

const app = express();

// El cuerpo CRUDO: volver a serializar el JSON cambia los bytes y la firma no casa.
app.post("/webhooks/trazza", express.raw({ type: "application/json" }), async (req, res) => {
  const cuerpo = req.body.toString("utf8");
  if (!firmaValida(req.get("X-Trazza-Signature-256"), cuerpo)) return res.sendStatus(401);

  const evento = JSON.parse(cuerpo);
  if (await yaProcesado(evento.id)) return res.sendStatus(200); // idempotencia
  await guardarComoProcesado(evento.id);

  if (evento.event === "material.cargado_en_orden") {
    // Imputar evento.data.lines a la orden evento.data.order en tu programa.
  }
  res.sendStatus(200);
});

PHP

<?php
$secreto  = getenv('TRAZZA_WEBHOOK_SECRET'); // whsec_…
$cuerpo   = file_get_contents('php://input'); // cuerpo crudo
$cabecera = $_SERVER['HTTP_X_TRAZZA_SIGNATURE_256'] ?? '';

$partes = [];
foreach (explode(',', $cabecera) as $par) {
    [$clave, $valor] = array_pad(explode('=', trim($par), 2), 2, '');
    $partes[$clave] = $valor;
}
$t  = $partes['t'] ?? '';
$v1 = $partes['v1'] ?? '';

if (!ctype_digit($t) || abs(time() - (int) $t) > 300) {
    http_response_code(401);
    exit;
}
$esperada = hash_hmac('sha256', $t . '.' . $cuerpo, $secreto);
if (!hash_equals($esperada, $v1)) {
    http_response_code(401);
    exit;
}

$evento = json_decode($cuerpo, true);
// Idempotencia: si $evento['id'] ya está procesado, responde 200 y sal.
http_response_code(200);

Python

import hashlib
import hmac
import time

def firma_valida(cabecera: str, cuerpo: bytes, secreto: str, ventana: int = 300) -> bool:
    partes = dict(p.strip().split("=", 1) for p in cabecera.split(",") if "=" in p)
    t, v1 = partes.get("t", ""), partes.get("v1", "")
    if not t.isdigit() or abs(time.time() - int(t)) > ventana:
        return False
    esperada = hmac.new(secreto.encode(), t.encode() + b"." + cuerpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, v1)

El caso típico de un taller: el material se escanea en el almacén contra la orden de trabajo, y el programa de gestión lo necesita en la orden para facturarlo.

Dar de alta órdenes, productos o tarifas en TRAZZA desde tu programa no forma parte de la API estándar: es trabajo a medida y se diseña con cada integrador. Escríbenos a info@newtex.es con lo que necesitas conectar.