API-documentatie

Bepaal HS-codes en laat de documenten van een zending controleren met de Import8 REST API.

Base URL https://import8.nl/api

Authenticatie

Alle API-verzoeken (behalve /health) vereisen authenticatie via een API key. Genereer API keys in je dashboard.

Stuur je API key mee via de Authorization header met het Bearer-schema:

curl -H "Authorization: Bearer c8_your_api_key" \
  https://import8.nl/api/v1/me
import requests

response = requests.get(
    "https://import8.nl/api/v1/me",
    headers={"Authorization": "Bearer c8_your_api_key"}
)
print(response.json())
const response = await fetch('https://import8.nl/api/v1/me', {
  headers: { 'Authorization': 'Bearer c8_your_api_key' }
});
const data = await response.json();

Verbruik bijhouden

Alle classificatie-endpoints bevatten een usage object in de response, zodat je je resterende credits kunt bijhouden zonder een apart API-verzoek.

"usage": {
  "credits_remaining": 47,
  "credits_days_left": 12,
  "credits_run_out_date": "2026-11-09"
}
Veld Type Beschrijving
credits_remaining integer Aantal resterende credits over alle actieve saldi
credits_days_left integer | null Verwacht aantal dagen tot het tegoed op is, op basis van het gemiddelde verbruik van de afgelopen 28 dagen en de verloopdatum van de tegoeden. null als dat niet te berekenen is (te weinig verbruik om op te rekenen, of een vrijgestelde organisatie). 0 als het tegoed op is.
credits_run_out_date string (Y-m-d) | null Verwachte datum (Y-m-d) waarop het tegoed op is. null als dat niet te berekenen is. Ook beschikbaar in GET /v1/usage.
POST

/v1/classify

Dien een product in voor HS code classificatie. De classificatie wordt asynchroon verwerkt. Je ontvangt een 202 Accepted response met een classificatie-ID. Poll voor resultaten of configureer een webhook.

Request Body

Parameter Type Verplicht Beschrijving
image_url string optional URL van een productafbeelding (maximaal 5 afbeeldingen)
image_base64 string optional Base64-gecodeerde productafbeelding
description string optional Productbeschrijving als tekst
origin_country string optional 2-letterige ISO landcode van het herkomstland
destination_country string optional 2-letterige ISO landcode (standaard: NL)
goods_value number optional Eenheidsprijs van de goederen (FOB). Indien opgegeven wordt de landed cost automatisch berekend na classificatie.
quantity integer optional Aantal eenheden (standaard: 1)
shipping_cost number optional Verzend- / vrachtkosten (standaard: 0)
insurance_cost number optional Verzekeringskosten (standaard: 0)
currency string optional 3-letterige valutacode (standaard: EUR). Ondersteund: EUR, USD, GBP, CNY.

Let op: Minimaal een van image_url, image_base64, of description is verplicht.

Landed cost: Wanneer goods_value is opgegeven, bevat het classificatieresultaat een landed_cost object met CIF-waarde, invoerrechten, antidumping, BTW en totale landed cost. Dit gebruikt dezelfde berekening als het standalone POST /v1/landed-cost endpoint.

Risico-grading & documenten: Een afgerond resultaat bevat ook risk_grading (regulatoir intensiteitsniveau L0 tot L6 voor de HS-code, plus CBAM-/antidumping-/sanctievlaggen) en documents (de vereiste importdocumenten per van toepassing zijnd regime). Beide hebben een available boolean: true mét de data, of false met een reason (no_hs_code of error), zodat je "geen verplichtingen" kunt onderscheiden van "kon niet berekend worden". Deze objecten worden teruggegeven door dit endpoint en door GET /v1/classifications/{id}. De webhook zelf geeft alleen een seintje dat het resultaat klaar is.

Voorbeeldverzoek

curl -X POST https://import8.nl/api/v1/classify \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Wireless bluetooth over-ear headphones with noise cancellation",
    "image_url": "https://example.com/product.jpg",
    "origin_country": "CN",
    "destination_country": "NL",
    "goods_value": 25.00,
    "quantity": 100,
    "shipping_cost": 150.00,
    "insurance_cost": 12.50,
    "currency": "EUR"
  }'
import requests

response = requests.post(
    "https://import8.nl/api/v1/classify",
    headers={"Authorization": "Bearer c8_your_api_key"},
    json={
        "description": "Wireless bluetooth over-ear headphones with noise cancellation",
        "image_url": "https://example.com/product.jpg",
        "origin_country": "CN",
        "destination_country": "NL",
        "goods_value": 25.00,
        "quantity": 100,
        "shipping_cost": 150.00,
        "insurance_cost": 12.50,
        "currency": "EUR"
    }
)

data = response.json()
classification_id = data["data"]["id"]
print(f"Classification queued: {classification_id}")
const response = await fetch('https://import8.nl/api/v1/classify', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer c8_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    description: 'Wireless bluetooth over-ear headphones with noise cancellation',
    image_url: 'https://example.com/product.jpg',
    origin_country: 'CN',
    destination_country: 'NL',
    goods_value: 25.00,
    quantity: 100,
    shipping_cost: 150.00,
    insurance_cost: 12.50,
    currency: 'EUR',
  }),
});

const { data } = await response.json();
console.log('Classification queued:', data.id);

Response 202 Accepted

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "message": "Classification queued. Poll GET /v1/classifications/{id} for results, or configure a webhook to receive notifications."
  },
  "usage": {
    "credits_remaining": 47
  }
}
GET

/v1/classifications/{id}

Haal een classificatieresultaat op via het UUID. Poll dit endpoint na het indienen van een classificatieverzoek totdat de status verandert van pending naar completed. Eindstatussen zijn completed, failed en insufficient_information.

Voorbeeldverzoek

curl https://import8.nl/api/v1/classifications/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer c8_your_api_key"
import requests
import time

classification_id = "550e8400-e29b-41d4-a716-446655440000"

# Poll until completed
while True:
    response = requests.get(
        f"https://import8.nl/api/v1/classifications/{classification_id}",
        headers={"Authorization": "Bearer c8_your_api_key"}
    )
    data = response.json()["data"]

    if data["status"] == "completed":
        print(f"HS Code: {data['hs_code']['code_8']}")
        print(f"Confidence: {data['confidence']}%")
        break
    elif data["status"] == "insufficient_information":
        # Not classified, no credit used: ask the importer for a clearer description
        print(data["insufficient"]["question"])
        break
    elif data["status"] == "failed":
        print("Classification failed")
        break

    time.sleep(5)
const classificationId = '550e8400-e29b-41d4-a716-446655440000';

// Poll until completed
async function pollResult() {
  const response = await fetch(
    `https://import8.nl/api/v1/classifications/${classificationId}`,
    { headers: { 'Authorization': 'Bearer c8_your_api_key' } }
  );
  const { data } = await response.json();

  if (data.status === 'completed') return data;
  if (data.status === 'insufficient_information') return data; // see data.insufficient.question
  if (data.status === 'failed') throw new Error('Classification failed');

  await new Promise(r => setTimeout(r, 5000));
  return pollResult();
}

