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);
}"""Python 3.8+, solo biblioteca estandar. Valida un pedido COD (datos ficticios)."""
import hashlib
import hmac
import json
import os
import time
import urllib.error
import urllib.request
import uuid
BASE_URL = os.environ.get("VALIDATA_BASE_URL") # URL base de tu entorno (aun no hay uno publico)
KEY_ID = os.environ.get("VALIDATA_KEY_ID")
SECRET = os.environ.get("VALIDATA_SIGNING_SECRET") # nunca en el navegador ni en un LLM
def sign(secret: str, timestamp: str, raw_body: str) -> str:
mac = hmac.new(secret.encode(), f"{timestamp}.{raw_body}".encode(), hashlib.sha256)
return "v1=" + mac.hexdigest()
def validate_order(order: dict, idempotency_key: str = None):
raw_body = json.dumps(order, ensure_ascii=False, separators=(",", ":")) # se firman estos bytes
timestamp = str(int(time.time()))
req = urllib.request.Request(
f"{BASE_URL}/v1/channel/validations",
data=raw_body.encode("utf-8"),
method="POST",
headers={
"Content-Type": "application/json",
"Idempotency-Key": idempotency_key or f"ord-{order['external_order_ref']}-{uuid.uuid4()}",
"X-Validata-Key-Id": KEY_ID,
"X-Validata-Timestamp": timestamp,
"X-Validata-Signature": sign(SECRET, timestamp, raw_body),
},
)
try:
with urllib.request.urlopen(req, timeout=20) as res:
return res.status, json.load(res)
except urllib.error.HTTPError as err:
return err.code, json.load(err)<?php
// PHP >= 7.4 con la extension curl. Valida un pedido COD (datos ficticios).
function validata_sign( string $secret, string $timestamp, string $raw_body ): string {
return 'v1=' . hash_hmac( 'sha256', $timestamp . '.' . $raw_body, $secret );
}
/**
* Construye la solicitud firmada. Se firman exactamente los bytes enviados (JSON_UNESCAPED_*).
*
* @return array{0:string,1:array<int,string>,2:string} URL, cabeceras y cuerpo crudo.
*/
function validata_build_request( array $order, string $base_url, string $key_id, string $secret, string $idempotency_key, string $timestamp ): array {
$raw_body = json_encode( $order, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES );
$headers = array(
'Content-Type: application/json',
'Idempotency-Key: ' . $idempotency_key,
'X-Validata-Key-Id: ' . $key_id,
'X-Validata-Timestamp: ' . $timestamp,
'X-Validata-Signature: ' . validata_sign( $secret, $timestamp, $raw_body ),
);
return array( $base_url . '/v1/channel/validations', $headers, $raw_body );
}
function validata_validate_order( array $order, string $base_url, string $key_id, string $secret, ?string $idempotency_key = null ): array {
$key = $idempotency_key ?? ( 'ord-' . $order['external_order_ref'] . '-' . bin2hex( random_bytes( 8 ) ) );
list( $url, $headers, $raw_body ) = validata_build_request( $order, $base_url, $key_id, $secret, $key, (string) time() );
$ch = curl_init( $url );
curl_setopt_array( $ch, array(
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $raw_body,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 20,
CURLOPT_HTTPHEADER => $headers,
) );
$response = curl_exec( $ch );
$status = (int) curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );
return array( $status, json_decode( (string) $response, true ) );
}#!/bin/sh
# cURL + openssl. Datos ficticios. Requiere VALIDATA_BASE_URL, VALIDATA_KEY_ID, VALIDATA_SIGNING_SECRET.
set -eu
BODY='{"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"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$VALIDATA_SIGNING_SECRET" -hex | sed 's/^.* //')
curl -sS -X POST "$VALIDATA_BASE_URL/v1/channel/validations" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: ord-ORD-1001-$(date +%s)-demo" \
-H "X-Validata-Key-Id: $VALIDATA_KEY_ID" \
-H "X-Validata-Timestamp: $TS" \
-H "X-Validata-Signature: v1=$SIG" \
--data-binary "$BODY"Solicitud HTTP cruda#
### 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.