Ir para o conteúdo

Introdução

Bem-vindo à API do Portal Único Siscomex (PUCOMEX). Consolidamos nessa página as informações técnicas da nova forma de integração entre o PUCOMEX e os sistemas próprios das empresas privadas e os diversos órgãos públicos intervenientes de Comércio Exterior.

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: https://val.portalunico.siscomex.gov.br
  • Intervenientes públicos: https://val.anuentes.portalunico.siscomex.gov.br

Ambiente de Produção:

  • Intervenientes privados: https://portalunico.siscomex.gov.br
  • Intervenientes públicos: https://anuentes.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. As cadeias de certificados podem ser encontradas no link “Baixar Cadeia”, no seguinte local: [https://ccd.serpro.gov.br/serproacf] (https://ccd.serpro.gov.br/serproacf) Cadeia de Certificados emitida em 21/11/2011 com Algoritmos SHA2.

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 disponíveis (intervenientes privados):

Nome Descrição
IMPEXP Declarante importador/exportador
DEPOSIT Depositário
OPERPORT Operador Portuário
TRANSPORT Transportador
AGEREMESS Remessa Expressa/Correio
AJUDESPAC Ajudante de Despachante
HABILITAD Habilitador

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 é recuperado no parâmetro Set-Token no response da autenticação string header
X-CSRF-Token Token de prevenção contra ataques CSRF (Cross-Site Request Forgery). Este token é recuperado no parâmetro X-CSRF-Token no response da 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