Conecta cualquier sistema con DerLabs

Autenticación

El dueño del negocio crea la clave en la Oficina, en Integraciones. La clave se muestra una sola vez; DerLabs guarda solo una huella cifrada, así que si la pierdes, crea otra y revoca la anterior.

Authorization: Bearer dlk_live_…
Content-Type: application/json

URL base: https://derlabs.cl/api/v1. Úsala solo desde tu servidor: la clave nunca debe ir en una página web ni en una app instalada.

Comprueba la clave y devuelve el negocio al que pertenece.

Pedidos

Crea un pedido. El total se calcula en DerLabs a partir de los items. Envía externalId (tu id) o el encabezado Idempotency-Key para que un reintento nunca duplique el pedido.

curl -X POST https://derlabs.cl/api/v1/pedidos \
  -H "Authorization: Bearer $DERLABS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-10482" \
  -d '{
    "externalId": "10482",
    "origen": "Mi web",
    "tipo": "delivery",
    "pagado": true,
    "cliente": { "nombre": "Camila Rojas", "telefono": "+56912345678",
                 "direccion": "Av. Italia 1234", "comuna": "Providencia" },
    "items": [ { "nombre": "Torta tres leches 20 personas", "cantidad": 1, "precio": 38000 } ],
    "costoDelivery": 4000,
    "fechaEntrega": "2026-12-05",
    "notas": "Escribir Feliz cumpleaños Sofía"
  }'

Lista los pedidos recientes (máximo 90 días y 100 resultados).

Cambia el estado: preparacion, camino, listo o cancelado.

{ "estado": "listo" }

Clientes

Crea o actualiza un cliente por su teléfono. Sirve para traer tu base de clientes y usarla en campañas y saludos de cumpleaños.

{ "telefono": "+56912345678", "nombre": "Camila Rojas", "email": "camila@correo.cl",
  "cumpleanos": "08-21", "notas": "Prefiere sin lactosa", "optOut": false }

Devuelve clientes con sus compras y total gastado.

Webhooks

DerLabs envía un POST JSON a tu URL cuando ocurre un evento. Configúralos en la Oficina o con la API (máximo 5 por negocio, solo https público).

{ "url": "https://tu-sistema.cl/derlabs", "eventos": ["pedido.creado", "cliente.nuevo"] }

La respuesta incluye el secreto del webhook, que se muestra una sola vez.

Verificar la firma

Cada aviso trae X-DerLabs-Signature: t=<unix>,v1=<hex>, donde v1 es HMAC-SHA256 del secreto sobre t + "." + cuerpo. Rechaza avisos con más de 5 minutos de antigüedad y usa X-DerLabs-Delivery para no procesar dos veces el mismo.

import crypto from "node:crypto";

function avisoValido(cuerpo, firma, secreto) {
  const { t, v1 } = Object.fromEntries(firma.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const esperado = crypto.createHmac("sha256", secreto).update(t + "." + cuerpo).digest("hex");
  return v1.length === esperado.length &&
         crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}

Responde con un código 2xx en menos de 8 segundos. Si falla, reintentamos a los 1, 5, 15, 60, 180 y 600 minutos; tras 25 fallas seguidas el webhook se pausa.

Errores y límites

Los errores responden { "ok": false, "error": { "codigo", "mensaje" } }.