Correios Getting Started: API Access & First Request (2026)

Getting started overview

Integrating with Correios, Brazil's national postal service, primarily involves utilizing their WSPro (Web Service for Postal Objects) API. This service facilitates tracking, calculating shipping costs, and managing various postal operations programmatically. Unlike many RESTful APIs, Correios's WSPro is a SOAP-based service, meaning interactions are typically conducted using XML messages over HTTP. This requires understanding WSDL (Web Services Description Language) definitions and SOAP envelopes for structuring requests and parsing responses.

The process of getting started with Correios APIs involves several key steps:

1. Account Registration: Establishing a commercial account with Correios.
2. Credential Acquisition: Obtaining specific API credentials (username, password, and potentially a contract number) after your account is approved.
3. Environment Setup: Configuring your development environment to send SOAP requests and handle XML responses.
4. First Request: Constructing and sending an initial request, such as a basic tracking query, to verify your setup and credentials.

It is important to note that the official Correios developer documentation is primarily available in Portuguese, which may require translation for non-Portuguese speakers. Access to the full range of API services, beyond basic public tracking, typically necessitates a commercial agreement with Correios. For detailed information on the WSPro API, consult the official Correios WSPro documentation.

Create an account and get keys

Accessing the full range of Correios APIs, particularly for commercial operations like bulk tracking or shipping label generation, requires a formal commercial agreement and specific credentials. The process typically involves:

1. Commercial Account Registration: Navigate to the Correios website and initiate the registration process for a business account. This usually involves providing company details, CNPJ (Brazilian company registration number), and contact information. The exact path may vary, but generally starts from the 'Para Empresas' (For Businesses) section of the Correios homepage.
2. Contracting Services: Once your business account is active, you will need to contract specific Correios services that include API access. This often involves discussions with a Correios commercial representative to define your needs and establish a service agreement, which will include details about the WSPro API.
3. Obtaining Credentials: Upon successful contract finalization, Correios will provide you with the necessary API credentials. These typically include a usuário (username), senha (password), and potentially a código de serviço (service code) or número do contrato (contract number). These credentials are distinct from your website login and are essential for authenticating API requests. Keep these credentials secure, as they grant access to your contracted services and data.
4. Reviewing API Specifications: Before making any requests, thoroughly review the Correios WSPro API specifications, including WSDL files and method definitions, available on the official Correios developer portal. This documentation will detail the specific XML structures required for each API call.

It's important to understand that public tracking of individual packages via the Correios website or mobile app does not require these API credentials. The credentials discussed here are specifically for programmatic access to the WSPro service for integrated systems.

Your first request

After obtaining your Correios API credentials, the next step is to make your first authenticated request. Since WSPro is a SOAP-based service, you will typically use a SOAP client library in your chosen programming language. This example demonstrates a basic tracking request using a conceptual XML structure, which you would then send to the Correios WSPro endpoint.

Key Components of a WSPro Request

• Endpoint URL: The specific URL for the Correios WSPro service. This will be provided by Correios in their documentation, often with separate URLs for testing (homologation) and production environments.
• WSDL: The Web Services Description Language file, which describes the services offered, their operations, and message formats. Your SOAP client will use this to generate proxy classes or validate your requests.
• SOAP Envelope: The XML wrapper that contains your request payload. It includes standard SOAP headers and a body.
• Authentication: Your Correios usuário (username) and senha (password) will be included in the request, typically within the SOAP body or as part of a security header, depending on the specific method.

Example: Tracking a Package (Conceptual XML)

Let's assume you want to track a package using the buscaEventos (search events) operation. The exact XML structure will be defined in the Correios WSDL.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://service.ws.correios.com.br/">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:buscaEventos>
         <usuario>YOUR_USERNAME</usuario>
         <senha>YOUR_PASSWORD</senha>
         <tipo>L</tipo> <!-- L for all events, F for latest event -->
         <resultado>T</resultado> <!-- T for all results, U for unique -->
         <lingua>101</lingua> <!-- 101 for Portuguese -->
         <codigosObjeto>AA123456789BR</codigosObjeto> <!-- The tracking code -->
      </ser:buscaEventos>
   </soapenv:Body>
</soapenv:Envelope>

Sending the Request (Conceptual Steps)

