Tighten API contract and simplify documentation

tests/test_api.py

@@ -38,12 +38,37 @@ def test_match_contract_and_message_order() -> None:
             assert 0.0 <= candidate["confidence"] <= 1.0
 
 
+def test_task_example_uses_required_request_and_response_shape() -> None:
+    message = "саморезы по дереву 4.2 на 75, пачку"
+    response = client.post("/match", json={"messages": [message]})
+
+    assert response.status_code == 200
+    body = response.json()
+    assert set(body) == {"results"}
+    assert len(body["results"]) == 1
+
+    result = body["results"][0]
+    assert set(result) == {"message", "status", "candidates"}
+    assert result["message"] == message
+    assert result["status"] in {"matched", "ambiguous", "not_found"}
+    for candidate in result["candidates"]:
+        assert set(candidate) == {"sku", "confidence"}
+        assert isinstance(candidate["sku"], str)
+        assert isinstance(candidate["confidence"], float)
+
+
 def test_empty_message_list_is_valid() -> None:
     response = client.post("/match", json={"messages": []})
     assert response.status_code == 200
     assert response.json() == {"results": []}
 
 
+def test_messages_field_is_required() -> None:
+    response = client.post("/match", json={})
+
+    assert response.status_code == 422
+
+
 def test_unknown_request_fields_are_rejected() -> None:
     response = client.post("/match", json={"messages": [], "debug": True})
     assert response.status_code == 422