VALIDATA Developers

API

Validaciones COD

POST /v1/channel/validations

Valida un pedido COD y devuelve qué hacer con él. Requiere el scope validations:write.

Cabeceras#

CabeceraObligatoriaNotas
Content-Type: application/jsonSíOtro tipo: 415.
Idempotency-KeySíUna por pedido. Ver Idempotencia.
CredencialSíVer Autenticación.
X-Validata-Deadline-MsNoSolo 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.

CampoTipoReglas
schema_versionstringExactamente channel.validation.v1.
channelstringwhatsapp o woocommerce; debe coincidir con tu credencial (si no, 403 CHANNEL_NOT_ENABLED).
external_order_refstringTu referencia del pedido, 1–128 caracteres [A-Za-z0-9._:-], sin datos personales.
buyer.phonestring7–32 caracteres (0-9 + ( ) . - espacio). Se normaliza con el indicativo del comercio.
deliveryobjetoVer abajo.
order.totalstringDecimal como texto: hasta 12 enteros y 4 decimales, p. ej. "120000" o "99.90".
order.currencystringARS AUD BRL CAD CHF CLP COP EUR GBP JPY MXN PEN USD.
order.payment_intentstringcod, prepaid o partial.
order.itemsarregloOpcional, máximo 50: { sku_ref, quantity (1–999) }.
event_atstringFecha UTC con Z, p. ej. 2026-10-19T15:00:00Z.
trace.conversation_refstringOpcional; 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, complement opcional.
  • 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);
}

Respuesta channel.validation.result.v1#

200 OK (ejemplo ilustrativo)
{
  "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 }
}
CampoSignificado
statusDECIDED o INVALID_PHONE (core, fingerprint y merchant_policy son null).
validation_ref, audit_refReferencias para soporte y auditoría. Guárdalas.
core.actionDecisión original: ALLOW_COD, REQUIRE_FREIGHT, REQUIRE_PREPAID, EXTRA_CONFIRMATION, MANUAL_REVIEW, WARN.
next_actionLo que debes hacer. Ver tabla.
buyer_message_keyClave del tipo de mensaje para el comprador.
consumption.stateCONSUMED, ALREADY_COUNTED, REPLAY_NOT_CHARGED, NOT_CHARGED_INVALID_PHONE.
idempotency.replayedtrue si es la réplica de una solicitud anterior.

next_action#

ValorQué hace tu sistema
CONTINUE_CODContinuar con el pedido contraentrega.
CONFIRM_ADDRESS_VIA_CHATPedir al comprador que confirme o complete la dirección.
OFFER_FREIGHT_ADVANCEOfrecer el abono del flete.
REQUIRE_PREPAIDExigir pago anticipado.
EXTRA_CONFIRMATIONPedir una confirmación adicional (por ejemplo, de un asesor).
HANDOFF_TO_HUMANPasar el caso a una persona.
ASK_VALID_PHONEPedir otro número de teléfono.