Correios SDKs & Libraries: Integration Guides (2026)

SDKs overview

Correios, as the national postal service of Brazil, provides Application Programming Interfaces (APIs) primarily for businesses and developers to integrate services such as parcel tracking, shipping calculation, and label generation directly into their applications or e-commerce platforms. The primary API solution offered by Correios is known as WSPro (Web Service for Products and Services), which is largely based on SOAP (Simple Object Access Protocol) and utilizes XML for data exchange Correios WSPro documentation.

Due to the nature of SOAP APIs, direct SDKs in the modern sense (like RESTful API wrappers) are less common from Correios directly. Instead, developers often interact with the WSPro service using standard web service client libraries available in various programming languages. These libraries handle the XML marshalling and unmarshalling, allowing developers to call remote methods as if they were local functions. The integration typically involves generating client code from the provided WSDL (Web Services Description Language) file W3C WSDL specification.

Access to the commercial WSPro APIs generally requires a prior registration process and a commercial agreement with Correios. This ensures that businesses integrating with the service comply with Correios's policies and retrieve appropriate credentials for authentication. The developer experience is often characterized by navigating XML structures and Portuguese-language documentation, which can present a learning curve for international developers Correios developer resources.

Official SDKs by language

Correios does not provide officially maintained, language-specific SDKs in the same manner as many modern REST API providers. Instead, developers typically generate client stubs from the WSPro WSDL file using tools native to their chosen programming language. This approach is standard for SOAP-based web services.

The WSDL defines the operations, messages, and schemas for the web service, allowing development environments to create proxy classes that encapsulate the complexities of SOAP communication. For instance, in Java, tools like Apache CXF or JAX-WS can generate client code from a WSDL. In .NET, Visual Studio can generate service references. For PHP, libraries such as SoapClient are used. Python also has libraries like suds-py3 that can consume WSDLs.

Despite the absence of conventional SDKs, the official documentation provides detailed specifications for interacting with the WSPro services, including XML request and response structures for various operations like calculating shipping costs (CalcPrecoPrazo) and tracking objects (ConsultaCEP, SRO). The onus is on the developer to implement or generate the client-side code that adheres to these specifications.

Installation

Installation for interacting with Correios WSPro services varies by programming language, as it often involves utilizing built-in SOAP client capabilities or common third-party libraries for SOAP consumption rather than installing a dedicated Correios SDK.

PHP

PHP's SoapClient is a built-in extension. Ensure it is enabled in your php.ini configuration file. You can check by running php -m | grep soap. If not enabled, typically you would enable it by uncommenting extension=soap in php.ini and restarting your web server.

<?php
  // Check if SoapClient is available
  if (extension_loaded('soap')) {
      echo "SoapClient is enabled.";
  } else {
      echo "SoapClient is not enabled. Please check php.ini.";
  }
?>

Python

For Python, suds-py3 is a widely used library for consuming SOAP web services. It can be installed via pip:

pip install suds-py3

Java

In Java, tools like JAX-WS (included in JDK) or Apache CXF can generate client code from a WSDL. For runtime, you would include the necessary dependencies in your build system (e.g., Maven or Gradle). For JAX-WS, no explicit dependency might be needed beyond the JDK. For Apache CXF, typical Maven dependencies would include:

<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-frontend-jaxws</artifactId>
    <version>3.4.5</version> <!-- Use a recent stable version -->
</dependency>
<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http</artifactId>
    <version>3.4.5</version>
</dependency>