Response 200 OK

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "source": "api",
    "created_at": "2026-03-03T12:00:00+00:00",
    "hs_code": {
      "code_6": "8518.30",
      "code_8": "8518.30.00",
      "description": "Headphones and earphones",
      "chapter": "85"
    },
    "confidence": 92,
    "reasoning": "The product is wireless bluetooth headphones, which fall under HS heading 8518 for microphones, loudspeakers, and headphones.",
    "decision_tree": [
      {"level": "section", "code": "XVI", "description": "Machinery and mechanical appliances"},
      {"level": "chapter", "code": "85", "description": "Electrical machinery and equipment"},
      {"level": "heading", "code": "8518", "description": "Microphones, loudspeakers, headphones"}
    ],
    "alternative_codes": [
      {
        "code": "8518.10.00",
        "description": "Microphones",
        "reasoning": "Would apply if the product includes a built-in microphone as primary function"
      }
    ],
    "product_summary": "Wireless bluetooth over-ear headphones with noise cancellation",
    "reasoning_steps": [
      {"sequence": 0, "kind": "product_profile", "status": "confirmed", "decided_by": "auditor", "decided_at": "2026-03-03T12:00:05+00:00"},
      {"sequence": 1, "kind": "heading_candidates", "status": "confirmed", "decided_by": "auditor", "decided_at": "2026-03-03T12:00:08+00:00"},
      {"sequence": 2, "kind": "heading", "status": "changed", "decided_by": "auditor", "decided_at": "2026-03-03T12:00:15+00:00", "motivation": "Heading 8518 names headphones directly (GRI 1)."},
      {"sequence": 3, "kind": "outcome", "status": "confirmed", "decided_by": "auditor", "decided_at": "2026-03-03T12:00:30+00:00"}
    ],
    "ai_usage": {
      "input_tokens": 1234,
      "output_tokens": 567,
      "cost_usd": 0.00408
    },
    "completed_at": "2026-03-03T12:00:30+00:00",
    "landed_cost": {
      "cif_value": 2662.50,
      "duty": {
        "rate": "0.0%",
        "amount": 0,
        "type": "mfn"
      },
      "anti_dumping": {
        "rate": "0.0%",
        "amount": 0
      },
      "vat": {
        "rate": "21.00%",
        "amount": 559.13
      },
      "total_landed_cost": 3221.63,
      "currency": "EUR"
    },
    "risk_assessment": {
      "level": "medium",
      "reasons": ["Electronics — CE marking, RoHS, WEEE registration and EMC compliance required"],
      "should_warn": true,
      "recommended_action": "Re-run this classification in Audit mode for a defensible decision trail, or consult a customs broker."
    },
    "risk_grading": {
      "available": true,
      "overall_level": 2,
      "overall_label": "Conformity",
      "trade8_tier": "free",
      "cbam_applicable": false,
      "anti_dumping_applicable": false,
      "sanctions_applicable": false,
      "dual_use_applicable": false,
      "elements": [
        {
          "regime": "Electromagnetic Compatibility (EMC)",
          "level": 2,
          "label": "Conformity",
          "applies": true,
          "obligations": ["Affix CE marking and draw up an EU Declaration of Conformity"],
          "legal_ref": "Directive 2014/30/EU",
          "source_url": "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32014L0030",
          "verified_at": "2026-05-20",
          "national_authority": null
        }
      ],
      "rules_version": "v1.0.1"
    },
    "documents": {
      "available": true,
      "items": [
        {
          "name": "EU Declaration of Conformity (DoC)",
          "status": "verplicht-EU",
          "legal_ref": "Directive 2014/30/EU, Art. 14",
          "source_url": "https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32014L0030",
          "source_quote": "The EU declaration of conformity shall state that the fulfilment of the essential requirements has been demonstrated.",
          "national_authority": null,
          "verified_at": "2026-05-20",
          "regime_code": "EMC_2014_30",
          "regime_name": "Electromagnetic Compatibility (EMC)"
        }
      ]
    }
  },
  "usage": {
    "credits_remaining": 47
  }
}

Response als het product niet te identificeren is 200 OK

Zegt de omschrijving niet wat het product is (bijvoorbeeld testtekst, een bestands- of kolomnaam of een interne code), dan gokt Import8 geen code. De status is insufficient_information: geen hs_code, geen risico, en de credit wordt teruggeboekt. Het object insufficient zegt wat er ontbreekt (missing: key, label en vraag per punt) en geeft één question voor de importeur. Een herkenbaar product waarvan alleen een detail ontbreekt (bijvoorbeeld het materiaal) wordt gewoon geclassificeerd, met de meest waarschijnlijke code, de aannames en de open vragen. Een duidelijke tekst volstaat; een foto is niet verplicht. Dien een nieuwe classificatie in met de verbeterde omschrijving.

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "SKU-633",
    "status": "insufficient_information",
    "source": "api",
    "created_at": "2026-10-02T09:00:00+00:00",
    "insufficient": {
      "summary": "The description does not establish what the product is.",
      "missing": [
        {"key": "identity", "label": "What the product is", "question": "What kind of product is it?"},
        {"key": "function", "label": "Use", "question": "What is it used for?"}
      ],
      "question": "What is the product and what is it used for? A short text is enough."
    }
  },
  "usage": {
    "credits_remaining": 48
  }
}

Open vragen en de codetrechter

Rust een keuze onder de post op een feit dat de omschrijving niet geeft, dan staat die als open vraag in decision_tree.questions: de code die we kozen (selected) en per ander antwoord een tak met code of codebereik, recht (duty_min_pct/duty_max_pct), de regimes die erbij komen of vervallen en of hij verschilt (differs). Elke boom telt ook de aangeefbare codes die nog mogelijk zijn: codes_remaining (op de boom en per vraag) is het aantal aangeefbare codes dat via de open takken van de hele boom bereikbaar is, 1 als er niets openstaat; codes_after (per tak en op selected) is hoeveel er na dat antwoord overblijven. Een vraag onder een tak (next) telt in de situatie van die tak. Zo laat je zien hoe dicht de importeur bij één code is.

"decision_tree": {
  "selected_code": "8460.19.10.00",
  "codes_remaining": 3,
  "questions": [
    {
      "id": 812,
      "answerable": true,
      "level": 2,
      "fact": "numerical control",
      "fact_keys": ["numerical control"],
      "codes_remaining": 3,
      "selected": {"code": "8460.19.00.00", "duty": "1.70%", "codes_after": 2},
      "branches": [
        {
          "code": "8460.12.00.00",
          "outcome": "code",
          "code_reached": "8460.12.00.00",
          "duty": "4.50%",
          "duty_min_pct": 4.5,
          "duty_max_pct": 4.5,
          "regimes_added": ["EMC"],
          "regimes_removed": [],
          "differs": true,
          "codes_after": 1,
          "next": []
        }
      ]
    }
  ]
}

Beantwoord een vraag met POST /v1/classifications/{id}/answers (question_id, fact_key, value, visible_in_input). Het antwoord bevat result in dezelfde vorm als decision_tree hierboven, met codes_remaining en codes_after opnieuw berekend; result.applied zegt of het antwoord al verwerkt is.

GET

/v1/classifications

Bekijk alle classificaties van je organisatie, gesorteerd op nieuwste eerst. Resultaten zijn gepagineerd.

Query Parameters

Parameter Type Standaard Beschrijving
per_page integer 20 Aantal resultaten per pagina (max 100)

Response 200 OK

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "product_summary": "Wireless bluetooth over-ear headphones",
      "hs_code": "8518.30.00",
      "confidence": 92,
      "created_at": "2026-03-03T12:00:00+00:00"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 42,
    "last_page": 3
  },
  "usage": {
    "credits_remaining": 47
  }
}
POST

/v1/classify/batch

Dien tot 100 producten in voor classificatie in een enkel verzoek. Elk item wordt individueel en asynchroon verwerkt. Retourneert een batch-ID om de voortgang te volgen.

Request Body

Parameter Type Verplicht Beschrijving
items array required Array van classificatieverzoeken (max 100). Elk item heeft dezelfde velden als POST /v1/classify.

Voorbeeldverzoek

curl -X POST https://import8.nl/api/v1/classify/batch \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"description": "Wireless bluetooth headphones", "origin_country": "CN"},
      {"description": "Stainless steel water bottle", "origin_country": "CN"},
      {"description": "Cotton t-shirt, men, crew neck", "origin_country": "BD"}
    ]
  }'
response = requests.post(
    "https://import8.nl/api/v1/classify/batch",
    headers={"Authorization": "Bearer c8_your_api_key"},
    json={
        "items": [
            {"description": "Wireless bluetooth headphones", "origin_country": "CN"},
            {"description": "Stainless steel water bottle", "origin_country": "CN"},
            {"description": "Cotton t-shirt, men, crew neck", "origin_country": "BD"}
        ]
    }
)
batch_id = response.json()["data"]["batch_id"]
const response = await fetch('https://import8.nl/api/v1/classify/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer c8_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    items: [
      { description: 'Wireless bluetooth headphones', origin_country: 'CN' },
      { description: 'Stainless steel water bottle', origin_country: 'CN' },
      { description: 'Cotton t-shirt, men, crew neck', origin_country: 'BD' },
    ]
  }),
});

Response 202 Accepted

{
  "success": true,
  "data": {
    "batch_id": "batch_abc123",
    "total": 3,
    "classification_ids": [
      "550e8400-e29b-41d4-a716-446655440001",
      "550e8400-e29b-41d4-a716-446655440002",
      "550e8400-e29b-41d4-a716-446655440003"
    ]
  },
  "usage": {
    "credits_remaining": 47
  }
}
GET

/v1/classify/batch/{batch_id}

Controleer de status van een batch-classificatieverzoek. Retourneert de status van elke individuele classificatie in de batch.

Response 200 OK

{
  "success": true,
  "data": {
    "batch_id": "batch_abc123",
    "total": 3,
    "completed": 2,
    "pending": 1,
    "failed": 0,
    "insufficient_information": 0,
    "classifications": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "status": "completed",
        "hs_code": "8518.30.00"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "status": "completed",
        "hs_code": "7323.93.00"
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "status": "pending",
        "hs_code": null
      }
    ]
  },
  "usage": {
    "credits_remaining": 44
  }
}
POST

/v1/classifications/{id}/feedback

