Validation API

Validate shipment data against deterministic business rules via Rynko Flow.

info

Validation is synchronous — the response contains the full validation result. No polling required.

Validate Shipment

POST /functions/v1/validate-shipment

Request Body

Field	Type	Required	Description
shipment	object	Yes	The full shipment data object (TradeShipment). See TradeShipment Schema.
shipment_id	string	No	When provided, links the validation record to the shipment and updates the shipment's validation state (validated or validation_failed).
gate_slug	string	No	Rynko Flow gate slug to validate against. Defaults to the RYNKO_DEFAULT_GATE_ID environment variable (trade-document-validator).

Example Request

curl -X POST "https://<project-ref>.supabase.co/functions/v1/validate-shipment" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_ANON_KEY" \
  -d '{
    "shipment": {
      "exporter": { "name": "Acme Corp" },
      "importer": { "name": "Global Trade GmbH" },
      "route": {
        "origin_country": "US",
        "destination_country": "DE",
        "port_of_loading": "USLAX",
        "port_of_discharge": "DEHAM"
      },
      "goods": {
        "currency": "USD",
        "total_value": 25000,
        "line_items": [
          { "hs_code": "8542.31.0000", "quantity": 500 }
        ]
      }
    },
    "shipment_id": "uuid-1234"
  }'

Response (Pass)

{
  "run_id": "run_a1b2c3d4",
  "validation_record_id": "uuid-record-5678",
  "status": "validated",
  "passed": true,
  "layers": [
    {
      "name": "Schema Validation",
      "status": "passed",
      "results": []
    },
    {
      "name": "Business Rules",
      "status": "passed",
      "results": []
    }
  ],
  "error": null,
  "validation_hash": "a1b2c3d4e5f6789..."
}

Response (Fail)

{
  "run_id": "run_b2c3d4e5",
  "validation_record_id": "uuid-record-9012",
  "status": "validated",
  "passed": false,
  "layers": [
    {
      "name": "Schema Validation",
      "status": "passed",
      "results": []
    },
    {
      "name": "Business Rules",
      "status": "failed",
      "results": [
        {
          "rule": "hs_code_exists",
          "status": "failed",
          "message": "HS code 9999.99.9999 not found in US HTS schedule"
        },
        {
          "rule": "port_code_valid",
          "status": "failed",
          "message": "Port XXABC is not a valid UN/LOCODE"
        }
      ]
    }
  ],
  "error": {
    "message": "2 rules failed"
  },
  "validation_hash": null
}

Response Fields

Field	Type	Description
run_id	string	Rynko Flow run ID
validation_record_id	string	Klervex validation record ID (persisted in Supabase)
status	string	Rynko Flow run status (e.g., validated)
passed	boolean	Authoritative pass/fail signal. true = all rules passed, false = one or more rules failed. Do not rely on status alone.
layers	array	Validation layers with individual rule results
error	object|null	Error details when validation fails. null on pass.
validation_hash	string|null	SHA-256 hash for passing validations. Used to link validation to document generation. null on fail.

Shipment Linking

When shipment_id is provided:

1. The validation record is linked to the shipment via shipment_id
2. The shipment's status is updated to validated (pass) or validation_failed (fail)
3. On pass, the shipment's current_validation_hash is set to the new hash
4. The shipment's current_validation_record_id is updated

This allows the shipment to carry its latest validation state for the Generate stage.

Error Codes

HTTP Status	Error Code	Description
400	KLV_VAL_002	shipment payload is required