API
Validaciones COD
POST /v1/channel/validationsValida un pedido COD y devuelve qué hacer con él. Requiere el scope validations:write.
Cabeceras#
| Cabecera | Obligatoria | Notas |
|---|---|---|
Content-Type: application/json | Sí | Otro tipo: 415. |
Idempotency-Key | Sí | Una por pedido. Ver Idempotencia. |
| Credencial | Sí | Ver Autenticación. |
X-Validata-Deadline-Ms | No | Solo WooCommerce: acota la espera (1500–5500 ms). |
Cuerpo máximo: 16 KB (413).
Solicitud channel.validation.v1#
Es un contrato cerrado: un campo desconocido devuelve 400 UNKNOWN_FIELD.
| Campo | Tipo | Reglas |
|---|---|---|
schema_version | string | Exactamente channel.validation.v1. |
channel | string | whatsapp o woocommerce; debe coincidir con tu credencial (si no, 403 CHANNEL_NOT_ENABLED). |
external_order_ref | string | Tu referencia del pedido, 1–128 caracteres [A-Za-z0-9._:-], sin datos personales. |
buyer.phone | string | 7–32 caracteres (0-9 + ( ) . - espacio). Se normaliza con el indicativo del comercio. |
delivery | objeto | Ver abajo. |
order.total | string | Decimal como texto: hasta 12 enteros y 4 decimales, p. ej. "120000" o "99.90". |
order.currency | string | ARS AUD BRL CAD CHF CLP COP EUR GBP JPY MXN PEN USD. |
order.payment_intent | string | cod, prepaid o partial. |
order.items | arreglo | Opcional, máximo 50: { sku_ref, quantity (1–999) }. |
event_at | string | Fecha UTC con Z, p. ej. 2026-10-19T15:00:00Z. |
trace.conversation_ref | string | Opcional; referencia opaca, no el texto de la conversación. |
delivery tiene dos formas, que no se pueden mezclar:
HOME_DELIVERY:mode,country(2 letras mayúsculas),department,city,address_line,complementopcional.OFFICE_PICKUP:mode,country,office_ref. No acepta campos de dirección.
Ejemplos#
// 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"Respuesta channel.validation.result.v1#
{
"schema_version": "channel.validation.result.v1",
"validation_ref": "val_ejemplo",
"audit_ref": "aud_ejemplo",
"external_order_ref": "ORD-1001",
"status": "DECIDED",
"core": { "action": "ALLOW_COD", "reason_code": "EJEMPLO", "rule_version_ref": "regla-ejemplo" },
"fingerprint": { "level": "nuevo", "category": "NO_HISTORY", "policy_version": "politica-ejemplo", "evidence_state": "NO_SOURCES" },
"address": { "gate": "HOME_PASS", "validator": "none" },
"merchant_policy": { "effect": "CONTINUE_COD_SUBJECT_TO_GATES", "version_ref": "politica-comercio-ejemplo" },
"next_action": "CONTINUE_COD",
"buyer_message_key": "COD_AVAILABLE_PENDING_GATES",
"consumption": { "state": "CONSUMED", "meter": "huella_validations" },
"idempotency": { "replayed": false }
}| Campo | Significado |
|---|---|
status | DECIDED o INVALID_PHONE (core, fingerprint y merchant_policy son null). |
validation_ref, audit_ref | Referencias para soporte y auditoría. Guárdalas. |
core.action | Decisión original: ALLOW_COD, REQUIRE_FREIGHT, REQUIRE_PREPAID, EXTRA_CONFIRMATION, MANUAL_REVIEW, WARN. |
next_action | Lo que debes hacer. Ver tabla. |
buyer_message_key | Clave del tipo de mensaje para el comprador. |
consumption.state | CONSUMED, ALREADY_COUNTED, REPLAY_NOT_CHARGED, NOT_CHARGED_INVALID_PHONE. |
idempotency.replayed | true si es la réplica de una solicitud anterior. |
next_action#
| Valor | Qué hace tu sistema |
|---|---|
CONTINUE_COD | Continuar con el pedido contraentrega. |
CONFIRM_ADDRESS_VIA_CHAT | Pedir al comprador que confirme o complete la dirección. |
OFFER_FREIGHT_ADVANCE | Ofrecer el abono del flete. |
REQUIRE_PREPAID | Exigir pago anticipado. |
EXTRA_CONFIRMATION | Pedir una confirmación adicional (por ejemplo, de un asesor). |
HANDOFF_TO_HUMAN | Pasar el caso a una persona. |
ASK_VALID_PHONE | Pedir otro número de teléfono. |