Geef feedback op een classificatieresultaat. Bevestig dat de classificatie correct was of geef de juiste HS code op. Dit helpt het systeem te verbeteren.

Request Body

Parameter Type Verplicht Beschrijving
status string required confirmed of corrected
corrected_code string if corrected De juiste HS code (verplicht wanneer status corrected is)

Voorbeeld: Bevestigen

curl -X POST https://import8.nl/api/v1/classifications/550e8400-.../feedback \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed"}'

Voorbeeld: Corrigeren

curl -X POST https://import8.nl/api/v1/classifications/550e8400-.../feedback \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"status": "corrected", "corrected_code": "8518.10.00"}'
GET

/v1/usage

Je creditsaldo en, per periode, je verbruik: voor classificatie en documentvalidatie apart en samen het aantal modelaanroepen, tokens (inclusief cache) en credits, plus het aantal gevalideerde documenten. Optionele queryparameters from en to (JJJJ-MM-DD, tot en met); standaard de lopende maand.

consumption.classification, consumption.document en consumption.total: count (classificaties of documenten met verbruik in de periode), calls, input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens en credits (netto, terugboekingen eraf). consumption.document.validated telt de in de periode geüploade documenten met een eindstatus. De bestaande velden zijn ongewijzigd.

Response 200 OK

curl "https://import8.nl/api/v1/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer c8_your_api_key"

{
  "success": true,
  "data": {
    "billing_exempt": false,
    "credits": {
      "remaining": 247,
      "total_purchased": 250,
      "total_used": 3,
      "earliest_expiry": "2027-03-26T00:00:00+00:00"
    },
    "credits_days_left": 41,
    "credits_run_out_date": "2026-12-08",
    "limits": { "rate_limit_per_minute": 20, "max_api_keys": 3 },
    "balances": [ ... ],
    "period": { "from": "2026-10-01", "to": "2026-10-31" },
    "consumption": {
      "classification": {
        "count": 2, "calls": 9,
        "input_tokens": 61240, "output_tokens": 4180,
        "cache_creation_input_tokens": 0, "cache_read_input_tokens": 12800,
        "credits": 2
      },
      "document": {
        "count": 1, "calls": 2,
        "input_tokens": 14310, "output_tokens": 2650,
        "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0,
        "credits": 1, "validated": 1
      },
      "total": {
        "count": 3, "calls": 11,
        "input_tokens": 75550, "output_tokens": 6830,
        "cache_creation_input_tokens": 0, "cache_read_input_tokens": 12800,
        "credits": 3
      }
    }
  }
}
GET

/v1/me

Haal accountinformatie op voor de geauthenticeerde API key, inclusief organisatiegegevens en creditsaldo.

Response 200 OK

{
  "success": true,
  "data": {
    "organization": {
      "name": "Acme Trading Co.",
      "email": "api@acmetrading.com",
      "country": "NL"
    },
    "credits": {
      "remaining": 247,
      "total_purchased": 250,
      "total_used": 3,
      "earliest_expiry": "2027-03-26T00:00:00+00:00"
    },
    "limits": {
      "rate_limit_per_minute": 20,
      "max_api_keys": 3
    }
  }
}
GET

/health

Controleer de API-status. Dit endpoint vereist geen authenticatie.

curl https://import8.nl/api/health

# Response:
{
  "success": true,
  "data": {
    "status": "operational"
  }
}
GET

/v1/duty-rates/{hs_code}

Haal invoerrechten op voor een 10-cijferige HS code. Retourneert MFN-rechten, preferentiële rechten, antidumpingrechten en BTW-tarief.

Query Parameters

Parameter Type Beschrijving
origin string 2-letterige ISO landcode om preferentiële rechten te filteren
destination string 2-letterige ISO landcode voor BTW-berekening (standaard: NL)

Voorbeeld

curl "https://import8.nl/api/v1/duty-rates/8518300090?origin=CN&destination=NL" \
  -H "Authorization: Bearer c8_your_api_key"

Response 200 OK

{
  "success": true,
  "data": {
    "hs_code": "8518300090",
    "description": "Headphones and earphones",
    "mfn_duty": {
      "rate": "2.00%",
      "expression": "2.000 %"
    },
    "preferential_duties": [
      {
        "scheme": "GSP",
        "rate": "0.00%",
        "countries": ["CN", "VN", "BD"]
      }
    ],
    "anti_dumping": [],
    "vat_rate": "21.00%"
  }
}
POST

/v1/landed-cost

Bereken de totale landed cost voor het importeren van een product. Combineert CIF-waarde, invoerrechten, antidumpingrechten en BTW.

Request Body

Parameter Type Verplicht Beschrijving
hs_code string required 10-cijferige HS goederencode
origin_country string required 2-letterige ISO landcode
destination_country string optional Standaard: NL
value number required Productwaarde (min: 0,01)
currency string optional Standaard: EUR
shipping number optional Verzendkosten (standaard: 0)
insurance number optional Verzekeringskosten (standaard: 0)

Response 200 OK

{
  "success": true,
  "data": {
    "cif_value": 31.50,
    "duty": {
      "rate": "0.00%",
      "amount": 0.00,
      "type": "preferential"
    },
    "anti_dumping": {
      "rate": "0.00%",
      "amount": 0.00
    },
    "vat": {
      "rate": "21.00%",
      "amount": 6.62
    },
    "total_landed_cost": 38.12,
    "currency": "EUR"
  }
}
POST

/v1/documents/validate

