Brazil Receita WS SDKs & Libraries: Official & Community (2026)

SDKs overview

The Brazil Receita WS (Web Services of the Brazilian Federal Revenue Service) provides programmatic interfaces for accessing various public tax and registration data. While the Receita Federal primarily offers SOAP-based web services, developers often use Software Development Kits (SDKs) and libraries to simplify interaction with these endpoints. These tools abstract the complexities of XML parsing, digital certificate handling, and request/response serialization, enabling more efficient integration into applications requiring fiscal data validation or retrieval.

Integrating with Brazil Receita WS typically involves handling digital certificates (e-CNPJ or e-CPF) for authentication, which requires specific cryptographic library support in SDKs. The choice between official and community-contributed libraries often depends on the developer's language preference, project requirements, and the level of abstraction desired over the underlying SOAP or REST communication protocols. Many community libraries focus on providing simpler HTTP client interfaces for specific Receita Federal services that might expose RESTful endpoints or for services that have been wrapped by third-party providers to offer a REST-like experience.

Official SDKs by language

The Brazilian Federal Revenue Service (Receita Federal do Brasil) primarily publishes technical documentation for its web services, detailing the WSDLs (Web Services Description Language) and schemas, rather than providing pre-built, language-specific SDKs in the traditional sense. However, the documentation often includes guidelines and code samples in common enterprise languages that serve as de facto official starting points for developers. These are generally focused on demonstrating how to consume SOAP services and handle digital certificates. The core interaction mechanism is based on web service standards, as detailed by the Receita Federal do Brasil's service access information.

The following table summarizes the common approaches and pseudo-SDKs or reference implementations that are often considered 'official' because they are directly supported or showcased in Receita Federal's technical guides:

Installation

Installation for Brazil Receita WS interactions largely depends on the chosen language and the specific web service client library. Since there isn't a single, unified SDK installer, the process involves setting up standard development environments and then installing relevant SOAP or HTTP client libraries.

Java

For Java projects, you typically add dependencies to your build tool. For example, using Maven:

<dependencies>
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-frontend-jaxws</artifactId>
        <version>3.5.0</version>
    </dependency>
    <dependency>
        <groupId>org.apache.cxf</groupId>
        <artifactId>cxf-rt-transports-http</artifactId&n>
        <version>3.5.0</version>
    </dependency>
</dependencies>

Certificate handling requires configuring a KeyStore and TrustStore, typically involving Java's java.security packages. More information on secure communication in Java can be found in the AWS SDK for Java documentation on certificates, which provides relevant concepts for handling secure connections.

Python

For Python, client libraries are installed via pip:

pip install suds-py3
# or
pip install zeep
pip install requests

Digital certificate integration often involves libraries like requests with custom SSL context or pyOpenSSL for advanced certificate management, as outlined in the Mozilla Developer Network's guide to HTTP authentication for general principles.

C# (.NET)

In .NET, you usually add a service reference to your project. This generates client proxy classes from the WSDL. For example, in Visual Studio:

1. Right-click on your project in Solution Explorer.
2. Select "Add" > "Service Reference..."
3. Enter the WSDL URL for the Receita WS endpoint.
4. Configure client settings in App.config or Web.config, including specifying the X.509 client certificate for authentication.

Quickstart example

This example demonstrates a basic interaction with a hypothetical Receita WS endpoint for CNPJ validation using Python with the zeep library for SOAP and requests for certificate handling. Note that actual Receita WS endpoints and WSDLs must be obtained from the official Receita Federal documentation.

import os
from zeep import Client, Transport
from requests import Session
from requests.adapters import HTTPAdapter

# --- Configuration (replace with your actual certificate paths and CNPJ) ---
WSDL_URL = "https://example.receita.ws/service?wsdl" # Placeholder: Replace with actual WSDL URL
CERT_FILE = "/path/to/your/certificate.pem" # Path to your e-CNPJ/e-CPF certificate
KEY_FILE = "/path/to/your/private_key.pem" # Path to your certificate's private key
PASSWORD = "your_certificate_password" # Your certificate password
TARGET_CNPJ = "12345678000100" # Example CNPJ

