Brazil runs the largest mandatory e-invoicing system on Earth. Every invoice, every truckload, every retail receipt in a $2T economy passes through government SOAP 1.2 webservices. In 2026.
Want to integrate? The documentation is four PDF manuals totaling over 1,000 pages, spread across different portals, with critical details that are simply not written anywhere. Two examples we paid for in hours of debugging: the freight document (CT-e) and the manifest (MDF-e) implement the same distribution spec with incompatible envelopes (one wraps the payload and requires an author state code, the other rejects that field and wants the state code in the SOAP header). And the SOAP action must travel inside the Content-Type header; send a SOAPAction header like every SOAP tutorial on the internet tells you to, and the server refuses you without explaining why.
So we mapped all 29 webservices across the 4 document models into one Postman collection: ready-to-fire envelopes, per-host mTLS certificate setup documented, and the distribution services validated against the production government endpoints, not just written from the manuals.
Where you can make it better: Brazil has 27 states and several run their own authorizer URLs (Sao Paulo's retail invoices, for one). We cover the shared authorizer plus the national environment; state-specific URL mappings are the top open contribution. The collection is generated from a Python inventory file, so a PR is a 5-line diff, not JSON surgery.
Docs in Portuguese (the devs suffering with this are Brazilian), but I'll answer anything here in English.
So, first up: why? Why is everything still using SOAP? I'm not talking down on Brazil, by the way. I've worked in American healthcare tech, and at some point you find yourself learning EDI to talk to insurance companies.
Maybe it's a solved problem and SOAP 1.2 is good enough for that particular job.
We _still_ use TCP/IP and it's v4 is from 1981.
edit: I once looked deep into Remote PowerShell. How it's actually built. Dear. God. XML enveloped inside XML inside another XML wrapped around HTTP. Add some certificate based encryption for the HTTP envelope and some more encryption for the Kerberos messaging inside the serialized XML wrapped in envelopes and wrappings. Now THAT'S a communication protocol. :D
SOAP is terrible[1], but if the whole country is on board, change is very difficult and you're not going to move to anything simpler because it would either be too simple to actually satisfy the need or too simple to satisfy the selection comittee.
[1] The whole thing with wsdl is like an elaborate prank. Without fail, the WSDL files are impossible to obtain and don't reflect the service as deployed or documented. Documented equivalent forms will not be treated as equivalent. Two instances of a 'standard' service will not accept the same XML. And I only worked with simple SOAP services with straight forward payloads.
The answer is probably "because SOAP was the hot new thing when they first decided to do this".
Working with enterprise software is in general a horrific experience, especially that which originated in the 90s at the peak of OOP dogma-cults and insane architecture-astronautism abstraction mixed with SOLIDly thick levels of bureaucracy.
My memories of COM, CORBA, DCE/RPC, XML, etc. are not great. Some of the stuff reads like satire today, but people were actually serious about it: https://en.wikipedia.org/wiki/Object_Management_Group (I recall an article in a physical magazine long ago which started with "The Object Management Group's Working Task Force, also known as OMGWTF...")
It's a perfectly fine protocol, with a rigid schema and mature code generation support for all relevant languages. It's not the sexiest protocol, but it gets the job done.
> mature code generation support for all relevant languages.
Heh, "relevant languages" is kind of an interesting term there. If the relevant language is Java then sure, it's fine.
Some of the popular modern languages (ie GO) don't have good SOAP support, at least not to the point of being able to point them at WSDL/XSD specs and have everything auto-generated. :(
It's based on XML and XML is a cursed format, because it does not cleanly separate parsing from evaluation. Because of this flaw, whatever words they want to use, it does not have real schemas, it has programs and a validator-evaluator, which performs network IO.
It’s been a long time since I had to work in SOAP. Does https://soapy.sourceforge.net/ atill work? That would make things easier to automate if so. This is awesome work.
have there been any "here's a nicer wrapper API" services out there? Or is the complexity somewhat upstream of "real" complexity/differences in reporting.
Brazil runs the largest mandatory e-invoicing system on Earth. Every invoice, every truckload, every retail receipt in a $2T economy passes through government SOAP 1.2 webservices. In 2026.
Want to integrate? The documentation is four PDF manuals totaling over 1,000 pages, spread across different portals, with critical details that are simply not written anywhere. Two examples we paid for in hours of debugging: the freight document (CT-e) and the manifest (MDF-e) implement the same distribution spec with incompatible envelopes (one wraps the payload and requires an author state code, the other rejects that field and wants the state code in the SOAP header). And the SOAP action must travel inside the Content-Type header; send a SOAPAction header like every SOAP tutorial on the internet tells you to, and the server refuses you without explaining why.
So we mapped all 29 webservices across the 4 document models into one Postman collection: ready-to-fire envelopes, per-host mTLS certificate setup documented, and the distribution services validated against the production government endpoints, not just written from the manuals.
Where you can make it better: Brazil has 27 states and several run their own authorizer URLs (Sao Paulo's retail invoices, for one). We cover the shared authorizer plus the national environment; state-specific URL mappings are the top open contribution. The collection is generated from a Python inventory file, so a PR is a 5-line diff, not JSON surgery.
Docs in Portuguese (the devs suffering with this are Brazilian), but I'll answer anything here in English.
So, first up: why? Why is everything still using SOAP? I'm not talking down on Brazil, by the way. I've worked in American healthcare tech, and at some point you find yourself learning EDI to talk to insurance companies.
Maybe it's a solved problem and SOAP 1.2 is good enough for that particular job.
We _still_ use TCP/IP and it's v4 is from 1981.
edit: I once looked deep into Remote PowerShell. How it's actually built. Dear. God. XML enveloped inside XML inside another XML wrapped around HTTP. Add some certificate based encryption for the HTTP envelope and some more encryption for the Kerberos messaging inside the serialized XML wrapped in envelopes and wrappings. Now THAT'S a communication protocol. :D
SOAP is terrible[1], but if the whole country is on board, change is very difficult and you're not going to move to anything simpler because it would either be too simple to actually satisfy the need or too simple to satisfy the selection comittee.
[1] The whole thing with wsdl is like an elaborate prank. Without fail, the WSDL files are impossible to obtain and don't reflect the service as deployed or documented. Documented equivalent forms will not be treated as equivalent. Two instances of a 'standard' service will not accept the same XML. And I only worked with simple SOAP services with straight forward payloads.
The answer is probably "because SOAP was the hot new thing when they first decided to do this".
Working with enterprise software is in general a horrific experience, especially that which originated in the 90s at the peak of OOP dogma-cults and insane architecture-astronautism abstraction mixed with SOLIDly thick levels of bureaucracy.
My memories of COM, CORBA, DCE/RPC, XML, etc. are not great. Some of the stuff reads like satire today, but people were actually serious about it: https://en.wikipedia.org/wiki/Object_Management_Group (I recall an article in a physical magazine long ago which started with "The Object Management Group's Working Task Force, also known as OMGWTF...")
SOAP is good for flexible APIs due to xml “eats anything”, the “included” support for signatures and schema validation.
Why it _shouldn't_ be SOAP?
It's a perfectly fine protocol, with a rigid schema and mature code generation support for all relevant languages. It's not the sexiest protocol, but it gets the job done.
And what are the alternatives? JSON schema?
> mature code generation support for all relevant languages.
Heh, "relevant languages" is kind of an interesting term there. If the relevant language is Java then sure, it's fine.
Some of the popular modern languages (ie GO) don't have good SOAP support, at least not to the point of being able to point them at WSDL/XSD specs and have everything auto-generated. :(
An adaptation of PEPPOL (also XML, but at least standardised)?
And what are the alternatives? JSON schema?
ASN.1? It's even more mature, and the de-facto DER/BER encoding is far more efficient to generate and parse than anything XML-based.
It's based on XML and XML is a cursed format, because it does not cleanly separate parsing from evaluation. Because of this flaw, whatever words they want to use, it does not have real schemas, it has programs and a validator-evaluator, which performs network IO.
I think the biggest problems with SOAP was the implementations, never the standard. WCF...
It’s been a long time since I had to work in SOAP. Does https://soapy.sourceforge.net/ atill work? That would make things easier to automate if so. This is awesome work.
Great job. Are there any interesting facts or anecdotes you found while perusing content?
have there been any "here's a nicer wrapper API" services out there? Or is the complexity somewhat upstream of "real" complexity/differences in reporting.