Skip to content

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 tag to reference them).

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:

alt text

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