API
Autenticación
Cada integración (un comercio conectando un canal) tiene su propia credencial. No existe una clave global de cuenta. Hay dos perfiles; el de tu credencial lo fija VALIDATA al crearla.
Perfil signed (recomendado)#
Obligatorio para WooCommerce. Tres cabeceras:
| Cabecera | Valor |
|---|---|
X-Validata-Key-Id | 16 caracteres [a-z0-9] |
X-Validata-Timestamp | Segundos Unix, exactamente 10 dígitos |
X-Validata-Signature | v1= + HMAC-SHA256 en hexadecimal minúscula |
La firma es:
HMAC-SHA256(secreto, "<timestamp>." + <cuerpo crudo>)- Se firman los bytes exactos que envías, incluidos espacios y saltos de línea. Si tu cliente re-serializa el JSON, la firma falla.
- En el
GETde readback el cuerpo está vacío: se firma"<timestamp>.". - El secreto tiene 43 caracteres base64url. La ventana de tiempo es de ±300 segundos (
TIMESTAMP_OUT_OF_WINDOW). - Los vectores oficiales incluyen casos con UTF-8, barras escapadas y cuerpo vacío para probar tu implementación.
Perfil static#
Para bots sin código que solo permiten cabeceras fijas:
Authorization: Bearer vdk_<key_id>.<secreto>Es menos seguro (el secreto viaja en cada llamada y no protege contra repetición). Úsalo solo si tu plataforma no puede firmar, y no lo uses con WooCommerce.
Scopes#
| Scope | Permite |
|---|---|
validations:write | POST /v1/channel/validations |
validations:read | GET /v1/channel/validations/readback |
Sin el scope necesario: 403 INSUFFICIENT_SCOPE.
Errores de autenticación#
| Código | HTTP | Cuándo |
|---|---|---|
INVALID_CREDENTIALS | 401 | Falta la credencial, o es desconocida. No revela si el key_id existe. |
SIGNATURE_INVALID | 401 | La firma no coincide. |
TIMESTAMP_OUT_OF_WINDOW | 401 | Reloj desfasado más de 300 s. |
MALFORMED_HEADER | 400 | Formato de cabecera inválido. |
INTEGRATION_REVOKED | 403 | La integración fue revocada. |
Cómo obtener credenciales: Futuro — hoy no se autoemiten; ver Inicio rápido.