SOAP zpráva v XML: Envelope, Header, Body, Fault

Požadavek: obálka, hlavička a tělo

SOAP zpráva se většinou posílá metodou POST přes HTTP. Ukázka volá smyšlenou službu, která vrací kurz měny:

HTTP požadavek (SOAP 1.1)

POST /sluzby/kurzy HTTP/1.1
Host: api.example.cz
Content-Type: text/xml; charset=utf-8
SOAPAction: "http://example.cz/kurzy/ZjistiKurz"

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:k="http://example.cz/kurzy">
  <soap:Header>
    <k:IdPozadavku>7f3c1a2e-5b1d-4c9e-9a61-2f0d8b7e4c11</k:IdPozadavku>
  </soap:Header>
  <soap:Body>
    <k:ZjistiKurz>
      <k:Mena>EUR</k:Mena>
      <k:Datum>2026-09-29</k:Datum>
    </k:ZjistiKurz>
  </soap:Body>
</soap:Envelope>

Envelope je kořen zprávy. Jeho jmenný prostor určuje verzi SOAP — server podle něj pozná, jak zprávu číst.
Header je nepovinný a nese metadata: přihlášení, identifikátor požadavku, adresování (WS-Addressing). Atribut mustUnderstand="1" říká, že server zprávu musí odmítnout, pokud je hlavička určená jemu a neumí ji zpracovat podle jejích pravidel.
Body nese obsah zprávy. V tomto příkladu jde o volání operace s parametry, ale SOAP umožňuje i předání dokumentu bez takové konvence. Podobu obsahu určuje popis konkrétní služby, obvykle WSDL a XSD.

Odpověď

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:k="http://example.cz/kurzy">
  <soap:Body>
    <k:ZjistiKurzResponse>
      <k:Kurz>24.315</k:Kurz>
      <k:Mnozstvi>1</k:Mnozstvi>
    </k:ZjistiKurzResponse>
  </soap:Body>
</soap:Envelope>

Odpověď má stejnou obálku, v těle je podle konvence prvek …Response. Při čtení hledej prvky podle jmenného prostoru, ne podle prefixu — server může použít ns2: místo k: a pořád jde o stejnou zprávu.

Chyba: Fault

Když služba požadavek nezpracuje, vrátí v těle prvek Fault (u HTTP se stavovým kódem 500, u chyb klienta v SOAP 1.2 i 400). Rozhraní se liší podle verze:

Fault v SOAP 1.1

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring xml:lang="cs">Neznámá měna: XYZ</faultstring>
      <detail>
        <k:Chyba xmlns:k="http://example.cz/kurzy"><k:Kod>E102</k:Kod></k:Chyba>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

Fault v SOAP 1.2

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">
  <env:Body>
    <env:Fault>
      <env:Code><env:Value>env:Sender</env:Value></env:Code>
      <env:Reason><env:Text xml:lang="cs">Neznámá měna: XYZ</env:Text></env:Reason>
    </env:Fault>
  </env:Body>
</env:Envelope>

SOAP 1.1 vs. SOAP 1.2

	SOAP 1.1	SOAP 1.2
Jmenný prostor obálky	http://schemas.xmlsoap.org/soap/envelope/	http://www.w3.org/2003/05/soap-envelope
Content-Type	text/xml	application/soap+xml
Údaj o akci v HTTP	hlavička SOAPAction; může být prázdná	volitelný parametr action v Content-Type
Struktura chyby	faultcode, faultstring, detail	Code/Value, Reason/Text, Detail
Kódy chyb	Client, Server	Sender, Receiver (a další)

Nejčastější chyba při ručním volání: obálka verze 1.2 poslaná s Content-Type: text/xml (nebo naopak). Server pak odpoví chybou o nepodporovaném typu obsahu nebo „VersionMismatch“.

WSDL a WS-Security

Popis služby je v souboru WSDL (také XML): jaké má operace, jaké XSD typy přijímá a vrací a na jaké adrese běží. Z WSDL si klienta vygeneruje většina prostředí (dotnet-svcutil, wsimport ze samostatné implementace JAX-WS v Javě, SoapClient v PHP, zeep v Pythonu). Přihlášení se často předává v hlavičce podle WS-Security:

WS-Security UsernameToken

<soap:Header xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <wsse:Security soap:mustUnderstand="1"
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
    <wsse:UsernameToken>
      <wsse:Username>uzivatel</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">…</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Jak SOAP službu zavolat a ladit

curl

curl https://api.example.cz/sluzby/kurzy \
  -H 'Content-Type: text/xml; charset=utf-8' \
  -H 'SOAPAction: "http://example.cz/kurzy/ZjistiKurz"' \
  --data-binary @pozadavek.xml

U zprávy, kterou teprve vytváříš, nejdřív ověř XML syntaxi a požadovanou strukturu. Neuzavřená značka může způsobit chybu parseru, HTTP chybu nebo Fault; konkrétní reakci určuje server.
Vygeneruj z WSDL ukázkový požadavek (SoapUI, Postman) a porovnej ho se svým ve strukturálním diffu.
Parsery na straně serveru i klienta nastav bez externích entit — SOAP je častým cílem útoku XXE.

Akce, HTTP stav a aktuální nástroje

SOAPAction ani parametr action nejsou univerzální náhradou názvu operace v těle. SOAP 1.1 při použití své HTTP vazby vyžaduje hlavičku SOAPAction, jejíž hodnota může být prázdná. V SOAP 1.2 je action volitelný parametr média application/soap+xml; jeho případné použití určuje služba. Pravidla uvádí SOAP 1.1 a SOAP 1.2 Part 2.

Při chybě čti HTTP stav i případný Fault. Odpověď nemusí vždy obsahovat SOAP: mezilehlý server může vrátit například HTML chybovou stránku. Nástroj wsimport už není součástí JDK od verze 11; potřebuješ samostatnou implementaci JAX-WS. Tuto změnu popisuje migrační dokumentace JDK.