1. Choose a SOAP Client Library: Select a library compatible with your programming language. Examples include zeep for Python, JAX-WS for Java, or gsoap for C++. These libraries handle the complexities of WSDL parsing and SOAP message construction.
2. Load the WSDL: Your client will need the URL to the Correios WSDL file to understand the available operations and expected message formats.
3. Create a Client Instance: Instantiate your SOAP client, pointing it to the Correios WSPro endpoint and WSDL.
4. Call the Operation: Invoke the desired operation (e.g., buscaEventos) through your client, passing the required parameters (username, password, tracking code, etc.) as defined by the WSDL. The client library will automatically construct the SOAP XML envelope.
5. Process the Response: The API will return an XML response, which your SOAP client library will parse into a structured object or data type, allowing you to extract tracking information.

For a deeper understanding of SOAP messaging and WSDL, refer to the W3C SOAP 1.2 specification or a general guide on Mozilla's SOAP explanation.

Common next steps

Once you have successfully made your first Correios API request and received a valid response, consider these common next steps to further integrate and optimize your usage:

1. Explore Additional WSPro Operations: The WSPro API offers more than just tracking. Investigate other available operations such as calculaPrazo (calculate delivery time), calculaPreco (calculate shipping price), and other services relevant to your business needs. Each operation will have its own specific WSDL definitions and required parameters.
2. Implement Error Handling: Develop robust error handling mechanisms for API responses. Correios WSPro will return specific error codes and messages in its XML responses for issues like invalid credentials, malformed requests, or service unavailability. Your application should gracefully manage these scenarios.
3. Secure Your Credentials: Ensure your API username and password are not hardcoded in your application. Use environment variables, secure configuration files, or a secrets management service to protect your credentials, especially in production environments.
4. Monitor API Usage: Implement logging and monitoring for your API calls. This helps in understanding usage patterns, identifying potential issues, and ensuring compliance with any Correios usage policies.
5. Optimize Performance: For high-volume applications, consider strategies to optimize API call performance, such as batching requests where supported, implementing caching for static data, and asynchronous processing.
6. Stay Updated with Documentation: Correios may update its API specifications or WSDL files. Regularly check the official Correios WSPro documentation for any changes that might affect your integration.
7. Consider Alternatives for Broader Logistics: While Correios is essential for Brazilian postal services, for global logistics or more modern API paradigms (like REST/JSON), you might explore integrating with platforms like Stripe Shipping API (for label generation with various carriers) or other global shipping providers such as FedEx or DHL, which often offer more standardized and developer-friendly interfaces.

Troubleshooting the first call

Encountering issues during your first API call is common, especially with SOAP-based services. Here are some troubleshooting steps:

• Verify Credentials: Double-check your usuário (username) and senha (password). Ensure they are the specific API credentials provided by Correios, not your general website login. Incorrect credentials are a frequent cause of authentication failures.
• Check Endpoint and WSDL URLs: Confirm that you are using the correct WSPro endpoint URL and WSDL file URL. There might be separate URLs for homologation (testing) and production environments. Using the wrong one can lead to connection errors or invalid responses.
• Validate XML Structure: Since WSPro is XML-based, even minor errors in the XML request structure can cause issues. Use an XML validator or your SOAP client's debugging features to ensure your request XML conforms to the WSDL schema. Pay close attention to namespaces and element casing.
• Review Correios Error Messages: Correios WSPro responses typically include detailed error messages and codes within the SOAP fault section of the XML. Parse these messages carefully to understand the root cause of the problem. Examples include 'Usuário ou senha inválidos' (Invalid username or password) or 'Objeto não encontrado' (Object not found).
• Network Connectivity: Ensure your server or development environment has outbound network access to the Correios WSPro endpoint. Firewall rules or proxy settings can sometimes block these connections.
• SSL/TLS Issues: Verify that your client library and environment correctly handle SSL/TLS certificates. Older environments or misconfigured clients can sometimes fail to establish secure connections.
• Language and Encoding: Ensure your requests and responses are using the correct character encoding, typically UTF-8, especially when dealing with Portuguese characters. The lingua parameter in tracking requests should be set appropriately (e.g., 101 for Portuguese).
• Consult Correios Documentation: Refer to the official Correios WSPro documentation for specific error codes and their meanings. The documentation, despite being in Portuguese, is the authoritative source for troubleshooting API-specific issues.
• Seek Community Support: While Correios doesn't have a large public developer community in English, searching for forums (often in Portuguese) or developer groups that discuss Brazilian e-commerce and logistics integrations might provide insights from others who have faced similar challenges.