Customs Declaration Overview

Compare every order a customs pipeline assembled with the filed declaration and read the clerk's seven blocking checks over the /v1/customs-declaration API.

The Customs Declaration API compares every order a customs pipeline assembled with the declaration that was filed for it in the workspace's own system, field by field, and runs the clerk's blocking checks on each order. An order is identified by its LRN (local reference number): the pipeline groups the documents of one LRN, composes one record from them, and the API reads that record against the matching row of a reference table. The endpoints belong to the Customs Declaration app (catalog slug customs-declaration); a workspace uses them after adding the app, and GET /v1/apps lists a workspace's apps by slug.

The surface is read-only. It reports where the extracted data and the filed declaration disagree and which checks fail, and it changes nothing. Review happens in the pipeline's data product in Review Mode (/delivery/data-products/{id}?review=<document>:<field>). data_product_id on the list response names that data product.

A pipeline is eligible when its Spec has a validation stage that compares with a reference table (the filed declarations): the stage names the reference table, the match key that pairs an order with its filed row (the LRN by default), and the field mappings that say which extracted field compares with which column. The engine uses exactly the stage's mappings, so the API and the stage never disagree on which fields compare. GET /v1/customs-declaration/pipelines lists the eligible pipelines, and the other two routes take one of them as pipeline_id.

Orders and their documents are read as the key's minting user may see them under Sources IAM, and records held back for review are not included. All three routes need the read scope; none of them writes, so a key minted by a viewer can use them. The surface needs a workspace-scoped credential.

The Seven Blocking Checks

Every order carries the same seven checks in checks[], each with a status of pass, fail or na (not applicable, when the data the check needs is absent). An order is ready when no check failed. A failed check sets message, and fields names the field keys the check concerns.

• required: the required fields are present (gross weight, package count, sender, receiver, departure and destination office codes, and plates).
• tariff: the tariff code needs no confirmation. The check fails when no code was found, or when the code was proposed from the customer's history instead of read from the documents.
• multi-cmr: the order has a single CMR. Two or more different CMR numbers fail it, because every CMR is filed as its own consignment.
• weight-agree: the order weight agrees with the CMR and order-request documents within 3 %. Delivery notes and certificates carry part weights and are not compared.
• packages-agree: the package count agrees with the CMR and order-request documents.
• packages-fit: the packages fit one truck, at most 66 packages or 34 pallets (package type code PX).
• weight-plausible: the weight is between 50 and 44,000 kg.

Numbers are compared as written. A weight such as 24.130,000 kg or 6741,261 has more than one plausible reading, so a check passes when any reading agrees, and a value given in tonnes is read as kilograms. The wording of message and title is English.

Worked Example: From Pipeline to Worklist

curl "https://api.talonic.com/v1/customs-declaration/pipelines" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

curl "https://api.talonic.com/v1/customs-declaration/declarations?pipeline_id=$PIPELINE_ID&status=review" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

The worklist route returns only the orders that are not ready, each with the checks that failed and the fields where the extracted value differs from the filed one or is missing, which is the short list a clerk works through.

curl "https://api.talonic.com/v1/customs-declaration/issues?pipeline_id=$PIPELINE_ID" \
  -H "Authorization: Bearer $TALONIC_API_KEY"