{
  "openapi": "3.1.0",
  "info": {
    "title": "Callnod Multi-Carrier Tracking API",
    "version": "2.0.0",
    "description": "Unofficial local adapters for PostEx, Leopards, TCS, BlueEX and Trax. GET /api/v1/carriers exposes verification status. Only PostEx has been verified with a supplied valid shipment. No throughput guarantees. API-key authentication is required only when configured."
  },
  "servers": [
    {
      "url": "http://127.0.0.1:8787"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    }
  },
  "security": [
    {},
    {
      "ApiKey": []
    }
  ],
  "paths": {
    "/api/v1/track/{trackingNumber}": {
      "get": {
        "operationId": "getTracking",
        "summary": "Track a shipment (PostEx by default)",
        "parameters": [
          {
            "name": "trackingNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{4,39}$",
              "example": "08640-01-090034008"
            }
          },
          {
            "name": "carrier",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "postex",
                "leopards",
                "tcs",
                "blueex",
                "trax"
              ],
              "default": "postex"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment found.",
            "headers": {
              "X-Cache": {
                "schema": {
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              },
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds remaining in the local request window."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "carrier",
                        "trackingNumber",
                        "history",
                        "latest",
                        "raw",
                        "cached",
                        "fetchedAt"
                      ],
                      "properties": {
                        "carrier": {
                          "type": "string",
                          "enum": [
                            "postex",
                            "leopards",
                            "tcs",
                            "blueex",
                            "trax"
                          ]
                        },
                        "trackingNumber": {
                          "type": "string"
                        },
                        "customerName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "orderPickupDate": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "latest": {
                          "anyOf": [
                            {
                              "type": "object",
                              "required": [
                                "code",
                                "status",
                                "timestamp"
                              ],
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "status": {
                                  "type": "string"
                                },
                                "timestamp": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                                },
                                "timestampText": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Original courier time text, retained for display when parsing is uncertain."
                                }
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "history": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "code",
                              "status",
                              "timestamp"
                            ],
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "timestamp": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                              },
                              "timestampText": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Original courier time text, retained for display when parsing is uncertain."
                              }
                            }
                          }
                        },
                        "raw": {
                          "type": "object",
                          "additionalProperties": true
                        },
                        "cached": {
                          "type": "boolean"
                        },
                        "fetchedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "verification": {
                          "type": "string",
                          "enum": [
                            "shipment_verified",
                            "invalid_response_verified",
                            "connection_unverified"
                          ]
                        },
                        "currentStatus": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "origin": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "destination": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/track": {
      "post": {
        "operationId": "postTracking",
        "summary": "Look up a shipment using JSON",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "trackingNumber"
                ],
                "properties": {
                  "trackingNumber": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{4,39}$",
                    "example": "08640-01-090034008"
                  },
                  "carrier": {
                    "type": "string",
                    "enum": [
                      "postex",
                      "leopards",
                      "tcs",
                      "blueex",
                      "trax"
                    ],
                    "default": "postex"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shipment found.",
            "headers": {
              "X-Cache": {
                "schema": {
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              },
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds remaining in the local request window."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "carrier",
                        "trackingNumber",
                        "history",
                        "latest",
                        "raw",
                        "cached",
                        "fetchedAt"
                      ],
                      "properties": {
                        "carrier": {
                          "type": "string",
                          "enum": [
                            "postex",
                            "leopards",
                            "tcs",
                            "blueex",
                            "trax"
                          ]
                        },
                        "trackingNumber": {
                          "type": "string"
                        },
                        "customerName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "orderPickupDate": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "latest": {
                          "anyOf": [
                            {
                              "type": "object",
                              "required": [
                                "code",
                                "status",
                                "timestamp"
                              ],
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "status": {
                                  "type": "string"
                                },
                                "timestamp": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                                },
                                "timestampText": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Original courier time text, retained for display when parsing is uncertain."
                                }
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "history": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "code",
                              "status",
                              "timestamp"
                            ],
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "timestamp": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                              },
                              "timestampText": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Original courier time text, retained for display when parsing is uncertain."
                              }
                            }
                          }
                        },
                        "raw": {
                          "type": "object",
                          "additionalProperties": true
                        },
                        "cached": {
                          "type": "boolean"
                        },
                        "fetchedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "verification": {
                          "type": "string",
                          "enum": [
                            "shipment_verified",
                            "invalid_response_verified",
                            "connection_unverified"
                          ]
                        },
                        "currentStatus": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "origin": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "destination": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "Local API is running.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "ok"
                    },
                    "service": {
                      "const": "callnod"
                    },
                    "apiKeyRequired": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/diagnostics": {
      "get": {
        "operationId": "getDiagnostics",
        "responses": {
          "200": {
            "description": "Process-local counters and request policy.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "401": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/track/{carrier}/{trackingNumber}": {
      "get": {
        "operationId": "getCarrierTracking",
        "summary": "Track an exact consignment with a selected courier",
        "parameters": [
          {
            "name": "carrier",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "postex",
                "leopards",
                "tcs",
                "blueex",
                "trax"
              ]
            }
          },
          {
            "name": "trackingNumber",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9-]{4,39}$",
              "example": "08640-01-090034008"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Shipment found.",
            "headers": {
              "X-Cache": {
                "schema": {
                  "enum": [
                    "HIT",
                    "MISS"
                  ]
                }
              },
              "RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              },
              "RateLimit-Reset": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds remaining in the local request window."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "const": true
                    },
                    "data": {
                      "type": "object",
                      "required": [
                        "carrier",
                        "trackingNumber",
                        "history",
                        "latest",
                        "raw",
                        "cached",
                        "fetchedAt"
                      ],
                      "properties": {
                        "carrier": {
                          "type": "string",
                          "enum": [
                            "postex",
                            "leopards",
                            "tcs",
                            "blueex",
                            "trax"
                          ]
                        },
                        "trackingNumber": {
                          "type": "string"
                        },
                        "customerName": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "orderPickupDate": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "latest": {
                          "anyOf": [
                            {
                              "type": "object",
                              "required": [
                                "code",
                                "status",
                                "timestamp"
                              ],
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "status": {
                                  "type": "string"
                                },
                                "timestamp": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                                },
                                "timestampText": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Original courier time text, retained for display when parsing is uncertain."
                                }
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "history": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "required": [
                              "code",
                              "status",
                              "timestamp"
                            ],
                            "properties": {
                              "code": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              },
                              "timestamp": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Timestamp with explicit timezone; null if the source time could not be reliably parsed."
                              },
                              "timestampText": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Original courier time text, retained for display when parsing is uncertain."
                              }
                            }
                          }
                        },
                        "raw": {
                          "type": "object",
                          "additionalProperties": true
                        },
                        "cached": {
                          "type": "boolean"
                        },
                        "fetchedAt": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "verification": {
                          "type": "string",
                          "enum": [
                            "shipment_verified",
                            "invalid_response_verified",
                            "connection_unverified"
                          ]
                        },
                        "currentStatus": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "origin": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "destination": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "415": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Request failed. See error.code; 429 includes Retry-After.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "Seconds to wait, present for throttling."
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "const": false
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string"
                        },
                        "message": {
                          "type": "string"
                        },
                        "retryAfter": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/carriers": {
      "get": {
        "operationId": "listCarriers",
        "summary": "List supported adapters and verification limits",
        "security": [],
        "responses": {
          "200": {
            "description": "Carrier adapter metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "carriers": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "id",
                          "name",
                          "website",
                          "verification",
                          "note"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "enum": [
                              "postex",
                              "leopards",
                              "tcs",
                              "blueex",
                              "trax"
                            ]
                          },
                          "name": {
                            "type": "string"
                          },
                          "website": {
                            "type": "string",
                            "format": "uri"
                          },
                          "verification": {
                            "type": "string",
                            "enum": [
                              "shipment_verified",
                              "invalid_response_verified",
                              "connection_unverified"
                            ]
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
