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:
| 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 |