# --- Setup HTTP Session with Client Certificate ---
# Zeep uses requests for transport, so we configure a requests.Session
session = Session()
session.cert = (CERT_FILE, KEY_FILE) # For PEM files. For PFX, you might need extra handling.
# If your certificate requires a password and is in PFX format, 
# you might need to use a custom transport adapter or convert it.

# Create a Zeep client with the configured session
transport = Transport(session=session)
client = Client(WSDL_URL, transport=transport)

# --- Call the Web Service (Hypothetical CNPJ Validation) ---
try:
    # Assuming a service method like 'consultarCnpj' that takes a CNPJ string
    # The actual method name and parameters will vary based on the WSDL
    response = client.service.consultarCnpj(cnpj=TARGET_CNPJ)
    print(f"CNPJ Validation Response for {TARGET_CNPJ}:")
    print(response)

    # Example of accessing response data (structure depends on WSDL)
    if hasattr(response, 'Status') and response.Status == 'OK':
        print(f"Status: {response.Status}")
        print(f"Company Name: {response.NomeEmpresa}") # Placeholder
    else:
        print("Validation failed or unexpected response structure.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure your WSDL URL, certificate paths, and service method calls are correct.")

This quickstart illustrates the typical steps: configuring an HTTP client with digital certificate credentials and then invoking a SOAP service method. Developers must consult the specific WSDL and documentation for the Receita WS endpoint they intend to use to determine the exact method names, parameters, and response structures. For more details on Python's requests library and SSL certificate handling, refer to the Requests documentation on client-side certificates.

Community libraries

Given the complexity of Brazil Receita WS's SOAP-based services and digital certificate requirements, various community-driven libraries and wrappers have emerged to simplify integration. These libraries often aim to provide a more idiomatic interface for specific programming languages or to abstract away the underlying SOAP communication, sometimes by re-exposing select Receita Federal services through a simpler REST-like interface.

Python

• python-receitaws: A community library that wraps some ReceitaWS services, often focusing on CNPJ queries, sometimes relying on third-party proxies that expose Receita Federal data. Developers should verify the data source and up-to-dateness.
• receita-federal-ws-client: Another Python library that attempts to streamline interactions, particularly for certificate-based authentication and SOAP calls to specific endpoints. Its effectiveness depends on maintenance and alignment with current Receita Federal WSDLs.

PHP

• laravel-receitaws: For PHP developers using the Laravel framework, there are packages designed to integrate ReceitaWS queries directly into Laravel applications. These often leverage Guzzle HTTP client for requests and may integrate with external services that provide simplified access to Receita Federal data.
• php-cnpj: A library focused specifically on CNPJ consultation, which may include integration points for Receita Federal data or similar public sources.

Node.js/JavaScript

• receitaws-node: A Node.js module that provides an interface for querying CNPJ information. Similar to Python counterparts, it might interact directly with public Receita Federal endpoints or through intermediary services.
• soap (NPM package): While not specific to Receita WS, the generic soap client for Node.js is frequently used by the community to build custom wrappers for Receita Federal's SOAP services, handling WSDL parsing and request/response serialization.

When considering community libraries, it is important to:

• Verify the source: Ensure the library's interaction method (direct to Receita Federal or via a third-party proxy) aligns with your security and compliance requirements.
• Check maintenance status: Actively maintained libraries are more likely to support changes in Receita Federal's web services or underlying security protocols.
• Review documentation and examples: Good documentation helps in understanding how to correctly handle digital certificates and interpret service responses.

Developers should always consult the official Receita Federal documentation for the most accurate and up-to-date information regarding service endpoints, WSDLs, and authentication protocols.