Birbla

Join the discussion

Write your take first — we'll ask for email only when you're ready to publish.

Sign in
  • Hacker News
  • 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.

    by lestx
  • Did you try to tell them about the incompatibilities and ways to improve? How did they react?
    by M95D
  • I dealt with Brazil payment system before and if is not bad at all. If could be simpler, but it is a plain 3/5. But Brazil taxes cannot be built not even by PhD 600 GPU Next Gen Hacker AI
    by motbus3
  • Why Postman? There are nicer, git friendlier options for something being shown as a git repo primarily.
    by nidnogg
  • Hold up, the alternatives I’m familiar are (UK) involve sending arbitrary documents which are read by humans, or ingressed into matching systems to then be checked by humans, so that key fields can be extracted…

    I read every invoice goes through a standard interface an improvement, no?

    by uefifjfj384
  • What’s the rationale of all this? I mean countries have gotten (mostly) rid of black books without such systems. Maintaining such a solution must be horribly expensive and what if it goes down?
    by belZaah
  • 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.
    by kstrauser
  • E-invoicing has been mandatory in Italy too for a while. The rollout started in 2014, but it took years to complete. The main integration system is based on the exchange of XML files via SFTP.

    So sending an invoice means leaving an XML file in a folder, then polling the server and waiting a few hours to get a response in the form of another XML file in another folder.

    You can also integrate via web service, but I think SFTP is still the most popular method, especially for its batching capabilities.

    by agopaul
  • SOAP 1.2 strikes me as really reasonable - it's a mature format with interop to several languages and has schema validation.

    The inconsistencies you describe above are probably due to each org in the government implementing the common spec independently of the others, and introducing differences without even knowing. Documentation is key here, but as with any large system, there can be gaps.

    It's really cool that you mapped it all.

    And kudos to Brazil for creating a common computerized platform.

    by uncle_kostya
  • Oh gosh. I could only imagine how many apps in chain crafts and parses soap envelopes with adhoc code with mandatory info loss.
    by bvrmn
  • Every SAML IdP (and there are still a lot) using the Artifact binding runs on SOAP 1.2, so what.
    by bdauvergne
  • seems like a great idea, as long as it's well maintained etc
    by bluegatty
  • Similar in Georgia https://eservices.rs.ge/app/Downloads

    XML/SOAP based protocol was created with modern at the time .Net technologies, but nobody really cared about interoperability, so it screams "old .Net" now.

    by adontz
  • This sounds similar to Ukrainian cash registers. Every retail operation goes through a cash register API on the tax agency side (because who would not love to keep some cash off the books, right), but there it is RESP+JSON and a cottage industry of services running it for you. It would not even be that hard is it wasn't sneaking the whole PKI into it.
    by Muromec
  • When we rolled out an ERP in our Brazil subsidiary the whole internal consulting team immediately agreed to leave our brains untouched by this complexity and hire a local consultant team as help. And the local consultant team in turn immediately suggested useing a middleware provider.
    by mhl47
  • It isn't that bad, at least XML is machine friendly, supports schema validation, and does comments, contrary to its replacements that had to rediscover why such features matter.

    As for performance, that was also rediscovered why none of them are great, thus gRPC rediscovering CORBA, COM and Sun RPC.

    by pjmlp
  • Comments were intentionally not included in JSON to prevent anyone adding extensions via preprocessor directives, IIRC
    by ehe78qhe