preregister

PREREGISTER

This API offers services so that external clients and applications within Correos can perform the validation and preregister of package shipments. There are other resources to get data of one or more shipments from the code generated in the preregister, cancel a shipment or modify the erroneous data of your shipment.

Available operations are:

Shipments validation. As input, it has general information about the shipments, sender, recipient, packages, added values ​​and customs information. As output, the operation returns the errors of each of the shipments.

Shipments preregister. As input, it has general information about the shipments, sender, recipient, packages, added values ​​and customs information. If the input data is correct, it returns the codes of the preregistered shipments.

Get shipments data. Receives as input the preregistered codes. As output, the operation returns shipment general information, sender, recipient, added values and customs information.

Cancel shipment. Receives as input a preregistered code. As output, returns if the shipment has been canceled.

Modify shipment. As input it receives shipment data with modified data. As output, return if the shipment has been modified.

General Aspects of Correos APIs

Note: Any client capable of making HTTP requests would work.

API Access Request

From the Exchange itself, or the API access portal being used, there will be a Request Access option. If you don't see this option, it means that API doesn't accept access requests.

Before a client application is allowed to consume an API, access must be requested. Once access is requested, the request goes through an approval flow. Once this flow is completed and approved by the API owner, you will receive an email with access credentials (if defined).

Usage Levels

APIs can have different defined usage levels. When requesting access to an API, you will see indications of the usage level (SLA) that the API offers. Please note that some usage levels may have an associated cost.

To learn about the usage levels that apply to your API, you can review the API General Description.

Security Policies

There are several security policies that can be applied to the APIs. An API offered by Correos may have none, one, or several of these policies.

To learn about the security policies that apply to your API, you can review the API General Description.

No Security Policy

An API may have been defined to not require authorization (APIs for internal use or open use), so there is no need to include any additional aspects in the API calls.

curl "http://example.restapi.es/myResource"

Client ID Enforcement

Client ID application policy: The API expects headers with key/value pairs in its requests.

Before a client application is allowed to consume an API protected by this policy, API access must be requested. After there is an approved contract between the client application and the API, each request must include the client application credentials in accordance with the policy configuration.

The credentials will go as request headers as shown in the following example using curl:

curl "http://example.restapi.es/myResource" -H "client_id:1234" -H "client_secret:abcd"

Is it possible to check client_id and client_secret if I forgot or lost them?: From Exchange, or the API access portal being used, you can check My Applications and there you can find the access credentials.

JWT Validation

Security policy capable of validating both JWT tokens generated by ISAM and tokens generated by CorreosID (Correos security product). Link https://apioauthcid.correos.es/

All API calls must include the JWT (Json Web Token) token to use the API.

To make the call, you must include the Authorization header with the Bearer value followed by the token.

curl "http://example.restapi.es/myResource" -H "Authorization: Bearer {token}"

How to obtain the JWT token?: Obtaining the JWT token will be specific to the system that provides it (for example CorreosID) and should have provided documentation regarding making calls to its APIs to obtain a valid token. Please check with your Correos contact to obtain documentation related to CorreosID.

Introduction to REST API Usage

REST APIs use Uniform Resource Identifiers (URI) to address resources. Well-designed URIs would clearly communicate the API resource, such as:

http://example.restapi.es/france/paris/louvre/leonardo-da-vinci/mona-lisa

An incorrect URI design would give a much harder to understand resource like:

http://example.restapi.es/68dd0-a9d3-11e0-9f1c-0800200c9a66

URI Format

The generic URI syntax is defined as follows:

URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

• scheme: The scheme identifies the protocol for accessing resources (http, https)
• authority: It is the hierarchical element that identifies the naming authority, formed by the hostname and port.
• path: The path is the most specific part of the URI that indicates the path or location of the resource within the server. The path can include deep hierarchies and often reflects the organizational structure of resources.
• query: It is an optional component that is included after the path and has a non-hierarchical structure, and provides a string of information that the resource can use for some purpose, for example, to search for parameters or data to process. The query is usually a string of parameter-value pairs ("argument=value"). Arguments along with values are separated from each other with an ampersand ("&").
• fragment: The fragment is an optional component that allows identifying a part of the main resource, or the view of a representation of it. The beginning of this component is indicated with the pound character ("#").