VALIDATA Developers

Herramientas

Ejemplos de código

Todos los ejemplos usan datos ficticios (+57 300 000 0000, Calle 00 # 00-00) y leen las credenciales del entorno. Se prueban automáticamente contra los vectores de firma oficiales.

Validar un pedido#

// Node.js ≥ 18, sin dependencias. Valida un pedido COD (datos ficticios).
import { createHmac, randomUUID } from "node:crypto";

const BASE_URL = process.env.VALIDATA_BASE_URL; // URL base de tu entorno (aún no hay uno público)
const KEY_ID = process.env.VALIDATA_KEY_ID;
const SECRET = process.env.VALIDATA_SIGNING_SECRET; // nunca en el navegador ni en un LLM

export function sign(secret, timestamp, rawBody) {
  return "v1=" + createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
}

export async function validateOrder(order, idempotencyKey = `ord-${order.external_order_ref}-${randomUUID()}`) {
  const rawBody = JSON.stringify(order); // firma EXACTAMENTE estos bytes
  const timestamp = String(Math.floor(Date.now() / 1000));
  const res = await fetch(`${BASE_URL}/v1/channel/validations`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
      "X-Validata-Key-Id": KEY_ID,
      "X-Validata-Timestamp": timestamp,
      "X-Validata-Signature": sign(SECRET, timestamp, rawBody),
    },
    body: rawBody,
  });
  return { status: res.status, body: await res.json(), idempotencyKey };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const { status, body } = await validateOrder({
    schema_version: "channel.validation.v1",
    channel: "whatsapp",
    external_order_ref: "ORD-1001",
    buyer: { phone: "+57 300 000 0000" },
    delivery: { mode: "HOME_DELIVERY", country: "CO", department: "Cundinamarca", city: "Bogotá", address_line: "Calle 00 # 00-00" },
    order: { total: "120000", currency: "COP", payment_intent: "cod" },
    event_at: new Date().toISOString().replace(/\.\d+Z$/, "Z"),
  });
  console.log(status, body.next_action ?? body.error);
}

Solicitud HTTP cruda#

HTTP
### Validacion sintetica (variables: base_url, key_id, timestamp, signature, idempotency_key)
### La firma es HMAC-SHA256(secreto, "<timestamp>.<cuerpo_crudo>") en hex, con prefijo v1=
POST {{base_url}}/v1/channel/validations
Content-Type: application/json
Idempotency-Key: {{idempotency_key}}
X-Validata-Key-Id: {{key_id}}
X-Validata-Timestamp: {{timestamp}}
X-Validata-Signature: {{signature}}

{"schema_version":"channel.validation.v1","channel":"whatsapp","external_order_ref":"ORD-1001","buyer":{"phone":"+57 300 000 0000"},"delivery":{"mode":"HOME_DELIVERY","country":"CO","department":"Cundinamarca","city":"Bogotá","address_line":"Calle 00 # 00-00"},"order":{"total":"120000","currency":"COP","payment_intent":"cod"},"event_at":"2026-10-19T15:00:00Z"}

### Readback (solo lectura) de una Idempotency-Key de esta integracion. Cuerpo vacio: se firma "<timestamp>."
GET {{base_url}}/v1/channel/validations/readback
Idempotency-Key: {{idempotency_key}}
X-Validata-Key-Id: {{key_id}}
X-Validata-Timestamp: {{timestamp}}
X-Validata-Signature: {{signature_readback}}

Probar tu firma#

Usa el secreto sintético de los vectores (WlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlpaWlo) y compara tu resultado con los casos del archivo channel.v1.vectors.json.