Upload een handelsdocument en krijg terug wat er ontbreekt of niet klopt voor een invoeraangifte: elke bevinding komt met de plek op het document, een kant-en-klare correctie en de bron van de eis. Een credit per document. Ondersteunde documenttypen:

  • commercial_invoice handelsfactuur (definitieve goederenfactuur).
  • proforma_invoice proforma (PI): dezelfde controles als de handelsfactuur, plus het signaal dat een proforma alleen bij uitzondering de basis voor de douanewaarde is. Een handelsfactuur die als proforma is opgegeven is geen fout.
  • freight_invoice vracht-, logistiek- of commissiefactuur: welke kosten bij de douanewaarde horen (vracht en verzekering tot de plaats van binnenbrengen, luchtvracht uit China voor 70%, verkoopcommissie wel en inkoopcommissie niet, goederenbedragen via de expediteur), en bij een EU-dienstverlener de btw-factuurvereisten (art. 226 Btw-richtlijn). Een expediteur buiten de EU heeft geen voorgeschreven vorm.
  • payment_proof betaalbewijs (Ebury, Wise, bankbevestiging): betaald bedrag, valuta, datum, betaler, ontvanger en betalingskenmerk, en de signalen voor de transactiewaarde (betaling aan een derde, aanbetaling of deelbetaling, betaling die niet bij de factuur past, één betaling voor meerdere facturen). Een betaalbewijs als extra pagina achter de factuur wordt ook gelezen; het hoofddocument staat dan in detected_type en de overige documenten in extracted.embedded_documents. Geen voorgeschreven vorm.
  • packing_list paklijst: nettomassa, brutomassa, soort en aantal colli, merken en nummers, en per regel omschrijving en aantal; signaal als de regels (stuks, dozen, gewichten, CBM) niet optellen tot de totalen. Tips: doosafmetingen, CBM en artikelnummers. Een gecombineerde "Invoice & Packing List" telt ook. Geen voorgeschreven vorm.
  • air_waybill luchtvrachtbrief (AWB, master en house, ook een koeriers-AWB of een AWB als extra pagina achter de factuur): de voorgeschreven inhoud uit het Verdrag van Montreal art. 5 (vertrek, bestemming, tussenlanding als beide in één land liggen, gewicht) als fout; AWB-nummer en het masternummer op een house-AWB, aantal colli, afzender en geadresseerde voor de ENS; signaal bij gevaarlijke goederen (lithium UN3480/3481/3090/3091, PI 965-970) zonder Shipper's Declaration, tenzij Section II. Tip: 11-cijferig IATA-nummer met controlecijfer. De AWB-gegevens staan in extracted.transport_documents.
  • bill_of_lading cognossement (B/L) of sea waybill, master en house: B/L-nummer en het masternummer op een house-B/L, containers met zegelnummer, brutomassa, colli, merken, laad- en loshaven (plaats van binnenbrengen = eerste EU-haven), afzender, geadresseerde en notify party bij een B/L aan order. Hague-Visby art. III(3) (merken, colli of gewicht, uiterlijke staat) is een signaal, geen fout: het verdrag geldt niet automatisch voor een B/L uit China. Tips: VGM (laadvoorwaarde, geen douanedocument) en het ISO 6346-controlecijfer van de containers. De gegevens staan in extracted.transport_documents.
  • declaration_of_conformity EU-conformiteitsverklaring (CE, DoC): de modelstructuur van Besluit 768/2008 bijlage III als fout (productidentificatie, naam en adres van de fabrikant of gemachtigde, verklaring onder volledige verantwoordelijkheid, voorwerp, wetgeving, normen, aangemelde instantie indien genoemd, ondertekening met plaats, datum, naam, functie en handtekening), plus per handeling: normen met datum of versie (EMC, RED) en een kleurafbeelding (speelgoed 2009/48). Een "CE certificate" of "Certificate of Compliance" van een testhuis is geen DoC. Met classification_uuid: de CE-handelingen die Import8 voor die HS-code altijd vereist en die de verklaring niet noemt (gap), en een tip als het model op de verklaring niet bij de classificatie past. Tips: accessoires/software (RED), Nederlandse versie (eis niet geverifieerd). De gegevens staan in extracted.manufacturer, product, legislation, acts, standards, notified_body en signature.
  • test_report testrapport of EU-typeonderzoekscertificaat (ook een "CE certificate" van een testhuis). Een testrapport heeft geen wettelijke vorm; de controles zijn tips: normen met jaartal of versie, modelnummer, uitgevende instantie, datum, eindconclusie. Alleen voor het EU-typeonderzoekscertificaat van een aangemelde instantie (RED, EMC) gelden fouten: fabrikant met adres, typeidentificatie, conclusie en gedekte essentiële eisen, en onder de speelgoedverordening 2025/2509 ook kleurafbeelding, afmetingen, tests met verwijzing naar het rapport en fabricageplaats. Signalen: verlopen certificaat, afgekeurde test, een "LVD-certificaat" (de LVD kent geen typeonderzoek). De gegevens staan in extracted.certificate, manufacturer, product, standards en notified_body.
  • gpsr_label GPSR-etiket: een foto (JPG/PNG) of PDF van het etiket, de verpakking of het product. Fouten volgens de GPSR (2023/988): type-, partij- of serienummer (art. 9 lid 5), naam of merk, postadres en elektronisch adres van de fabrikant (art. 9 lid 6), bij een fabrikant buiten de EU de importeur met post- en elektronisch adres (art. 11 lid 3) en een marktdeelnemer in de EU met postadres (art. 16, Verordening 2019/1020 art. 4; de importeur telt daarvoor mee). Tips: waarschuwingen niet in het Nederlands (taaleis aangenomen, niet geverifieerd), geen QR-code, en met classification_uuid: geen CE-markering te zien terwijl Import8 voor die HS-code CE-wetgeving verwacht (informatief). De gegevens staan in extracted.manufacturer, importer, eu_responsible, product, languages en label.
  • insurance_certificate verzekeringscertificaat of polis van de zending. Geen wettelijk voorgeschreven inhoud (geen fouten). Gaten voor de douanewaarde: verzekerd bedrag en valuta, premie (niet bij CIF/CIP, dan zit de verzekering in de prijs), waar de dekking begint en eindigt, en een factuur- of vervoersreferentie; signaal dat de verzekeringskosten tot de plaats van binnenbrengen bij de douanewaarde horen als er werkelijk verzekerd is en het niet CIF/CIP is (art. 71 lid 1(e)(i) DWU, art. 137-138 UVo). Tips: dekking onder 110% van de factuurwaarde bij CIF/CIP (Incoterms 2020, privaat) en ontbrekende dekkingsvoorwaarden. De gegevens staan in extracted.insurance, incoterm en transport_mode.
  • certificate_of_origin oorsprongsbewijs: REX-attest van oorsprong (ook op een factuur), EUR.1, Form A of niet-preferentieel certificaat (CCPIT, kamer van koophandel). Signaal: een preferentieel bewijs met China als oorsprong levert geen preferentie op (China geen SAP-begunstigde sinds 1-1-2015, GV 2015/1978; geen vrijhandelsakkoord). Alleen als preferentie mogelijk is gelden fouten: voor het REX-attest de vaste tekst, het REX-nummer boven EUR 6.000, het oorsprongscriterium (P/W) per product en Engels, Frans of Spaans (UVo art. 92, bijlage 22-07; geen handtekening nodig), voor de EUR.1 het visum van de douane (bijlage 22-10). Niet-preferentieel: geen voorgeschreven inhoud (art. 61 DWU); gaten land van oorsprong per goed (16 08, ook voor antidumping) en omschrijving. Tips: Form A (vervangen door REX), uitgevende instantie. De gegevens staan in extracted.origin, origin_country en lines (met origin_criterion).
  • cmr CMR-vrachtbrief (wegvervoer, ook als extra pagina): de elf vermeldingen van art. 6 lid 1 CMR als fout (plaats en datum van opmaak; afzender, vervoerder en geadresseerde met adres; plaats en datum van inontvangstneming en plaats van aflevering; aard van de goederen en verpakking, bij gevaarlijke goederen hun omschrijving; colli met merken en nummers; brutogewicht; vervoerskosten; instructies voor de douane als er douaneformaliteiten zijn; de CMR-verklaring). Gaten: CMR-nummer, en bij rechtstreeks wegvervoer van buiten de EU het douanekantoor van binnenkomst (plaats van binnenbrengen) en het signaal zonder TIR-carnet of T1/MRN (transit is geen plicht, art. 226 lid 3 DWU). Tip: de lijst meegegeven documenten (lid 2(g)). De gegevens staan in extracted.transport_documents.
  • cim CIM-vrachtbrief (spoor), ook de gemeenschappelijke CIM/SMGS-vrachtbrief. Fouten: geen CIM-vrachtbrief of alleen een SMGS-vrachtbrief (art. 6 § 7 CIM: op EU-grondgebied elke zending een CIM-vrachtbrief), en de vermeldingen van art. 7 § 1 CIM (plaats en datum van opmaak; afzender, vervoerder en geadresseerde met adres; plaats en datum van inontvangstneming en plaats van aflevering; aard van de goederen en verpakking, bij gevaarlijke goederen de RID-omschrijving; colli, wagennummer of container; merken bij stukgoed; brutomassa; lijst douanedocumenten; de CIM-verklaring). Gaten: nummer van de vrachtbrief, colli, en bij vervoer van buiten de EU het douanekantoor van binnenkomst (plaats van binnenbrengen) en het signaal zonder T1/MRN (transit is geen plicht, art. 226 lid 3 DWU). Tips: vervoerskosten voor de geadresseerde, zegels. De gegevens staan in extracted.transport_documents (kind cim, smgs = CIM/SMGS).
  • un38_3_summary UN38.3-testsamenvatting van een lithiumcel of -batterij. Fouten: de tien vermeldingen van UN-Manual 38.3.5 zoals 49 CFR 173.185(a)(3) ze opsomt (UN-tekst niet geverifieerd): fabrikant en contactgegevens, testlaboratorium, uniek rapportnummer, datum, beschrijving (lithium-ion of lithium-metaal, massa, Wh-waarde of lithiuminhoud, fysieke beschrijving, model), de tests met pass/fail, bij een batterij de verwijzing naar de tests voor geassembleerde batterijen, de editie van het UN-Manual, en naam en functie van de ondertekenaar. Signaal: een gezakte test. Tips (niet geverifieerd): T1-T5 niet alle vermeld, boven 100 Wh (batterij) of 20 Wh (cel) voor de vervoersclassificatie, een editie van vóór Rev. 8, en met classification_uuid een HS-code die Import8 niet aan batterijen koppelt (informatief). De gegevens staan in extracted.battery, manufacturer, product en signature.
  • safety_data_sheet veiligheidsinformatieblad (SDS, MSDS) volgens REACH bijlage II zoals vervangen door Vo. 2020/878. Fouten: ontbrekende rubrieken 1-8, ontbrekende rubrieken 9-16 en rubrieken niet in de volgorde 1-16 (rubriek 9-16 en de volgorde niet geverifieerd), rubriek 1: productidentificatie (1.1), geïdentificeerd gebruik (1.2), leverancier met adres, telefoon en e-mail (1.3), noodnummer (1.4), en rubriek 14 zonder UN-nummer of vermelding dat het geen gevaarlijke stof voor vervoer is (niet geverifieerd). Voor een voorwerp zoals een batterij (ook herkend aan UN3480/3481/3090/3091) is een SDS meestal vrijwillig (art. 31 REACH, niet geverifieerd): dan geen fouten, maar één tip met wat ontbreekt. Tip: niet in het Nederlands (taaleis aangenomen, niet geverifieerd). De gegevens staan in extracted.sds, seller en languages.

