Ir para o conteúdo

Próxima release.

Esta é a documentação da próxima release do Portal Único Siscomex. Ainda não se encontra disponível em produção, e podem haver diferenças entre esta documentação e a documentação da release atual. A documentação da release atual pode ser acessada em https://docs.portalunico.siscomex.gov.br/ .

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:

alt text

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:

Nome Descrição Tipo do dado Tipo do Parâmetro
Role-Type Perfil para o qual se deseja efetuar a autenticação. string, obrigatório para intervenientes privados header
System-Code Chave de acesso do sistema. string, obrigatório para intervenientes públicos usando certificado de equipamento header

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.

Nome Descrição e-CPF e-CNPJ
IMPEXP Declarante importador/exportador X
DEPOSIT Depositário X X
OPERPORT Operador Portuário X X
TRANSPORT Transportador X X
TRANSPEST PF – Representante de TETI X
AGECARGA Agente de Carga X
AGEREMESS Remessa Expressa/Correio X X
AJUDESPAC Ajudante de Despachante X
INSTFINANC Instituição Financeira X
CONTATOOEA Ponto de Contato OEA X
RESPLEGAL Responsável Legal OE X
HABILITAD Habilitador X
TERCEIROS Terceiros (Outros Intervenientes) X

Atributos do retorno:

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

Nome Descrição Tipo
Set-Token JSON Web Token (JWT) contendo as informações do usuário. Conforme o padrão JWT, esse token poderá ser decodificado (Base64) a fim de se extrair as informações do usuário para que as mesmas sejam utilizadas na aplicação cliente. O token é assinado digitalmente pelo servidor e verificado a cada requisição, garantindo a sua inviolabilidade. string
X-CSRF-Token Token de prevenção contra ataques CSRF (Cross-Site Request Forgery). Ao contrário do JWT, esse token é criptografado e pode ser decodificado apenas no servidor. O token possui um tempo de vida de 60 minutos. A cada nova requisição, para qualquer endpoint do Portal, o token é gerado novamente pelo servidor e devolvido no header do response com o tempo de expiração renovado. Dessa forma, a cada nova requisição, dentro do prazo de 60 minutos, utilize o token renovado que foi recebido na requisição anterior, sem precisar chamar novamente o endpoint de autenticação. string
X-CSRF-Expiration Data de expiração do X-CSRF-Token, em milisegundos. Após essa data, o token não será mais aceito no servidor. string

Erros da Autenticação:

Código Mensagem Observações
PUCX-ER0101 O cabeçalho 'Role-Type' não está na requisição
PUCX-ER0102 O cabeçalho 'Role-Type' é inválido. Verifique a tabela de domínio no manual de integração.
PLAT-ER2001 Não foi possível identificar um certificado digital válido. A autenticação SSL/TLS não foi efetuada com sucesso.
PLAT-ER2004 Não foi possível efetuar a consulta de representações do usuário. Instabilidade no Serviço Único (SUCE). Se possível aguarde alguns instantes e repita a operação. Se o problema persistir entre em contato com o administrador do sistema.
PLAT-ER2002 Ocorreu um erro na autenticação do usuário. Entre em contato com o administrador do sistema. Mensagem de retorno: Mensagem de erro retornada pelo Serviço Único (SUCE). Em caso de dúvida, entre em contato com o administrador do sistema.
PLAT-ER8001 Não foi possível identificar um certificado digital de equipamento válido.
PLAT-ER8002 O certificado digital não está habilitado no Portal Único do Comércio Exterior.
PLAT-ER8003 A chave de acesso enviada não é válida.
PLAT-ER8004 A integração está desaabilitada temporariamente.

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"
}
Nome Descrição Tipo
message Mensagem de erro string
code Código que identifica o erro string
tag Tag do registro de log (para ser informado na abertura de chamado à central de suporte) string
status Código do status HTTP. Mesmo código retornado no HTTP Status Code da resposta. string

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

Nome Descrição Tipo Local
Authorization JSON Web Token (JWT) contendo as informações do usuário. Este token deve ser preenchido com o conteúdo do header Set-Token, retornado no response da chamada ao serviço de autenticação. string header
X-CSRF-Token Token de prevenção contra ataques CSRF (Cross-Site Request Forgery). Este token deve ser preenchido com o conteúdo do header X-CSRF-Token, retornado no response da chamada ao serviço de autenticação. string header

Status Codes

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

Código Descrição
200 Operação realizada com sucesso
201 Recurso criado com sucesso
204 Operação realizada com sucesso. Nenhum conteúdo retornado
400 Requisição mal formatada
400 XML não atende as especificações definidas no XSD (requisições com envio de arquivo XML)
401 Usuário não autenticado ou autenticação inválida
403 Usuário não tem permissão de acesso ao recurso
404 Recurso não encontrado
422 Erro(s) de validação da camada de negócio
500 Erro interno no servidor
503 Serviço indisponível