Introdução

No PUCOMEX, todos os serviços seguem o mesmo protocolo de acesso, baseado no padrão SSL/TLS e no uso de certificado digital. A API do Portal foi desenvolvida baseada na arquitetura REST. Serão utilizados os formatos XML e JSON, sendo que alguns serviços serão disponibilizados exclusivamente no formato XML, tendo sua estrutura especificada na sintaxe XSD (XML Schema Definition). Estes schemas serão disponibilizados para facilitar a validação e construção dos clientes consumidores dos serviços. Além disso, toda a nossa API usará o formato UTF-8.

Destacamos que o sistema foi implementado recentemente para as empresas privadas prepararem as adaptações necessárias em seus sistemas, podendo ainda ocorrer instabilidades pontuais. Caso haja dúvidas relacionadas ao Novo Processo de Exportações, envie-as ao Comex Responde (campo "Assunto Geral" opção "Sistemas e ferramentas de apoio" e campo "Assunto Específico" opção "Portal Único Siscomex").

Para problemas relacionados à TI entre em contato com a Central Serpro de Atendimento (no campo de "Serviço" escolher a opção "PORTAL ÚNICO SISCOMEX - PUCOMEX").

Esperamos que o PUCOMEX melhore os processos de negócios das empresas e dos intervenientes públicos, aumentando a competitividade, aumentando a qualidade e tempo de atendimento a sociedade e diminuindo os custos acessórios envolvidos.

Observação: Favor atentar que alguns serviços marcados com o texto: "Funcionalidade ainda não disponível nos ambientes de Validação das Empresas e Produção" ainda estão em processo de construção. Assim que os mesmos estiverem disponíveis em ambiente de validação e produção, os interessados serão informados e os textos excluídos das funcionalidades.

URLs de acesso

Abaixo estão descritas as URLs base da API por ambiente (usaremos a tag <url> para referenciá-las).

Ambiente de Validação das Empresas:

• Intervenientes privados e públicos: https://val.portalunico.siscomex.gov.br

Ambiente de Produção:

• Intervenientes privados e públicos: https://portalunico.siscomex.gov.br

Autenticação

A segurança do portal é baseada em SSL/TLS, sendo obrigatória a utilização de certificados digitais. Ao acionar o serviço de autenticação, será preciso realizar o processo de handshake SSL entre a aplicação cliente e o portal, apresentando um certificado digital válido e reconhecido pelo SERPRO. Após a validação do certificado, o portal consultará a base autorizativa a fim de identificar o perfil do usuário proprietário do certificado digital. O serviço suporta certificados A1 e A3, do padrão ICP-Brasil.

As plataformas de desenvolvimento atuais já implementam o fluxo de Handshake SSL/TLS. Em geral, basta configurar algumas variáveis de ambiente e a API se encarrega de executar o protocolo. Em resumo, o processo acontece da seguinte forma:

1. O cliente inicia o pedido de conexão com o serviço;

2. O serviço retorna o seu certificado assinado para que seja verificado pelo cliente;

3. O cliente verifica a sequência de cadeias de autoridades certificadoras presentes no certificado e compara com as cadeias presentes na TrustStore local;

4. O cliente envia o seu certificado encapsulado em uma Keystore para que seja reconhecido pelo servidor;

5. O servidor valida o certificado do cliente;

6. O processo de handshake é finalizado e o cliente pode realizar a requisição ao serviço.

Fluxo de acionamento do serviço de autenticação:

Endpoint (certificado digital de pessoa física ou jurídica):

POST https://<url>/portal/api/autenticar

Endpoint (certificado digital de equipamento) disponível apenas para intervenientes públicos :

POST https://<url>/portal/api/autenticar/sistema

Atributos:

Lista de perfis :

Na seguinte tabela estão listados os valores possíveis para o cabeçalho "Role-Type" indicando o perfil de atuação do usuário. Para cada perfil, a tabela também informa se a autenticação admite certificado digital de pessoa física (e-CPF), de pessoa jurídia (e-CNPJ) ou ambos.

Atributos do retorno:

Os seguintes atributos serão retornados no cabeçalho da resposta:

Erros da Autenticação:

Atributos da resposta quando o resultado for 4xx ou 5xx:

Exemplo da estrutura de resposta de erro no formato JSON

{
   "message":"O cabeçalho 'Role-Type' não está na requisição.",
   "code":"PUCX-ER0101",
   "tag":"[081454RXF]",
   "status":422,
   "severity":"ERROR"
}

Atributos obrigatórios em todas as requisições após autenticação:

Status Codes

A API do Portal retornará sempre um HTTP status code para indicar sucesso ou falha de uma requisição.