Kleine documenten (tot 5 pagina's en 5 MB) worden verwerkt terwijl je wacht en het resultaat komt direct terug (200); de duur hangt af van het aantal artikelregels; een document dat niet binnen 24 seconden klaar is gaat op de achtergrond verder en geeft dan ook 202. Grotere documenten, of een aanvraag met async=true, geven 202 met een uuid; vraag GET /v1/documents/{uuid} op tot de status niet meer processing is. Het antwoord heeft in beide gevallen dezelfde vorm. Toegestane bestanden: PDF, JPG, PNG, XLSX, XLS, maximaal 20 MB per bestand (grotere bestanden geven 422); documenten boven 5 MB of 5 pagina's worden altijd asynchroon verwerkt. Een spreadsheet (XLSX, XLS) telt één pagina per tabblad; in de bevindingen is evidence.page dan het tabbladnummer, evidence.sheet de naam van het tabblad en bevat het citaat het celadres (bv. B4: 123). Stel bij synchrone aanroepen een client-timeout van minstens 40 seconden in.

Bestanden worden niet bewaard; het resultaat is 24 uur opvraagbaar. Het geüploade bestand wordt verwijderd zodra de verwerking klaar (of mislukt) is. De uitgelezen gegevens en de bevindingen blijven 24 uur na het uploaden opvraagbaar via GET /v1/documents/{uuid} en worden daarna gewist. Wat blijft is een logregel zonder inhoud: typen, status, het aantal fouten, gaten en tips, de codes van de bevindingen, pagina's, bestandsgrootte, duur en credits.

Request Body multipart/form-data

Parameter Type Verplicht Beschrijving
file file required Het document: PDF, JPG, PNG, XLSX of XLS. Niet leeg, niet met wachtwoord beveiligd.
document_type string optional Documenttype: commercial_invoice, proforma_invoice, freight_invoice, payment_proof, packing_list, air_waybill, bill_of_lading, declaration_of_conformity, test_report, gpsr_label, insurance_certificate, certificate_of_origin, cmr, cim, un38_3_summary, safety_data_sheet. Andere waarden geven 422 met de ondersteunde typen. Laat je het weg, dan herkent Import8 het type zelf en past het de controles van dat type toe (type_detected true in de response; de extractie leest dan alle velden en kost iets meer modeltijd). Is het document geen van deze typen, dan wordt document_type other met de fout document_type_not_recognized.
transport_mode string optional Vervoerswijze: sea, air, rail, road of post. Gebruikt voor de controles op vracht en verzekering.
import_country string optional Land van invoer: NL of DE, standaard NL. Bepaalt de taal en de eisen per land. Met de header Accept-Language: de komt het resultaat in het Duits.
importer_name string optional Naam van de importeur als die niet je organisatie is, bijvoorbeeld je eindklant. De kopercontrole en de correcties gebruiken deze naam. Wordt met de inhoud gewist.
reference string optional Je eigen vrije referentie (maximaal 255 tekens); komt terug als <code>reference</code> in het resultaat en staat in het rapport.
classification_uuid string optional Uuid van een van je eigen classificaties. De HS-codes op de factuur worden met die classificatie vergeleken; bij een conformiteitsverklaring de vereiste CE-handelingen en het model; bij een GPSR-etiket de CE-markering; bij een UN38.3-testsamenvatting of de HS-code aan batterijen gekoppeld is.
async boolean optional true om altijd 202 te krijgen en het resultaat op te halen.

Voorbeeld

curl -X POST "https://import8.nl/api/v1/documents/validate" \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Accept-Language: en" \
  -F "file=@invoice.pdf" \
  -F "document_type=commercial_invoice" \
  -F "transport_mode=sea"

Response 200 OK / 202 Accepted

{
  "success": true,
  "data": {
    "uuid": "9f1c2a4e-5b7d-4c1a-8e0f-3a6d2b9c7e11",
    "document_type": "commercial_invoice",
    "type_detected": false,
    "detected_type": "proforma_invoice",
    "transport_mode": "sea",
    "classification_uuid": null,
    "status": "incomplete",
    "findings": [
      {
        "layer": "declaration",
        "severity": "gap",
        "code": "goods_code_missing",
        "field": "lines[].hs_code",
        "paths": ["lines[0].hs_code", "lines[1].hs_code"],
        "message": "The commodity code (at least the 6-digit HS code) is missing on one or more item lines.",
        "evidence": { "page": 1, "sheet": null, "quote": null },
        "correction": "Please state at least the 6-digit HS code for each item.",
        "source": "GV 2015/2446 bijlage B, 18 09; ICS2/ENS: HS op 6 cijfers"
      },
      {
        "layer": "declaration",
        "severity": "gap",
        "code": "gross_mass_missing",
        "field": "gross_kg",
        "paths": ["gross_kg"],
        "message": "The gross mass is missing.",
        "evidence": { "page": 1, "sheet": null, "quote": null },
        "correction": "Please state the gross weight in kg.",
        "source": "GV 2015/2446 bijlage B (brutomassa; bij de ENS zoals op het vervoerdocument)"
      },
      {
        "layer": "common",
        "severity": "tip",
        "code": "currency_not_usd",
        "field": "currency",
        "paths": ["currency"],
        "message": "The invoice is not in USD. Any currency is legally allowed, but forwarders often ask for USD.",
        "evidence": { "page": 1, "sheet": null, "quote": "Total: CNY 12,480.00" },
        "correction": "Forwarders usually expect the invoice in USD.",
        "source": "Praktijk expediteurs (laag C), geen wettelijke eis; wettelijk mag elke valuta, omrekening volgens UVo 2015/2447 art. 146"
      }
    ],
    "correction_request": "Please issue a corrected invoice: 1. Please state at least the 6-digit HS code for each item. 2. Please state the gross weight in kg.",
    "extracted": { "invoice_number": "EX-2026-0412", "currency": "CNY", "lines": [ "..." ] },
    "created_at": "2026-10-08T10:15:30+00:00"
  },
  "usage": { "credits_remaining": 41 }
}

correction_request is een Engelse tekst voor de leverancier met de correcties van alle errors en gaps samen. Hij is null als er niets te corrigeren valt. extracted bevat de uit het document gelezen gegevens.

Status

De status vat de bevindingen samen. Los eerst de errors op, daarna de gaps.

Status Beschrijving
processing Nog in verwerking (asynchrone aanvragen). Vraag over enkele seconden opnieuw op.
failed Verwerking mislukt. De credit is teruggeboekt; dien het document opnieuw in.
invalid Minstens een error: het document is geen goederenfactuur of mist wettelijk verplichte inhoud.
incomplete Geen errors, wel minstens een gap: gegevens die voor de aangifte nodig zijn ontbreken. Ze kunnen uit een ander document komen (paklijst, vervoersdocument).
complete_with_tips Geen errors of gaps, alleen tips waar expediteurs vaak om vragen.
complete Niets te melden.

De drie lagen

Elke bevinding hoort bij een laag, en de laag bepaalt de ernst.

Layer Beschrijving
legal → error Wettelijk voorgeschreven inhoud van het document zelf. Ernst error.
declaration → gap Nodig voor de douaneaangifte of de douanewaarde, maar kan uit een ander document komen. Ernst gap.
common → tip Veelgevraagd door expediteurs; niet verplicht. Ernst tip.

Bevindingen

Veld Beschrijving
layer legal, declaration of common.
severity error, gap of tip.
code Vaste regelcode, bijvoorbeeld goods_code_missing.
field Het betreffende veld, bijvoorbeeld lines[].hs_code.
paths De exacte plekken in extracted waar de bevinding over gaat, bijvoorbeeld lines[2].hs_code.
message Uitleg in de taal van de Accept-Language-header (nl of en).
evidence page, sheet en quote: waar op het document de bevinding op is gebaseerd, indien van toepassing. Bij een spreadsheet (XLSX, XLS) is page het tabbladnummer, sheet de naam van het tabblad (anders null) en bevat de quote het celadres.
correction Wat de leverancier moet aanpassen, in het Engels, klaar om te versturen.
source De wettelijke of praktische bron van de eis.

Foutmeldingen

Status Beschrijving
422 Niet-ondersteund document_type; ontbrekend, leeg, onleesbaar, versleuteld of te groot bestand; of een classification_uuid die niet van jou is. Het errors-object noemt het veld.
413 De request-body is groter dan de serverlimiet voordat hij de API bereikt (JSON, geen HTML-pagina). Stuur een bestand van maximaal 20 MB.
429 Onvoldoende credits. Het document wordt niet bewaard.
502 Verwerking mislukt tijdens een synchrone aanroep. Er wordt geen credit afgeschreven; probeer opnieuw.
GET

/v1/documents/{uuid}

Geeft hetzelfde object als de validate-aanroep. Gebruik het om na een 202 te pollen of een resultaat opnieuw op te halen.

Na 24 uur antwoordt de aanroep nog steeds, met de logregel: content_purged is true, findings is leeg, extracted en correction_request zijn null, en finding_counts / finding_codes laten nog zien wat er gevonden is. Het antwoord bevat dan een message dat de inhoud is verwijderd. content_expires_at geeft aan tot wanneer de inhoud beschikbaar is.

Voorbeeld

curl "https://import8.nl/api/v1/documents/9f1c2a4e-5b7d-4c1a-8e0f-3a6d2b9c7e11" \
  -H "Authorization: Bearer c8_your_api_key"

404 — Onbekende uuid, of een document van een andere organisatie.

/v1/documents/{uuid}/pdf

Hetzelfde rapport als in het dashboard, als PDF (application/pdf): eindoordeel, bevindingen met vindplaats en wetsbron, en het bericht aan de leverancier. De taal volgt de Accept-Language-header. Geeft 404 bij een onbekende uuid, zolang het document bezig is of mislukt is, en nadat de inhoud gewist is (24 uur).

curl "https://import8.nl/api/v1/documents/9f1c2a4e-5b7d-4c1a-8e0f-3a6d2b9c7e11/pdf" \
  -H "Authorization: Bearer c8_your_api_key" \
  -o document-check.pdf
POST

/v1/document-sets

Upload de documenten van één zending samen (handelsfactuur, paklijst, vervoersdocument, certificaten) en krijg één rapport voor de hele set: de bevindingen per document, welke bevindingen een ander document uit de set al dekt, welke verplichte documenten ontbreken en één bericht voor de leverancier. De documenten worden één voor één gecontroleerd zoals bij POST /v1/documents/validate, daarna wordt de set als geheel beoordeeld. De aanroep geeft altijd 202 met een uuid; poll GET /v1/document-sets/{uuid} tot status niet meer processing is.

Credits: 1 per document plus 1 voor de set. De credits worden vooraf en atomair gereserveerd; bij te weinig credits geeft de aanroep 429 en wordt er niets bewaard. Een document dat niet verwerkt kan worden, wordt teruggeboekt.

Maximaal 20 bestanden per set en 50 MB in totaal na het uitpakken; per bestand gelden de grenzen van de documentcontrole (PDF, JPG, PNG, XLSX, XLS, maximaal 20 MB). Een zip wordt herkend op de inhoud en uitgepakt (ook als hij in files[] zit); zip bombs, geneste zips en versleutelde bestanden worden niet uitgepakt. Een bestand dat niet gecontroleerd kan worden houdt de set niet tegen: het wordt overgeslagen en met een reden vermeld in skipped (unsupported_type, unreadable, too_large, set_too_large, too_many_files, nested_zip, encrypted, too_many_entries). Kan geen enkel bestand gecontroleerd worden, dan geeft de aanroep 422.

Request Body multipart/form-data

Parameter Type Verplicht Beschrijving
files[] file[] required without zip De documenten als array van bestanden, of één zip. Verplicht tenzij zip is meegegeven.
zip file required without files[] Eén zip met de documenten. Verplicht tenzij files[] is meegegeven.
reference string optional Je eigen referentie van de zending (maximaal 255 tekens); staat in het rapport en in het bericht aan de leverancier.
transport_mode string optional Vervoerswijze: sea, air, rail, road of post. Bepaalt welk vervoersdocument verwacht wordt.
import_country string optional Land van invoer: NL of DE, standaard NL. Bepaalt de taal en de eisen per land. Met de header Accept-Language: de komt het resultaat in het Duits.
importer_name string optional Naam van de importeur als die niet je organisatie is, bijvoorbeeld je eindklant. De kopercontrole en de correcties gebruiken deze naam. Wordt met de inhoud gewist.
classification_uuids[] string[] optional Uuids van je eigen classificaties (maximaal 50); gebruikt voor de controles per HS-code.

Voorbeeld

curl -X POST "https://import8.nl/api/v1/document-sets" \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Accept-Language: en" \
  -F "files[]=@invoice.xlsx" \
  -F "files[]=@packing-list.xlsx" \
  -F "reference=AQ8-2026-10" \
  -F "transport_mode=sea"

Response 202 Accepted

{
  "success": true,
  "data": {
    "uuid": "5b0d6f9e-3a41-4c8e-9d2a-7e1f0c4b8a63",
    "reference": "AQ8-2026-10",
    "transport_mode": "sea",
    "status": "processing",
    "verdict": null,
    "documents": [ { "uuid": "...", "file_name": "invoice.xlsx", "status": "processing", ... } ],
    "counts": null,
    "skipped": [],
    "file_count": 2,
    "credits": 3,
    "content_purged": false
  },
  "message": "Document set queued. Poll GET /v1/document-sets/{uuid} for the result.",
  "usage": { "credits_remaining": 97 }
}

Foutmeldingen

422 Geen enkel bestand kan gecontroleerd worden (de array skipped zegt waarom), files[] noch zip is meegegeven, een niet-ondersteunde transport_mode of een classification_uuids-waarde die niet van jou is. Het errors-object noemt het veld.
429 Te weinig credits voor de set (1 per document plus 1 voor de set). Er wordt niets bewaard.
GET

/v1/document-sets/{uuid}

Geeft de set terug. Gebruik het om te pollen na de 202, of om het resultaat opnieuw op te halen. Alleen sets van je eigen organisatie; anders 404.

De inhoud van een set wordt 24 uur na het uploaden gewist, net als die van een document. De aanroep antwoordt dan nog met de logregel: content_purged is true, counts, missing_documents en correction_request zijn leeg of null en het antwoord heeft een message.

Voorbeeld

curl "https://import8.nl/api/v1/document-sets/5b0d6f9e-3a41-4c8e-9d2a-7e1f0c4b8a63" \
  -H "Authorization: Bearer c8_your_api_key"

Response 200 OK

{
  "success": true,
  "data": {
    "uuid": "5b0d6f9e-3a41-4c8e-9d2a-7e1f0c4b8a63",
    "reference": "AQ8-2026-10",
    "transport_mode": "sea",
    "status": "completed",
    "verdict": "incomplete",
    "documents": [
      {
        "uuid": "9f1c2a4e-5b7d-4c1a-8e0f-3a6d2b9c7e11",
        "file_name": "invoice.xlsx",
        "document_type": "commercial_invoice",
        "type_detected": true,
        "status": "incomplete",
        "set_status": "incomplete",
        "finding_counts": { "error": 0, "gap": 3, "tip": 1 },
        "covered_count": 1,
        "url": "https://import8.nl/api/v1/documents/9f1c2a4e-..."
      }
    ],
    "covered_findings": [
      {
        "document_uuid": "9f1c2a4e-...", "document_type": "commercial_invoice",
        "file_name": "invoice.xlsx", "code": "gross_mass_missing",
        "field": "gross_kg", "message": "...",
        "covered_by": { "document_uuid": "c2b7...", "document_type": "packing_list",
                        "file_name": "packing-list.xlsx", "field": "gross_kg" }
      }
    ],
    "missing_documents": [
      {
        "type": "bill_of_lading", "label": "Bill of lading",
        "requirement": "required", "required": true, "issuer": "forwarder",
        "reasons": [ { "text": "...", "requirement": "required", "condition": null,
                       "source": "...", "hs_codes": [], "regime_code": null,
                       "incoterm": null, "determined": [] } ]
      }
    ],
    "possible_issues": [
      {
        "hs_code": "8414809000", "product": "Tire air pump",
        "condition_key": "...", "condition": "...", "evidence": false, "applies": false,
        "regimes": [ { "code": "...", "name": "EMC" } ],
        "documents": [ { "type": "declaration_of_conformity", "label": "Declaration of conformity" } ],
        "issuer": "supplier", "sources": ["..."], "text": "..."
      }
    ],
    "not_applicable": [],
    "counts": { "error": 0, "gap": 2, "tip": 1, "missing_documents": 1,
                "recommended_documents": 1, "possible_issues": 1, "failed_documents": 0,
                "inconsistencies": 1 },
    "skipped": [ { "name": "notes.txt", "reason": "unsupported_type", "message": "..." } ],
    "hs_codes": ["8414809000"],
    "incoterm": "FOB",
    "transport_mode_used": "sea",
    "consistency": [
      { "code": "gross_mass_mismatch", "severity": "error", "topic": "gross mass",
        "message": "Gross mass differs: 389.85 kg on the packing list, 400 kg on the air waybill (difference 10.15 kg, allowed 7.8 kg).",
        "correction": "Please make the gross mass on the packing list (389.85 kg) and the air waybill (400 kg) the same.",
        "source": "GV 2015/2446 bijlage B, 18 04 (brutomassa); DWU art. 15 lid 2 ...",
        "responsible": "supplier_forwarder",
        "locations": ["Packing list (packing.xlsx), sum of the lines", "Air waybill (hawb.pdf), p. 1: '30 CTNS 400 KG'"],
        "documents": [ { "uuid": "...", "document_type": "packing_list", "field": "lines[].gross_kg", "page": null, "line": null, "quote": null },
                       { "uuid": "...", "document_type": "air_waybill", "field": "transport_documents[0].gross_kg", "page": 1, "line": null, "quote": "30 CTNS 400 KG" } ] }
    ],
    "correction_request": "Subject: Corrections and documents required for EU import shipment ...",
    "file_count": 2,
    "credits": 3,
    "created_at": "2026-10-14T10:07:22+00:00",
    "duration_ms": 41200,
    "content_purged": false,
    "content_expires_at": "2026-10-15T10:07:22+00:00"
  },
  "usage": { "credits_remaining": 97 }
}

Velden van het antwoord

  • status processing, completed of failed.
  • verdict Het oordeel over de hele set, met dezelfde waarden als de documentstatus: invalid, incomplete, complete_with_tips of complete. Null zolang de set bezig is.
  • counts De ene telling van de set: openstaande errors, gaps en tips over alle documenten (een gap die een ander document dekt telt niet mee), missing_documents (verplicht), recommended_documents, possible_issues, failed_documents en inconsistencies (tegenstrijdigheden tussen documenten; die tellen ook mee in errors, gaps en tips naar hun ernst). Null als de inhoud niet beschikbaar is.
  • documents Eén regel per document: uuid, file_name, document_type, type_detected, status, set_status (de status in de context van de set), finding_counts, covered_count en url (GET /v1/documents/{uuid}).
  • covered_findings Bevindingen die een ander document uit de set al dekt, elk met document_uuid, document_type, file_name, code, field, message en covered_by (document_uuid, document_type, file_name, field). Een gedekte gap telt niet als openstaand.
  • missing_documents Documenten die de set mist: type, label, requirement (required, if_applicable of recommended), required (boolean), issuer (supplier, forwarder of buyer) en reasons[] (text, requirement, condition, source, hs_codes, regime_code, incoterm en determined: waarom het verplicht is als dat voor het product is vastgesteld).
  • possible_issues Wat niet vaststaat en niet meetelt in het oordeel: per product (hs_code, product) de voorwaarde (condition_key, condition), regimes[] (code, name), documents[] (type, label), issuer, sources[], evidence en applies (booleans) en een neutrale zin in text.
  • not_applicable Regimes die voor een product als niet van toepassing zijn vastgesteld, met hs_code, product, regimes, documents en evidence.
  • consistency Tegenstrijdigheden tussen de documenten van de set (partijen, hoeveelheid en HS-code per regel factuur ↔ paklijst, colli en brutomassa ↔ vervoersdocument, betaling ↔ factuurtotaal, verzekerd bedrag ↔ CIF-waarde, oorsprongsbewijs ↔ factuur): code, ernst, melding, correctie, wettelijke bron, wie het oplost en beide vindplaatsen (document, veld, pagina of regel, citaat). Alleen als beide documenten in de set zitten en beide velden geëxtraheerd zijn.
  • correction_request Eén Engelse tekst voor de leverancier met de correcties van alle documenten en de aanvullende documenten. Null als er niets te vragen is. skipped somt de bestanden op die niet gecontroleerd zijn (name, reason, message).
  • Verder: reference, transport_mode, hs_codes, incoterm, transport_mode_used, file_count, credits, created_at, duration_ms, content_purged en content_expires_at.

404 — Onbekende uuid, of een document van een andere organisatie.

/v1/document-sets/{uuid}/pdf

Hetzelfde rapport als het setrapport in het dashboard, als PDF (application/pdf): het oordeel, de acties (prioriteit, actie, wie), de correcties per document, de ontbrekende en mogelijke documenten, het bericht aan de leverancier en de controlebasis. De taal volgt de Accept-Language-header; de bestandsnaam is dossiercontrole-{referentie}-{datum}.pdf (document-set-check-... in het Engels). Geeft 404 bij een onbekend uuid, zolang de set nog bezig is of mislukt is, en nadat de inhoud gewist is (24 uur).

curl "https://import8.nl/api/v1/document-sets/5b0d6f9e-3a41-4c8e-9d2a-7e1f0c4b8a63/pdf" \
  -H "Authorization: Bearer c8_your_api_key" \
  -o document-set-check.pdf
GET POST

/v1/classifications/{id}/audit

Een geauditeerde classificatie loopt op dezelfde motor als de autonome, maar pauzeert waar iets te beslissen valt: het productbeeld, beslissende feiten, de post, open onderverdelingen en de uitkomst. Je auditor voert het gesprek stap voor stap, precies zoals in het dashboard. Elke stap staat met antwoord, naam, tijd en onderbouwing in het verslag en het dossier. Start met mode=audited op POST /v1/classify.

Een geauditeerde classificatie kost 1 credit, net als in het dashboard. Mislukt de bepaling, dan wordt het credit teruggeboekt. Alleen een omschrijving of afbeeldingen; product_url alleen wordt niet ondersteund.

Endpoints

Endpoint Beschrijving
POST /v1/classify
mode=audited
Start met mode=audited en optioneel locale (taal van het verslag en de vragen). Antwoord 202 met id en status.
GET /v1/classifications/{id}/auditDe stand: run.status (running, waiting, done, failed) en etappe, het hele verslag als data (report: per bericht staptype, nummer, tekst, AIR, stempel en onderbouwing), de antwoorden tot nu toe met de Engelse motorwaarden ernaast, en open_question.
POST /v1/classifications/{id}/audit/answersBeantwoord de open vraag met een option (een id uit open_question.options) of vrije text in elke taal.
POST /v1/classifications/{id}/audit/steps/{step_id}/backTerug naar een eerdere stap. Er wordt niets opnieuw betaald; de latere stappen blijven bewaard maar tellen niet meer mee.
POST /v1/classifications/{id}/audit/attestBevestig de uitkomst met de naam van de auditor. Daarna is de bepaling bevroren.

Antwoorden

Parameter Type Beschrijving
optionstringEen id uit open_question.options, bijvoorbeeld confirm, assume (weet ik niet), q:0 of line:123. records zegt wat de optie vastlegt. Wordt zonder modelaanroep vastgelegd.
textstringVrij antwoord in elke taal. Eenduidige antwoorden ("ja", "klopt", "weet ik niet") gaan zonder modelaanroep; anders leest één goedkope aanroep het antwoord. Is het niet eenduidig, dan volgt een terugvraag en wordt niets vastgelegd.
step_idintegerOptioneel: de stap die je beantwoordt. Wacht een andere stap, dan volgt 409.
answered_bystringNaam van de auditor bij jou; komt op de stempel. Standaard de naam van de API-sleutel, anders van de organisatie.
localenl | enTaal van de teksten in het antwoord. Standaard de taal die bij de start is gekozen.

Het antwoord heeft result: recorded (vastgelegd; data is de nieuwe stand, eventueel met de volgende vraag of run.status=running), clarification (een terugvraag in clarification; niets vastgelegd) of rejected (met reason).

Voorbeeld: een volledig gesprek

question is de vriendelijke vraag van de vraagschrijver en kan null zijn; question_template is altijd gevuld. Toon question als die er is, anders het sjabloon.

# 1. Starten
curl -X POST "https://import8.nl/api/v1/classify" \
  -H "Authorization: Bearer c8_..." -H "Content-Type: application/json" \
  -d '{"description": "Staande ventilator, 220v", "mode": "audited", "locale": "nl"}'

{"success": true, "data": {"id": "9f1c…", "mode": "audited", "status": "processing", "run_status": "running"}}

# 2. De stand en de open vraag
curl "https://import8.nl/api/v1/classifications/9f1c…/audit" -H "Authorization: Bearer c8_..."

{"success": true, "data": {
  "run": {"status": "waiting", "stage": "candidates"},
  "open_question": {
    "step_id": 41, "question_id": "picture", "kind": "product_profile",
    "question": null,
    "question_template": "Klopt dat?",
    "why": null,
    "context": {"lead": "Ik zie: een staande elektrische ventilator voor 220 V.", "body": "Bedoeld om lucht te laten circuleren."},
    "options": [{"id": "confirm", "label": "Ja", "records": {"type": "confirm"}}],
    "free_text_allowed": true
  },
  "report": [ … ], "answers": [ … ]
}}

# 3. Het productbeeld klopt; de beslissende vraag volgt
curl -X POST ".../audit/answers" -d '{"option": "confirm", "answered_by": "J. de Vries"}'

{"success": true, "result": "recorded", "data": {"open_question": {
  "question_id": "fact:part_of", "kind": "product_profile",
  "question": "Is het een complete ventilator, klaar voor gebruik, of een los onderdeel?",
  "question_template": "Wat weet u over: onderdeel van?",
  "why": "Een los onderdeel valt onder 8414 90 of de post van dat onderdeel zelf.",
  "options": [
    {"id": "q:0", "label": "Compleet, klaar voor gebruik", "records": {"type": "fact", "key": "part_of", "value": "complete fan, ready for use"}},
    {"id": "q:1", "label": "Los onderdeel", "records": {"type": "fact", "key": "part_of", "value": "a separate part of a fan"}},
    {"id": "assume", "label": "Weet ik niet", "records": {"type": "assumption"}}
  ],
  "free_text_allowed": true
}}}

# 4. Vrij antwoord (elke taal)
curl -X POST ".../audit/answers" -d '{"text": "hij is compleet, met voet en kabel"}'

{"success": true, "result": "recorded", "answer": {"text": "hij is compleet, met voet en kabel", "english": "it is complete, with stand and cable", "interpreted_by": "model"}, …}

# 5. Een antwoord dat niet eenduidig is: terugvraag, niets vastgelegd
{"success": true, "result": "clarification", "clarification": "Ik begrijp uw antwoord niet helemaal. Bedoelt u dat het een andere post is?"}

# 6. De post
{"open_question": {"kind": "heading", "question": null, "question_template": "Gaat u akkoord met post 8414?",
  "options": [{"id": "confirm", "label": "Akkoord", "records": {"type": "confirm"}}]}}

# 7. De uitkomst
{"open_question": {"kind": "outcome", "question_template": "Bevestigt u deze classificatie?",
  "context": {"code": "8414.51.00.00"}, "options": [{"id": "confirm", "label": "Ik bevestig deze classificatie", "records": {"type": "confirm_outcome"}}],
  "free_text_allowed": false}}

# 8. Attesteren
curl -X POST ".../audit/attest" -d '{"answered_by": "J. de Vries"}'

{"success": true, "result": "attested", "data": {"attestation": {"attested_at": "2026-10-15T14:32:10+02:00", "attested_by": "J. de Vries"}}}

Webhooks

classification.awaiting_answer komt zodra de motor op een antwoord wacht, met de open vraag (question en question_template) in de payload. Een volgende vraag binnen dezelfde stap staat direct in het antwoord op je POST. classification.completed volgt als de uitkomst bevestigd is, classification.failed als de bepaling mislukt.

{"event": "classification.awaiting_answer",
 "data": {"id": "9f1c…", "status": "processing",
   "open_question": {"step_id": 43, "question_id": "decisive", "kind": "heading",
     "question": "Is het een complete ventilator of een los onderdeel?",
     "question_template": "Wat weet u over: onderdeel van?",
     "why": "Een complete ventilator valt onder 8414, een los onderdeel elders.",
     "options": [ … ], "free_text_allowed": true}}}

{"event": "classification.completed", "data": {"id": "9f1c…", "status": "completed"}}
{"event": "classification.failed", "data": {"id": "9f1c…", "status": "failed"}}

Gesprekstoken en rate limit

Elke open_question (en de stand zelf) bevat een ondertekend conversation_token, geldig 24 uur. Stuur het mee als header X-Import8-Conversation of als veld conversation_token bij de /audit-aanroepen van dezelfde classificatie: die tellen dan niet mee in de rate limit van je organisatie, maar in een eigen limiet per gesprek (60 per minuut). Zonder token, met een ongeldig of verlopen token, of met een token van een andere classificatie geldt de gewone limiet. Het token geeft geen toegang: de c8_-sleutel blijft vereist.

Fouten

404De classificatie bestaat niet, is van een andere organisatie of is niet geauditeerd.
409 no_open_questionEr wacht geen vraag: de motor is bezig of de bepaling is klaar.
409 step_not_waitingDe opgegeven step_id is niet de stap die wacht.
409 busy / not_attestableDe motor is bezig, de stap is al beslist, of attesteren kan nog niet of niet meer.
422Ongeldige invoer, bijvoorbeeld een option die niet in de lijst staat, of geen option en geen text.
429Rate limit van de organisatie; een gesprek telt per aanroep mee.
PUT

/v1/webhook

Configureer een webhook-URL om pushmeldingen te ontvangen wanneer classificaties worden voltooid of mislukken.

Let op: De webhook is alleen een melding. Hij bevat het classificatie-id, niet het resultaat. Haal de volledige data op via GET /v1/classifications/{id}.

Voorbeeld

curl -X PUT https://import8.nl/api/v1/webhook \
  -H "Authorization: Bearer c8_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook"}'

