Introduction
Welcome to the API of the Portal Único Siscomex (PUCOMEX). On this page, technical information is consolidated on the new integration between PUCOMEX and the private companies' systems and several public agencies involved in Foreign Trade.
At PUCOMEX, all services follow the same access protocol, based on the SSL/TLS standard and on the use of digital certificate. The Portal’s API was developed based on the REST architecture. XML and JSON formats will be used, being some services available in XML format exclusively, with their structure specified in XSD (XML Schema Definition) syntax. These schemas will be made available to facilitate the validation and the construction of the customers consuming services. In addition, our entire API will use the UTF-8 format.
We point out that the system was recently implemented for private companies to prepare the necessary adaptations in their systems, and occasional instabilities may occur. In case of doubts for further information, please, fill in the webform Comex Responde (field "General Subject" option "Support systems and tools" and field "Specific Topic" option "Portal Único Siscomex").
For IT-related problems, please, contact the Serpro Customer Service Center (in "Service" field, please choose the option "PORTAL ÚNICO SISCOMEX - PUCOMEX").
We hope that PUCOMEX improves the business processes of companies and public agencies, increasing competitiveness, increasing the quality, of the service to society, and decreasing the incidental costs involved.
Note: Please consider that some services marked with the text: "Functionality not yet available in Test and Production environments" are still under construction. As soon as they are available in a test and production environment, the interested parties will be informed and the texts will be excluded from the functionalities.
Access URLs
Below are the API’s base URLs per environment (we will use the
Test Environment:
- Private actors: https://val.portalunico.siscomex.gov.br
- Public actors: https://val.anuentes.portalunico.siscomex.gov.br
Production Environment:
- Private actors: https://portalunico.siscomex.gov.br
- Public actors: https://anuentes.portalunico.siscomex.gov.br
Authentication
The security of the portal is based on the SSL/TLS standard, and the use of digital certificates is mandatory. When activating the authentication service, it will be necessary to perform the SSL handshake process between the client application and the portal, presenting a valid digital certificate recognized by SERPRO. After the certificate is validated, the portal will consult the authorization base in order to identify the user profile who owns the digital certificate. The service supports A1 and A3 certificates based on the ICP-Brasil (Brazilian Root Certification Authority) standard.
The current development platforms already implement the SSL/TLS Handshake workflow. In general, you only need to configure some environment variables and the API will take care of executing the protocol. In summary, the process happens as follows:
1. The client initiates the request for connection to the service;
1. The service returns your signed certificate to be verified by the client;
2. The client checks the chain of certification authorities chains in the certificate and compares it with the available certificate chains in the local TrustStore. The certificate chains can be found in the link "Baixar Cadeia" (Download Certificate Chain), in the following location: https://ccd.serpro.gov.br/serproacf “Cadeia de Certificados emitida em 21/11/2011 com Algoritmos SHA2.” (Certificate chain issued with SHA2 Algorithms).
3. The client sends its certificate encapsulated in a Keystore to be recognized by the server;
4. The server validates the client's certificate;
5. The handshake process is finished and the client can make the service request.
Activation flow of the authentication service:
Endpoint (digital certificate for natural or legal entity):
POST https://<url>/portal/api/autenticar
Endpoint (server digital certificate) available only to public actors:
POST https://<url>/portal/api/autenticar/sistema
Attributes:
| Name | Description | Data Type | Parameter Type |
|---|---|---|---|
| Role-Type | Profile for which you want to authenticate. | string, mandatory for private actors | header |
| System-Code | System access key. | string, mandatory for public actors that use equipment certificate | header |
List of available profiles (private actors):
| Name | Description |
|---|---|
| IMPEXP | Importer/Exporter |
| DEPOSIT | Depositary |
| OPERPORT | Port Operator |
| TRANSPORT | Carrier |
| AGEREMESS | Courier/ Postal |
| AJUDESPAC | Custom Broker Assistant |
| HABILITAD | Company Register Role |
Return Attributes:
The following attributes will be returned in response header:
| Name | Description | Type |
|---|---|---|
| Set-Token | JSON Web Token (JWT) containing user information. According to the JWT standard, this token can be decoded (Base64) in order to extract user information so that it can be used in the client application. The token is digitally signed by the server and verified at each request, ensuring its inviolability. | string |
| X-CSRF-Token | CSRF (Cross-Site Request Forgery) attack prevention token. Unlike JWT, this token is encrypted and can only be decrypted on the server. The token has a lifetime of 60 minutes. With each new request, for any Portal endpoint, the token is generated again by the server and returned in the response header with the renewed expiration time. Likewise, for each new request, within the 60-minute period, use the renewed token that was received in the previous request, without having to call the authentication endpoint again. | string |
| X-CSRF-Expiration | Expiration date of the X-CSRF-Token, in milliseconds. After that date, the token will no longer be accepted on the server. | string |
Authentication Errors:
| Code | Message | Comments |
|---|---|---|
| PUCX-ER0101 | The 'Role-Type' header is not on the request. | |
| PUCX-ER0102 | The ‘Role-Type’ header is invalid. Check the domain table in the integration manual. | |
| PLAT-ER2001 | It was not possible to identify a valid digital certificate. | The SSL/TLS authentication was not successful. |
| PLAT-ER2004 | It was not possible to perform the user representations query. | Instability on the Serviço Único (SUCE). If possible, wait a few moments and repeat the operation. If the problem persists, contact your system administrator. |
| PLAT-ER2002 | There was an error in user authentication. Contact your system administrator. Return message: |
Error message returned by the Serviço Único (SUCE). If in doubt, contact your system administrator. |
| PLAT-ER8001 | It was not possible to identify a valid server digital certificate. | |
| PLAT-ER8002 | The digital certificate is not enabled on the Portal Único do Comércio Exterior. | |
| PLAT-ER8003 | The access key sent is not valid. | |
| PLAT-ER8004 | Integration is disabled temporarily. |
Response attributes when the result is 4xx or 5xx:
Example of the error response structure in JSON format
{
"message":"O cabeçalho 'Role-Type' não está na requisição.",
"code":"PUCX-ER0101",
"tag":"[081454RXF]",
"status":422,
"severity":"ERROR"
}
| Code | Message | Comments |
|---|---|---|
| message | Error message | string |
| code | Code that identifies the error | string |
| tag | Tag of the log record (to be informed when opening a case to the support center) | string |
| status | HTTP status code. Same code returned on the response of the HTTP Status Code. | string |
Required attributes in all requests after authentication:
| Nome | Descrição | Tipo | Local |
|---|---|---|---|
| Authorization | JSON Web Token (JWT) containing user information. This token is retrieved in the Set-Token parameter in the authentication response | string | header |
| X-CSRF-Token | CSRF (Cross-Site Request Forgery) attacks prevention token. This token is retrieved from the X-CSRF-Token parameter in the authentication response | string | header |
Status Codes
The Portal API will always return an HTTP status code to indicate the success or failure of a request.
| Code | Description |
|---|---|
| 200 | Request has succeeded |
| 201 | Created |
| 204 | No content |
| 400 | Malformed request |
| 401 | Request requires authentication |
| 403 | Request not authorized |
| 404 | Resource not found |
| 422 | Business error |
| 500 | Internal server error |
| 503 | Service unavailable |