{
  "openapi": "3.1.0",
  "info": {
    "title": "VALIDATA Channel API",
    "version": "1.0.0-preview",
    "summary": "Validación de pedidos contraentrega (COD) para chatbots, agentes de IA y plataformas.",
    "description": "VISTA PREVIA. Este contrato está probado en un entorno interno; todavía no existe un entorno público ni credenciales autoemitibles. Documentación: https://validatapp.com/docs"
  },
  "servers": [
    {
      "url": "{base_url}",
      "description": "Marcador: aún no hay un entorno público. Sustituye base_url por la URL que se te indique.",
      "variables": {
        "base_url": {
          "default": "https://base-url-pendiente.invalid"
        }
      }
    }
  ],
  "security": [
    {
      "signed": []
    },
    {
      "staticBearer": []
    }
  ],
  "paths": {
    "/v1/channel/validations": {
      "post": {
        "operationId": "createValidation",
        "summary": "Valida un pedido COD",
        "description": "Scope validations:write. Cuerpo máximo 16 KB. Plazo de decisión: whatsapp 15 s; woocommerce 3,5 s (1,5–5,5 s con X-Validata-Deadline-Ms).",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:-]{15,127}$"
            },
            "description": "Una clave por pedido. Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta original sin cobrar."
          },
          {
            "name": "X-Validata-Deadline-Ms",
            "in": "header",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 999999
            },
            "description": "Solo woocommerce: acorta el plazo (se acota a 1500–5500)."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Decisión (o INVALID_PHONE).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "400": {
            "description": "INVALID_REQUEST, UNKNOWN_FIELD, FORBIDDEN_FIELD, IDEMPOTENCY_KEY_REQUIRED, MALFORMED_HEADER",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "INVALID_CREDENTIALS, SIGNATURE_INVALID, TIMESTAMP_OUT_OF_WINDOW",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "INTEGRATION_REVOKED, INSUFFICIENT_SCOPE, CHANNEL_NOT_ENABLED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "METHOD_NOT_ALLOWED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "IDEMPOTENCY_CONFLICT (no reintentar) u OPERATION_PENDING (consultar el readback)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "PAYLOAD_TOO_LARGE",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "UNSUPPORTED_MEDIA_TYPE",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "423": {
            "description": "VALIDATIONS_EXHAUSTED: cupo agotado",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Segundos a esperar."
              }
            }
          },
          "503": {
            "description": "SERVICE_UNAVAILABLE: reintentar con la misma Idempotency-Key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/channel/validations/readback": {
      "get": {
        "operationId": "readbackValidation",
        "summary": "Consulta la respuesta sellada de una Idempotency-Key de tu integración",
        "description": "Scope validations:read. Sin cuerpo (se firma «<timestamp>.»). No ejecuta ni cobra.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9._~:-]{15,127}$"
            },
            "description": "Una clave por pedido. Reintentar con la misma clave y el mismo cuerpo devuelve la respuesta original sin cobrar."
          }
        ],
        "responses": {
          "200": {
            "description": "Respuesta original con consumption.state=REPLAY_NOT_CHARGED.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationResult"
                }
              }
            }
          },
          "401": {
            "description": "Credencial o firma inválida",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Integración revocada o sin scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "RESOURCE_NOT_FOUND (también si la clave es de otra integración)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "OPERATION_PENDING",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "RATE_LIMITED",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "signed": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Validata-Signature",
        "description": "Perfil firmado. Además: X-Validata-Key-Id y X-Validata-Timestamp (10 dígitos). Firma = 'v1=' + hex(HMAC-SHA256(secreto, '<timestamp>.<cuerpo crudo>')). Ventana ±300 s. Obligatorio para woocommerce."
      },
      "staticBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Perfil estático: Authorization: Bearer vdk_<key_id>.<secreto>. Solo canal whatsapp."
      }
    },
    "schemas": {
      "ValidationRequest": {
        "title": "channel.validation.v1",
        "description": "Solicitud de validación COD. Contrato cerrado: no se aceptan campos desconocidos ni claves de identidad, política o datos personales innecesarios (ver docs).",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schema_version",
          "channel",
          "external_order_ref",
          "buyer",
          "delivery",
          "order",
          "event_at"
        ],
        "properties": {
          "schema_version": {
            "const": "channel.validation.v1"
          },
          "channel": {
            "enum": [
              "whatsapp",
              "woocommerce"
            ]
          },
          "external_order_ref": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
            "minLength": 1,
            "maxLength": 128
          },
          "buyer": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "phone"
            ],
            "properties": {
              "phone": {
                "type": "string",
                "pattern": "^[0-9+()\\s.-]{7,32}$",
                "minLength": 7,
                "maxLength": 32
              }
            }
          },
          "delivery": {
            "oneOf": [
              {
                "title": "HOME_DELIVERY",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "mode",
                  "country",
                  "department",
                  "city",
                  "address_line"
                ],
                "properties": {
                  "mode": {
                    "const": "HOME_DELIVERY"
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$"
                  },
                  "department": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "city": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "address_line": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  },
                  "complement": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200
                  }
                }
              },
              {
                "title": "OFFICE_PICKUP",
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "mode",
                  "country",
                  "office_ref"
                ],
                "properties": {
                  "mode": {
                    "const": "OFFICE_PICKUP"
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$"
                  },
                  "office_ref": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
                    "minLength": 1,
                    "maxLength": 128
                  }
                }
              }
            ]
          },
          "order": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "total",
              "currency",
              "payment_intent"
            ],
            "properties": {
              "total": {
                "type": "string",
                "pattern": "^(?:0|[1-9][0-9]{0,11})(?:\\.[0-9]{1,4})?$",
                "maxLength": 17
              },
              "currency": {
                "enum": [
                  "ARS",
                  "AUD",
                  "BRL",
                  "CAD",
                  "CHF",
                  "CLP",
                  "COP",
                  "EUR",
                  "GBP",
                  "JPY",
                  "MXN",
                  "PEN",
                  "USD"
                ]
              },
              "payment_intent": {
                "enum": [
                  "cod",
                  "prepaid",
                  "partial"
                ]
              },
              "items": {
                "type": "array",
                "maxItems": 50,
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "sku_ref",
                    "quantity"
                  ],
                  "properties": {
                    "sku_ref": {
                      "type": "string",
                      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "quantity": {
                      "type": "integer",
                      "minimum": 1,
                      "maximum": 999
                    }
                  }
                }
              }
            }
          },
          "event_at": {
            "type": "string",
            "pattern": "^[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\\.[0-9]{1,6})?Z$",
            "maxLength": 27
          },
          "trace": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "conversation_ref": {
                "type": "string",
                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$",
                "minLength": 1,
                "maxLength": 128
              }
            }
          }
        }
      },
      "ValidationResult": {
        "title": "channel.validation.result.v1",
        "description": "Respuesta de validación COD. Los clientes deben ignorar campos desconocidos y tratar enumeraciones desconocidas con seguridad.",
        "type": "object",
        "required": [
          "schema_version",
          "validation_ref",
          "audit_ref",
          "external_order_ref",
          "status",
          "core",
          "fingerprint",
          "address",
          "merchant_policy",
          "next_action",
          "buyer_message_key",
          "consumption",
          "idempotency"
        ],
        "properties": {
          "schema_version": {
            "const": "channel.validation.result.v1"
          },
          "validation_ref": {
            "type": "string"
          },
          "audit_ref": {
            "type": "string"
          },
          "external_order_ref": {
            "type": "string"
          },
          "status": {
            "enum": [
              "DECIDED",
              "INVALID_PHONE"
            ]
          },
          "core": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "action",
                  "reason_code",
                  "rule_version_ref"
                ],
                "properties": {
                  "action": {
                    "enum": [
                      "ALLOW_COD",
                      "REQUIRE_FREIGHT",
                      "REQUIRE_PREPAID",
                      "EXTRA_CONFIRMATION",
                      "MANUAL_REVIEW",
                      "WARN"
                    ]
                  },
                  "reason_code": {
                    "type": "string"
                  },
                  "rule_version_ref": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "fingerprint": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "level",
                  "category",
                  "policy_version",
                  "evidence_state"
                ],
                "properties": {
                  "level": {
                    "enum": [
                      "nuevo",
                      "bueno",
                      "con_devoluciones",
                      "alto_riesgo",
                      null
                    ]
                  },
                  "category": {
                    "enum": [
                      "NO_HISTORY",
                      "INSUFFICIENT_HISTORY",
                      "CRITICAL",
                      "EXCELLENT",
                      "GOOD",
                      "REGULAR",
                      "RISKY"
                    ]
                  },
                  "policy_version": {
                    "type": "string"
                  },
                  "evidence_state": {
                    "enum": [
                      "VALIDATED",
                      "DEGRADED",
                      "NO_SOURCES"
                    ]
                  }
                }
              }
            ]
          },
          "address": {
            "type": "object",
            "required": [
              "gate",
              "validator"
            ],
            "properties": {
              "gate": {
                "enum": [
                  "NOT_VALIDATED",
                  "HOME_PASS",
                  "PICKUP_VALIDATED",
                  "SKIPPED_BY_POLICY",
                  "BLOCKED"
                ]
              },
              "validator": {
                "enum": [
                  "none",
                  "office_collection"
                ]
              }
            }
          },
          "merchant_policy": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "type": "object",
                "required": [
                  "effect",
                  "version_ref"
                ],
                "properties": {
                  "effect": {
                    "enum": [
                      "CONTINUE_COD_SUBJECT_TO_GATES",
                      "REQUIRE_FREIGHT",
                      "REQUIRE_PREPAID",
                      "EXTRA_CONFIRMATION",
                      "HUMAN_CONTROL"
                    ]
                  },
                  "version_ref": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "next_action": {
            "enum": [
              "CONTINUE_COD",
              "CONFIRM_ADDRESS_VIA_CHAT",
              "OFFER_FREIGHT_ADVANCE",
              "REQUIRE_PREPAID",
              "EXTRA_CONFIRMATION",
              "HANDOFF_TO_HUMAN",
              "ASK_VALID_PHONE"
            ]
          },
          "buyer_message_key": {
            "type": "string"
          },
          "consumption": {
            "type": "object",
            "required": [
              "state",
              "meter"
            ],
            "properties": {
              "state": {
                "enum": [
                  "CONSUMED",
                  "ALREADY_COUNTED",
                  "REPLAY_NOT_CHARGED",
                  "NOT_CHARGED_INVALID_PHONE"
                ]
              },
              "meter": {
                "const": "huella_validations"
              }
            }
          },
          "idempotency": {
            "type": "object",
            "required": [
              "replayed"
            ],
            "properties": {
              "replayed": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "Error": {
        "title": "channel.error.v1",
        "type": "object",
        "required": [
          "schema_version",
          "error",
          "correlation_ref"
        ],
        "properties": {
          "schema_version": {
            "const": "channel.error.v1"
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "retry_class"
            ],
            "properties": {
              "code": {
                "enum": [
                  "INVALID_REQUEST",
                  "UNKNOWN_FIELD",
                  "FORBIDDEN_FIELD",
                  "IDEMPOTENCY_KEY_REQUIRED",
                  "MALFORMED_HEADER",
                  "INVALID_CREDENTIALS",
                  "SIGNATURE_INVALID",
                  "TIMESTAMP_OUT_OF_WINDOW",
                  "INTEGRATION_REVOKED",
                  "INSUFFICIENT_SCOPE",
                  "CHANNEL_NOT_ENABLED",
                  "RESOURCE_NOT_FOUND",
                  "METHOD_NOT_ALLOWED",
                  "IDEMPOTENCY_CONFLICT",
                  "OPERATION_PENDING",
                  "PAYLOAD_TOO_LARGE",
                  "UNSUPPORTED_MEDIA_TYPE",
                  "VALIDATIONS_EXHAUSTED",
                  "RATE_LIMITED",
                  "SERVICE_UNAVAILABLE"
                ]
              },
              "retry_class": {
                "enum": [
                  "DO_NOT_RETRY",
                  "RETRY_SAME_KEY",
                  "RETRY_AFTER",
                  "POLL_READBACK_ONLY"
                ]
              },
              "field": {
                "type": "string"
              }
            }
          },
          "correlation_ref": {
            "type": "string"
          }
        },
        "x-http-status": {
          "INVALID_REQUEST": 400,
          "UNKNOWN_FIELD": 400,
          "FORBIDDEN_FIELD": 400,
          "IDEMPOTENCY_KEY_REQUIRED": 400,
          "MALFORMED_HEADER": 400,
          "INVALID_CREDENTIALS": 401,
          "SIGNATURE_INVALID": 401,
          "TIMESTAMP_OUT_OF_WINDOW": 401,
          "INTEGRATION_REVOKED": 403,
          "INSUFFICIENT_SCOPE": 403,
          "CHANNEL_NOT_ENABLED": 403,
          "RESOURCE_NOT_FOUND": 404,
          "METHOD_NOT_ALLOWED": 405,
          "IDEMPOTENCY_CONFLICT": 409,
          "OPERATION_PENDING": 409,
          "PAYLOAD_TOO_LARGE": 413,
          "UNSUPPORTED_MEDIA_TYPE": 415,
          "VALIDATIONS_EXHAUSTED": 423,
          "RATE_LIMITED": 429,
          "SERVICE_UNAVAILABLE": 503
        },
        "x-retry-class": {
          "INVALID_REQUEST": "DO_NOT_RETRY",
          "UNKNOWN_FIELD": "DO_NOT_RETRY",
          "FORBIDDEN_FIELD": "DO_NOT_RETRY",
          "IDEMPOTENCY_KEY_REQUIRED": "DO_NOT_RETRY",
          "MALFORMED_HEADER": "DO_NOT_RETRY",
          "INVALID_CREDENTIALS": "DO_NOT_RETRY",
          "SIGNATURE_INVALID": "DO_NOT_RETRY",
          "TIMESTAMP_OUT_OF_WINDOW": "DO_NOT_RETRY",
          "INTEGRATION_REVOKED": "DO_NOT_RETRY",
          "INSUFFICIENT_SCOPE": "DO_NOT_RETRY",
          "CHANNEL_NOT_ENABLED": "DO_NOT_RETRY",
          "RESOURCE_NOT_FOUND": "DO_NOT_RETRY",
          "METHOD_NOT_ALLOWED": "DO_NOT_RETRY",
          "IDEMPOTENCY_CONFLICT": "DO_NOT_RETRY",
          "OPERATION_PENDING": "POLL_READBACK_ONLY",
          "PAYLOAD_TOO_LARGE": "DO_NOT_RETRY",
          "UNSUPPORTED_MEDIA_TYPE": "DO_NOT_RETRY",
          "VALIDATIONS_EXHAUSTED": "DO_NOT_RETRY",
          "RATE_LIMITED": "RETRY_AFTER",
          "SERVICE_UNAVAILABLE": "RETRY_SAME_KEY"
        }
      }
    }
  }
}