Response 200 OK

{
  "success": true,
  "data": {
    "url": "https://example.com/webhook"
  }
}
DELETE

/v1/webhook

Verwijder de geconfigureerde webhook. Je ontvangt geen meldingen meer.

curl -X DELETE https://import8.nl/api/v1/webhook \
  -H "Authorization: Bearer c8_your_api_key"

# Response:
{
  "success": true,
  "message": "Webhook removed."
}

Webhook Events

Wanneer een classificatie is verwerkt, stuurt Import8 een klein POST seintje naar je webhook-URL, met het eventtype in de X-Import8-Event header.

Event Beschrijving
classification.completed Classificatie succesvol afgerond
classification.failed Classificatie mislukt door een fout
classification.insufficient_information Het product is uit de omschrijving niet te identificeren; geen code, credit teruggeboekt (zie het insufficient-object)
classification.awaiting_answer Een geauditeerde classificatie wacht op een antwoord; de payload bevat de open vraag.

Headers

Header Beschrijving
X-Import8-Event Eventtype (bijv. classification.completed)
User-Agent Import8-Webhook/1.0

Voorbeeld Payload

{
  "event": "classification.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed"
  }
}

De webhook is een seintje, niet de data. Hij meldt alleen dat een classificatie klaar is (of mislukt) en bevat het id. Haal het volledige resultaat (HS-code, risk grading, documenten) op via de geauthenticeerde GET /v1/classifications/{id}. Het seintje bevat niets gevoeligs, want het resultaat zit achter je API-key. Elke webhook is wel ondertekend: zie Handtekening controleren hieronder.

