{"openapi":"3.1.0","info":{"title":"DeclareHQ API","version":"1.0.0","summary":"AI-native UK customs, GVMS, and CBAM compliance platform — REST API.","description":"DeclareHQ exposes a clean REST API for UK trade compliance workflows.\nAll endpoints are authenticated with a Bearer API key in the format `dhq_<32 chars>`.\nGenerate keys at https://declarehq.com/settings/keys.\n\n**Mock mode:** AI endpoints work without an Anthropic API key — they return\ndeterministic mock data so you can build and test integrations risk-free.","contact":{"name":"DeclareHQ Developer Support","email":"developers@declarehq.com","url":"https://declarehq.com/developers"},"license":{"name":"Proprietary","url":"https://declarehq.com/terms"}},"servers":[{"url":"https://declarehq.com","description":"Production"}],"security":[{"BearerAuth":[]}],"tags":[{"name":"Declarations","description":"Create and submit CDS declarations"},{"name":"Shipments","description":"Track inbound/outbound consignments"},{"name":"Clients","description":"Manage importer/exporter records"},{"name":"AI","description":"Claude-powered customs assistants"},{"name":"GVMS","description":"Goods Vehicle Movement Service"},{"name":"EMCS","description":"Excise Movement Control System — duty-suspended movements"},{"name":"TSS","description":"Trader Support Service — Northern Ireland Protocol declarations"},{"name":"CBAM","description":"Carbon Border Adjustment Mechanism"},{"name":"ICS2","description":"EU Import Control System 2 — ENS pre-arrival filings"},{"name":"Tax","description":"Making Tax Digital — VAT returns"},{"name":"Audit","description":"Cross-Hub forensic audit log"},{"name":"Bulk","description":"CSV import/export"},{"name":"Hubs","description":"Hub catalog + entitlements"},{"name":"Webhooks","description":"Outgoing webhook endpoints + inbound CDS callbacks (HMAC-SHA256 signed)"}],"paths":{"/api/declarations":{"get":{"tags":["Declarations"],"summary":"List declarations","description":"Returns declarations belonging to the authenticated organisation, newest first.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"status","in":"query","schema":{"type":"string","example":"CLEARED"}}],"responses":{"200":{"description":"List of declarations","content":{"application/json":{"schema":{"type":"object","properties":{"declarations":{"type":"array","items":{"$ref":"#/components/schemas/Declaration"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Declarations"],"summary":"Create a declaration","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclarationCreate"}}}},"responses":{"201":{"description":"Declaration created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Declaration"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cds/submit":{"post":{"tags":["Declarations"],"summary":"Submit a declaration to HMRC CDS","description":"Sends the WCO 3.6 XML payload to HMRC CDS. Returns the conversation ID used to correlate inbound DMSRCV/DMSACC/DMSTAX/DMSCLE notifications.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["declarationId"],"properties":{"declarationId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":"string"},"status":{"type":"string","example":"SUBMITTED"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"502":{"description":"HMRC CDS unreachable or rejected the request"}}}},"/api/ai/commodity-classify":{"post":{"tags":["AI"],"summary":"Classify a product to a 10-digit commodity code","description":"Plain-English product description in, ranked commodity-code suggestions out. Falls back to keyword-based mock when ANTHROPIC_API_KEY is not set.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["description"],"properties":{"description":{"type":"string","example":"100% cotton women's evening dresses"},"countryOfOrigin":{"type":"string","example":"IN","maxLength":2}}}}}},"responses":{"200":{"description":"Suggestions ranked by confidence","content":{"application/json":{"schema":{"type":"object","properties":{"suggestions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","example":"6204430000"},"description":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":1},"reasoning":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/ai/extract-document":{"post":{"tags":["AI"],"summary":"Extract structured data from an invoice or BoL","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","documentType"],"properties":{"file":{"type":"string","format":"binary"},"documentType":{"type":"string","enum":["invoice","bill_of_lading","packing_list"]}}}}}},"responses":{"200":{"description":"Extracted structured payload"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/ai/analyse-declaration":{"post":{"tags":["AI"],"summary":"AI anomaly review of a draft declaration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["declarationId"],"properties":{"declarationId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Findings ranked by severity","content":{"application/json":{"schema":{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["info","warning","blocker"]},"field":{"type":"string"},"message":{"type":"string"}}}},"hasBlockers":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/ai/explain-rejection":{"post":{"tags":["AI"],"summary":"Plain-English explanation of HMRC DMSREJ errors","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["declarationId"],"properties":{"declarationId":{"type":"string","format":"uuid"}}},{"type":"object","required":["errors"],"properties":{"errors":{"type":"array","items":{"type":"object"}}}}]}}}},"responses":{"200":{"description":"Per-error explanations + suggested fixes"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/shipments":{"get":{"tags":["Shipments"],"summary":"List shipments","responses":{"200":{"description":"Shipments","content":{"application/json":{"schema":{"type":"object","properties":{"shipments":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Shipments"],"summary":"Create a shipment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","portOfEntry","transportMode"],"properties":{"clientId":{"type":"string","format":"uuid"},"portOfEntry":{"type":"string","example":"Felixstowe"},"transportMode":{"type":"string","enum":["SEA","AIR","ROAD","RAIL"]},"vesselName":{"type":"string"},"expectedArrival":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Shipment created"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/clients":{"get":{"tags":["Clients"],"summary":"List clients","responses":{"200":{"description":"Clients"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/gvms/movements":{"get":{"tags":["GVMS"],"summary":"List GVMS goods-movement records","responses":{"200":{"description":"Movements"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"GVMS Hub not enabled"}}},"post":{"tags":["GVMS"],"summary":"Create a GMR draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["routeFrom","routeTo","vehicleReg"],"properties":{"routeFrom":{"type":"string","example":"Calais"},"routeTo":{"type":"string","example":"Dover"},"vehicleReg":{"type":"string","example":"AB12CDE"},"crossingDate":{"type":"string","format":"date-time"}}}}}},"responses":{"201":{"description":"Movement created"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"GVMS Hub not enabled"}}}},"/api/tss/declarations":{"get":{"tags":["TSS"],"summary":"List TSS (NI Protocol) declarations","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","ACCEPTED","REJECTED","CANCELLED"]}}],"responses":{"200":{"description":"Declarations"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"TSS Hub not enabled"}}},"post":{"tags":["TSS"],"summary":"Create a DRAFT TSS declaration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["movementType","traderEori","consignorName","consigneeName","commodityCode","goodsDescription","netMassKg"],"properties":{"movementType":{"type":"string","enum":["GB_NI","NI_GB","IMPORT_TO_NI"]},"traderEori":{"type":"string","example":"GB123456789000"},"ukimsAuthNumber":{"type":"string","example":"XIUKIMGB123456789000000000000123"},"consignorName":{"type":"string"},"consignorEori":{"type":"string"},"consignorCountry":{"type":"string","maxLength":2},"consigneeName":{"type":"string"},"consigneeEori":{"type":"string"},"consigneeCountry":{"type":"string","maxLength":2},"commodityCode":{"type":"string"},"goodsDescription":{"type":"string"},"netMassKg":{"type":"number"},"customsValueGbp":{"type":"number"},"countryOfOrigin":{"type":"string"},"riskCategorisation":{"type":"string","enum":["NOT_AT_RISK","AT_RISK","UNCLAIMED"]},"notAtRiskReason":{"type":"string","enum":["ukims_consumed_in_ni","uk_origin_goods","no_processing","domestic_uk_goods"]},"transportDocNumber":{"type":"string"},"vehicleReg":{"type":"string"},"scheduledDispatchAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Declaration created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"TSS Hub not enabled"}}}},"/api/tss/declarations/{id}":{"get":{"tags":["TSS"],"summary":"Get a TSS declaration","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Declaration"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["TSS"],"summary":"Cancel a TSS declaration","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"description":"Cannot cancel in current state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tss/declarations/{id}/submit":{"post":{"tags":["TSS"],"summary":"Submit a TSS declaration (mock MRN assigned)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tss/declarations/{id}/review":{"post":{"tags":["TSS","AI"],"summary":"AI categorisation review of a TSS declaration","description":"Scans for NI Protocol categorisation errors: missing UKIMS, always-at-risk commodity codes, contradictory UK-origin claims, vague descriptions.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Risk score + findings"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tss/declarations/{id}/mark-accepted":{"post":{"tags":["TSS"],"summary":"Mark a SUBMITTED TSS declaration as ACCEPTED (OWNER only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Marked accepted"},"400":{"description":"Not in SUBMITTED state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only OWNER role can mark accepted"}}}},"/api/audit":{"get":{"tags":["Audit"],"summary":"Cross-Hub forensic audit log","description":"Returns every meaningful state transition across all Hubs (submit, accept, reject, cancel, etc.). Filter by hub, eventType, actor, date range.","parameters":[{"name":"hub","in":"query","schema":{"type":"string"}},{"name":"eventType","in":"query","schema":{"type":"string"}},{"name":"actorUserId","in":"query","schema":{"type":"string"}},{"name":"startDate","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"endDate","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Events + cursor for next page"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/webhooks/endpoints/{id}/deliveries/{deliveryId}/resend":{"post":{"tags":["Webhooks"],"summary":"Re-fire a past delivery with the same payload","description":"Creates a fresh PENDING delivery cloned from a previous attempt and runs it inline. Useful for replaying failed deliveries.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"New delivery row + originalId"},"400":{"description":"Endpoint paused"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Endpoint or delivery not found"}}}},"/api/emcs/movements":{"get":{"tags":["EMCS"],"summary":"List excise movements","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","ACCEPTED","IN_TRANSIT","DELIVERED","REJECTED","CANCELLED"]}}],"responses":{"200":{"description":"Movements"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"EMCS Hub not enabled"}}},"post":{"tags":["EMCS"],"summary":"Create a DRAFT excise movement (e-AD)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category","movementType","dispatcherName","dispatcherExciseNumber","consigneeName","productCode","productDescription"],"properties":{"category":{"type":"string","enum":["ALCOHOL","TOBACCO","ENERGY_OILS"]},"movementType":{"type":"string","enum":["DOMESTIC","EXPORT","IMPORT_FROM_EU"]},"dispatcherName":{"type":"string"},"dispatcherExciseNumber":{"type":"string","example":"GBWK000123456"},"consigneeName":{"type":"string"},"consigneeExciseNumber":{"type":"string"},"consigneeCountry":{"type":"string","maxLength":2},"productCode":{"type":"string","example":"S400"},"productDescription":{"type":"string"},"quantityLitres":{"type":"number"},"quantityKg":{"type":"number"},"alcoholAbv":{"type":"number"},"packageType":{"type":"string"},"numberOfPackages":{"type":"integer"},"vehicleReg":{"type":"string"},"expectedJourneyTime":{"type":"integer"},"scheduledDispatchAt":{"type":"string","format":"date-time"}}}}}},"responses":{"200":{"description":"Movement created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"EMCS Hub not enabled"}}}},"/api/emcs/movements/{id}":{"get":{"tags":["EMCS"],"summary":"Get an excise movement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Movement"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["EMCS"],"summary":"Cancel an excise movement","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"description":"Cannot cancel in current state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/emcs/movements/{id}/submit":{"post":{"tags":["EMCS"],"summary":"Submit e-AD to EMCS (mock ARC assigned)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/emcs/movements/{id}/review":{"post":{"tags":["EMCS","AI"],"summary":"AI risk scoring of an excise movement","description":"Scans for excise-fraud indicators — malformed approval numbers, diversion-risk journey times, oversized consignments, sanctioned destinations.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Risk score + findings"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cbam/imports":{"get":{"tags":["CBAM"],"summary":"List CBAM-relevant imports","parameters":[{"name":"quarter","in":"query","schema":{"type":"string","example":"2026-Q2"}}],"responses":{"200":{"description":"Imports"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"CBAM Hub not enabled"}}},"post":{"tags":["CBAM"],"summary":"Log a CBAM-relevant import (AI estimates emissions if not supplied)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["category","commodityCode","countryOfOrigin","netMassKg"],"properties":{"category":{"type":"string","enum":["CEMENT","IRON_STEEL","ALUMINIUM","FERTILISER","HYDROGEN","ELECTRICITY"]},"commodityCode":{"type":"string","example":"7208390010"},"countryOfOrigin":{"type":"string","example":"CN","maxLength":2},"netMassKg":{"type":"number","example":25000},"customsValueGbp":{"type":"number"},"embeddedEmissionsKgCo2":{"type":"number","description":"If omitted, AI estimates from category + country."},"notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Import logged"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"CBAM Hub not enabled"}}}},"/api/cbam/reports":{"get":{"tags":["CBAM"],"summary":"List CBAM quarterly reports","responses":{"200":{"description":"Reports","content":{"application/json":{"schema":{"type":"object","properties":{"reports":{"type":"array","items":{"$ref":"#/components/schemas/CbamReport"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["CBAM"],"summary":"Generate (or refresh) a DRAFT report for a quarter","description":"Snapshots all CBAM imports in the given quarter into a CbamReport. Refuses to overwrite a SUBMITTED or ACCEPTED report.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"quarter":{"type":"string","pattern":"^\\d{4}-Q[1-4]$","example":"2026-Q2","description":"Defaults to the current quarter."}}}}}},"responses":{"200":{"description":"Draft generated","content":{"application/json":{"schema":{"type":"object","properties":{"report":{"$ref":"#/components/schemas/CbamReport"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cbam/reports/{id}":{"get":{"tags":["CBAM"],"summary":"Get a CBAM report + its imports","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report + imports"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["CBAM"],"summary":"Delete a DRAFT report (ACCEPTED locked)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Cannot delete in current state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cbam/reports/{id}/submit":{"post":{"tags":["CBAM"],"summary":"Submit a CBAM report (locks it)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cbam/reports/{id}/mark-accepted":{"post":{"tags":["CBAM"],"summary":"Mark a SUBMITTED CBAM report as ACCEPTED (OWNER only)","description":"Records that HMRC accepted the quarterly submission. Fires the cbam.report.accepted webhook event. Until the real regulator webhook is wired, operators flip this manually.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Report marked accepted"},"400":{"description":"Not in SUBMITTED state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only OWNER role can mark accepted"}}}},"/api/cbam/reports/{id}/review":{"post":{"tags":["CBAM","AI"],"summary":"AI compliance review of a CBAM report","description":"Scans the imports for missing supplier data, implausible factors, concentration risk, etc. Mock mode falls back to deterministic rule-based checks.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Findings + summary","content":{"application/json":{"schema":{"type":"object","properties":{"review":{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object"}},"hasBlockers":{"type":"boolean"},"summary":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cbam/reports/{id}/export.xml":{"get":{"tags":["CBAM"],"summary":"Download a CBAM report as XML","description":"Emits the report in the EU CBAM Transitional Registry XML shape (HMRC reuses a near-identical format).","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"XML file","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}}},"/api/ics2/filings":{"get":{"tags":["ICS2"],"summary":"List ENS pre-arrival filings","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["DRAFT","SUBMITTED","ACCEPTED","REJECTED","CANCELLED"]}}],"responses":{"200":{"description":"Filings"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"ICS2 Hub not enabled"}}},"post":{"tags":["ICS2"],"summary":"Create a DRAFT ENS filing","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["filingType","modeOfTransport","carrierName","transportDocNumber","consignorName","consigneeName","portOfLoading","portOfUnloading"],"properties":{"filingType":{"type":"string","enum":["ENS_ROAD","ENS_AIR","ENS_SEA","ENS_RAIL","ENS_POSTAL"]},"modeOfTransport":{"type":"string","example":"1"},"carrierName":{"type":"string"},"carrierEori":{"type":"string"},"transportDocNumber":{"type":"string"},"consignorName":{"type":"string"},"consignorEori":{"type":"string"},"consigneeName":{"type":"string"},"consigneeEori":{"type":"string"},"portOfLoading":{"type":"string","example":"GBFXT"},"portOfUnloading":{"type":"string","example":"DEHAM"},"estimatedArrival":{"type":"string","format":"date-time"},"totalPackages":{"type":"integer"},"totalGrossMassKg":{"type":"number"},"goodsDescription":{"type":"string"},"commodityCodes":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Filing created"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"ICS2 Hub not enabled"}}}},"/api/ics2/filings/{id}":{"get":{"tags":["ICS2"],"summary":"Get an ENS filing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filing"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["ICS2"],"summary":"Cancel an ENS filing","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Cancelled"},"400":{"description":"Cannot cancel in current state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/ics2/filings/{id}/submit":{"post":{"tags":["ICS2"],"summary":"Submit ENS filing to ICS2 (mock until live)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/ics2/filings/{id}/mark-accepted":{"post":{"tags":["ICS2"],"summary":"Mark a SUBMITTED ICS2 filing as ACCEPTED (OWNER only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Filing marked accepted"},"400":{"description":"Not in SUBMITTED state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only OWNER role can mark accepted"}}}},"/api/ics2/filings/{id}/review":{"post":{"tags":["ICS2","AI"],"summary":"AI risk scoring of an ENS filing","description":"Scans the filing for ICS2 risk targeting hits — sanctioned jurisdictions, vague descriptions, high-risk commodity codes, missing EORIs, late filing windows.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Risk score + findings","content":{"application/json":{"schema":{"type":"object","properties":{"review":{"type":"object","properties":{"riskScore":{"type":"number","minimum":0,"maximum":1},"findings":{"type":"array","items":{"type":"object"}},"hasBlockers":{"type":"boolean"},"summary":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tax/periods":{"get":{"tags":["Tax"],"summary":"List VAT obligations (periods)","description":"Ensures the current calendar quarter exists and returns it plus historical periods.","responses":{"200":{"description":"Periods","content":{"application/json":{"schema":{"type":"object","properties":{"periods":{"type":"array","items":{"$ref":"#/components/schemas/VatPeriod"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"Tax Hub not enabled"}}}},"/api/tax/returns":{"get":{"tags":["Tax"],"summary":"List VAT returns","responses":{"200":{"description":"Returns"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Tax"],"summary":"Generate (or refresh) a DRAFT VAT return","description":"Snapshots cleared import declarations in the period into Box 4. Accepts user-supplied figures for the other boxes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["periodId"],"properties":{"periodId":{"type":"string"},"box1VatDueSales":{"type":"number"},"box2VatDueAcquisitions":{"type":"number"},"box4AdditionalReclaim":{"type":"number"},"box6TotalSales":{"type":"number"},"box7TotalPurchases":{"type":"number"},"box8TotalSuppliesEu":{"type":"number"},"box9TotalAcquisitionsEu":{"type":"number"}}}}}},"responses":{"200":{"description":"Draft generated"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tax/returns/{id}":{"get":{"tags":["Tax"],"summary":"Get a VAT return","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Return"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"delete":{"tags":["Tax"],"summary":"Delete a DRAFT VAT return","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tax/returns/{id}/submit":{"post":{"tags":["Tax"],"summary":"Submit a VAT return (locks it, assigns mock HMRC ID)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Submitted"},"400":{"description":"Not in DRAFT state"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tax/returns/{id}/mark-accepted":{"post":{"tags":["Tax"],"summary":"Mark a SUBMITTED VAT return as ACCEPTED (OWNER only)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Return marked accepted"},"400":{"description":"Not in SUBMITTED state"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Only OWNER role can mark accepted"}}}},"/api/tax/returns/{id}/review":{"post":{"tags":["Tax","AI"],"summary":"AI compliance review of a VAT return","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Findings + summary"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/tax/returns/{id}/export.xml":{"get":{"tags":["Tax"],"summary":"Download a VAT return as XML","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"XML file","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/import/clients/preview":{"post":{"tags":["Bulk"],"summary":"AI-mapped CSV preview for client import","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Preview with AI column mapping"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/import/clients/commit":{"post":{"tags":["Bulk"],"summary":"Commit a CSV client import","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["mapping","rows"],"properties":{"mapping":{"type":"object"},"rows":{"type":"array","items":{"type":"object"}}}}}}},"responses":{"200":{"description":"Commit result"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/export/declarations":{"get":{"tags":["Bulk"],"summary":"Download all declarations as CSV","responses":{"200":{"description":"CSV stream","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/export/shipments":{"get":{"tags":["Bulk"],"summary":"Download all shipments as CSV","responses":{"200":{"description":"CSV stream"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/export/clients":{"get":{"tags":["Bulk"],"summary":"Download all clients as CSV","responses":{"200":{"description":"CSV stream"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/hubs/{id}":{"post":{"tags":["Hubs"],"summary":"Enable a Hub for the authenticated organisation","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Enabled"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Already enabled or not bookable"}}},"delete":{"tags":["Hubs"],"summary":"Disable a Hub (refuses 'customs' — foundational)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Disabled"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"Cannot disable foundational Hub"}}}},"/api/webhooks/endpoints":{"get":{"tags":["Webhooks"],"summary":"List webhook endpoints","responses":{"200":{"description":"Endpoints (secrets redacted)"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Webhooks"],"summary":"Create a webhook endpoint — full signing secret returned ONCE","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://example.com/hooks/declarehq"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string"},"description":"Empty array = all events. Use '*' as a wildcard."}}}}}},"responses":{"200":{"description":"Endpoint created (secret in plaintext)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/webhooks/endpoints/{id}":{"get":{"tags":["Webhooks"],"summary":"Get a webhook endpoint (secret redacted)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Endpoint"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found"}}},"patch":{"tags":["Webhooks"],"summary":"Update url / events / active state","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","nullable":true},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Updated"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"delete":{"tags":["Webhooks"],"summary":"Delete the endpoint + cascade its delivery log","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Deleted"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/webhooks/endpoints/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Delivery log for an endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"Deliveries"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/webhooks/endpoints/{id}/test":{"post":{"tags":["Webhooks"],"summary":"Fire a `webhook.ping` event to this endpoint","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Delivery row (with status + HTTP code)"},"400":{"description":"Endpoint paused"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/cds/webhook":{"post":{"tags":["Webhooks"],"summary":"Inbound CDS notification (HMRC → DeclareHQ)","description":"Signed HMRC callback delivering DMSRCV / DMSACC / DMSTAX / DMSCLE / DMSREJ messages. Authenticated via OAuth bearer issued by HMRC, not your API key.","requestBody":{"content":{"application/xml":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"Acknowledged"}},"security":[]}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"dhq_*","description":"API key generated at /settings/keys."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"invalid_request"},"message":{"type":"string"}}},"Declaration":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"lrn":{"type":"string","example":"GBLRN0000001"},"mrn":{"type":"string","nullable":true,"example":"26GB123456789ABC01"},"status":{"type":"string","enum":["DRAFT","SUBMITTED","ACCEPTED","REJECTED","CLEARED","CANCELLED"]},"declarationType":{"type":"string","example":"IMPORT"},"totalDutyGbp":{"type":"number"},"totalVatGbp":{"type":"number"},"createdAt":{"type":"string","format":"date-time"}}},"VatPeriod":{"type":"object","properties":{"id":{"type":"string"},"periodKey":{"type":"string","example":"2026-Q2"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"dueDate":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["OPEN","FULFILLED"]},"source":{"type":"string","enum":["mtd","mock"]}}},"CbamReport":{"type":"object","properties":{"id":{"type":"string"},"quarter":{"type":"string","example":"2026-Q2"},"status":{"type":"string","enum":["DRAFT","SUBMITTED","ACCEPTED"]},"totalImportsCount":{"type":"integer"},"totalNetMassKg":{"type":"number"},"totalEmissionsKg":{"type":"number"},"totalCertCostGbp":{"type":"number"},"submittedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"DeclarationCreate":{"type":"object","required":["shipmentId","declarationType","items"],"properties":{"shipmentId":{"type":"string","format":"uuid"},"declarationType":{"type":"string","enum":["IMPORT","EXPORT"]},"items":{"type":"array","items":{"type":"object","required":["commodityCode","description","netMassKg","customsValueGbp"],"properties":{"commodityCode":{"type":"string","example":"6204430000"},"description":{"type":"string"},"netMassKg":{"type":"number"},"grossMassKg":{"type":"number"},"customsValueGbp":{"type":"number"},"countryOfOrigin":{"type":"string","example":"IN"},"quantity":{"type":"integer"},"additionalProcedureCodes":{"type":"array","items":{"type":"string"}}}}},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","example":"N380"},"reference":{"type":"string"}}}}}}}}}