.NET (C#)

In a .NET project, you typically add a 'Service Reference' or 'Connected Service' in Visual Studio, pointing to the Correios WSDL URL. Visual Studio then generates all necessary proxy classes and configuration automatically.

// No direct installation command; add via Visual Studio IDE
// Example using generated proxy:
// var client = new CorreiosService.CalcPrecoPrazoWSClient();
// var result = client.CalcPrecoPrazo(...);

Quickstart example

This example demonstrates how to use a generic SOAP client (Python with suds-py3) to interact with a hypothetical Correios WSPro service endpoint for calculating shipping costs. Actual credentials and specific WSDL URLs would be obtained after registration with Correios.

Note: The WSDL URL used here is illustrative. Developers must use the official, current WSDL URL provided by Correios after obtaining their commercial agreement and credentials Correios API documentation.

from suds.client import Client
from suds.sax.text import Raw

# Replace with the actual Correios WSDL URL and credentials
WSDL_URL = 'http://ws.correios.com.br/calculador/CalcPrecoPrazo.asmx?wsdl' # Example WSDL

# Correios service codes (examples)
SERVICE_PAC = '04510' # PAC service code
SERVICE_SEDEX = '04014' # SEDEX service code

# Your credentials (obtained from Correios after registration)
COMPANY_CODE = 'YOUR_COMPANY_CODE' # Code provided by Correios
PASSWORD = 'YOUR_PASSWORD'       # Password provided by Correios

def calculate_shipping_cost(
    company_code, password, service_code, origin_cep, destination_cep,
    package_weight_kg, package_length_cm, package_height_cm, package_width_cm,
    package_diameter_cm, declare_value=0.0, own_hand=False, receipt_notification=False
):
    client = Client(WSDL_URL)

    # Parameters for CalcPrecoPrazo method
    args = {
        'nCdEmpresa': company_code,
        'sDsSenha': password,
        'nCdServico': service_code,
        'sCepOrigem': origin_cep,
        'sCepDestino': destination_cep,
        'nVlPeso': str(package_weight_kg), # Weight in kg (e.g., '1.5')
        'nCdFormato': 1, # 1=Box/Package, 2=Roll/Prism, 3=Envelope
        'nVlComprimento': package_length_cm, # Length in cm
        'nVlAltura': package_height_cm,     # Height in cm
        'nVlLargura': package_width_cm,     # Width in cm
        'nVlDiametro': package_diameter_cm,   # Diameter in cm (if format 2)
        'sCdMaoPropria': 'S' if own_hand else 'N',
        'nVlValorDeclarado': declare_value, # Declared value in BRL
        'sCdAvisoRecebimento': 'S' if receipt_notification else 'N',
    }

    try:
        result = client.service.CalcPrecoPrazo(args)
        return result.cServicos.Servicos # Access the list of services found
    except Exception as e:
        print(f"An error occurred: {e}")
        return None

# Example Usage:
if __name__ == "__main__":
    # Replace with actual data
    origin_cep = '20000000' # Example Origin CEP
    destination_cep = '01000000' # Example Destination CEP
    weight = 1.0 # kg
    length = 20 # cm
    height = 10 # cm
    width = 15 # cm
    diameter = 0 # cm (for boxes, set to 0)

    # Calculate PAC shipping
    pac_services = calculate_shipping_cost(
        COMPANY_CODE, PASSWORD, SERVICE_PAC,
        origin_cep, destination_cep, weight, length, height, width, diameter
    )
    if pac_services:
        for service in pac_services:
            print(f"PAC Service: {service.nCdServico}")
            print(f"  Value: {service.nVlValor}")
            print(f"  Delivery Time: {service.PrazoEntrega} days")
            print(f"  Error: {service.MsgErro}")

    print("\n---\n")

    # Calculate SEDEX shipping
    sedex_services = calculate_shipping_cost(
        COMPANY_CODE, PASSWORD, SERVICE_SEDEX,
        origin_cep, destination_cep, weight, length, height, width, diameter
    )
    if sedex_services:
        for service in sedex_services:
            print(f"SEDEX Service: {service.nCdServico}")
            print(f"  Value: {service.nVlValor}")
            print(f"  Delivery Time: {service.PrazoEntrega} days")
            print(f"  Error: {service.MsgErro}")

Community libraries

Given the SOAP-based nature of Correios's WSPro API, many community-contributed libraries are essentially wrappers or more user-friendly interfaces built on top of the standard SOAP client implementations. These libraries aim to simplify common interactions, such as calculating freight or tracking packages, by providing more idiomatic functions for specific programming languages.

While an exhaustive list is beyond the scope here, popular environments for these community efforts include PHP, Python, and JavaScript (Node.js). Developers often share these implementations on platforms like GitHub or through package managers specific to their language (e.g., Composer for PHP, npm for Node.js, PyPI for Python).

When selecting a community library, it's advisable to consider the following factors:

• Maintenance Status: Is the library actively maintained and compatible with the latest Correios API changes?
• Documentation: Is there clear documentation, preferably in English, for installation and usage?
• Community Support: Is there an active community or maintainer responsive to issues and pull requests?
• Features: Does the library cover the specific Correios services you intend to use (e.g., CalcPrecoPrazo, SRO for tracking)?
• License: Is the library released under an open-source license compatible with your project?

Examples of common types of community libraries might include:

• PHP Wrappers: Libraries that provide a simpler object-oriented interface over PHP's SoapClient for Correios-specific functions.
• Python Classes: Modules that abstract the XML request/response handling for tracking or shipping calculations.
• Node.js Modules: JavaScript packages that facilitate asynchronous calls to the Correios SOAP endpoints, often using libraries like soap or axios with XML parsing.

Searching on respective package managers (e.g., Packagist for PHP, PyPI for Python, npm for Node.js) with keywords like "Correios," "frete," or "rastreamento" can help discover relevant community contributions. Always review the source code and reliability of any third-party library before integrating it into a production environment.