Handtekening controleren

Elke webhook is ondertekend. De header X-Import8-Signature: t=1760536330,v1=5f2c… bevat een Unix-tijdstempel t en v1: een HMAC-SHA256 in hex met je signing secret over t, een punt en de ruwe body precies zoals ontvangen. Het secret ziet en roteert je op de webhookpagina van het dashboard (begint met whsec_). Controleer de HMAC in constante tijd en weiger een tijdstempel die meer dan 5 minuten afwijkt; dat houdt een opgevangen bericht tegen dat later opnieuw wordt afgespeeld.

# PHP
$body   = file_get_contents('php://input');            // raw body, before any json_decode
$header = $_SERVER['HTTP_X_IMPORT8_SIGNATURE'] ?? '';  // "t=...,v1=..."
parse_str(str_replace(',', '&', $header), $sig);
$ok = isset($sig['t'], $sig['v1'])
   && abs(time() - (int) $sig['t']) <= 300               // replay tolerance: 5 minutes
   && hash_equals(hash_hmac('sha256', $sig['t'].'.'.$body, getenv('IMPORT8_WEBHOOK_SECRET')), $sig['v1']);
if (! $ok) { http_response_code(401); exit; }

# Python
import hmac, hashlib, time
parts = dict(p.split('=', 1) for p in header.split(','))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
ok = abs(time.time() - int(parts['t'])) <= 300 and hmac.compare_digest(expected, parts['v1'])

Rate Limits

Rate limits worden per API key toegepast en zijn afhankelijk van je creditpakket. Elke API-response bevat rate limit headers:

Header Beschrijving
X-RateLimit-Limit Maximaal aantal verzoeken per venster
X-RateLimit-Remaining Resterende verzoeken in het huidige venster
X-RateLimit-Reset Unix-timestamp wanneer het venster reset

Bij overschrijding retourneert de API 429 Too Many Requests met een Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "success": false,
  "message": "Rate limit exceeded. Please retry after 30 seconds."
}

Foutcodes

De API gebruikt standaard HTTP-statuscodes:

Status Betekenis
200 Succesvol
202 Geaccepteerd: classificatie in wachtrij
401 Ongeldige of ontbrekende API key
404 Bron niet gevonden
422 Validatiefout: controleer de request body
429 Rate limit of verbruikslimiet overschreden
500 Serverfout

Foutresponse formaat

{
  "success": false,
  "message": "Description of the error"
}
Import8

Welkom terug

Log in op je account

Wachtwoord vergeten?

Nog geen account?

Import8

Account aanmaken

Begin met 5 gratis credits

Wat voor organisatie ben je? (optioneel)
Hoeveel zendingen per maand? (optioneel)

Heb je al een account?