Ir para o conteúdo

Notificação de eventos push

O Portal Único de Comércio Exterior fornece um serviço de envio de notificações para eventos relacionados a mudanças de status das operações em andamento. Os interessados em receber as notificações devem utilizar a API de subscrição descrita a seguir, que é baseada no conceito de webhook – uma estratégia de integração em que a parte interessada é notificada a partir de um endpoint previamente cadastrado.

As seções abaixo definem os serviços da API de notificação, que devem ser acessados depois de realizada a autenticação no Portal.

Pré-requisitos de infraestrutura

Os sistemas que irão receber as notificações devem aceitar requisições via HTTPS na porta 443/tcp. As requisições irão chegar a partir de endereços IPv4 de origem dentro das faixas:

  • 161.148.0.0/16 (161.148.0.1 a 161.148.255.254)
  • 189.9.0.0/16 (189.9.0.1 a 189.9.255.254)
  • 200.198.192.0/18 (200.198.192.1 a 200.198.255.254).

O protocolo de Transport Layer Security deve ter versão mínima como TLSv1.2.

O tempo máximo de processamento de uma requisição é de 3500 milisegundos , e em tempo superior a isso consideramos erro no envio da requisição por timeout . Para aplicações com tempo maior de processamento das notificações, recomenda-se uma implementação assíncrona que permita que o recebimento de eventos do Portal Único Siscomex seja primeiro armazenado, e posteriormente processado.

Exclusão automática de assinaturas

A exclusão automática das assinaturas se dará quando, em um período de 30 dias, houver apenas ocorrências de erro na entrega. As assinaturas canceladas automaticamente poderão ser consultadas enviando o parâmetro exibirInativos=true, onde poderá ser verificado também o motivo da exclusão.


Documentação adicional:

Subscrever evento

Exemplo de envio de dados para subscrição de evento:

{
  "evento": "id_evento",
  "endpoint": "https://endpoint_a_ser_notificado",
  "chaveSecreta": "0484a6e22cf66a2d3da8953789f8c6b3"
}

Endpoint:

POST https://<url>/portal/api/ext/webhook

Content-Type:

application/json

Parâmetros de Entrada:

Nome Descrição Tipo Local Detalhes
evento Identificador do evento (consultar na seção ‘Relação de eventos para subscrição’) Texto(40), obrigatório JSON
endpoint Endpoint a ser notificado na ocorrência do evento Texto(500), obrigatório JSON Deve ser uma URL segura (https://), na porta 443.
chaveSecreta Chave secreta que poderá ser usada para verificação na recepção da notificação Texto(100), opcional JSON Essa chave, com até 100 caracteres, será enviada no cabeçalho 'Secret' da requisição POST de notificação.

Resposta:

Nome Descrição Tipo
id Identificador da subscrição Número(10)
evento Identificador do evento (consultar na seção ‘Relação de eventos para subscrição’) Texto(40)
endpoint Endpoint a ser notificado na ocorrência do evento Texto(500)
chaveSecreta Chave secreta enviada na notificação Texto(100)

Listar subscrições

Lista as subscrições ativas para o usuário.

Endpoint:

GET https://<url>/portal/api/ext/webhook

Content-Type:

application/json

Parâmetros de Entrada:

Nome Descrição Tipo Local Detalhes
exibirInativos Flag (true/false) sinalizando se as assinaturas excluídas devem ser retornadas Boolean(true/false Query

Resposta:

Nome Descrição Tipo
id Identificador da subscrição Número(10)
evento Identificador do evento Texto(40)
endpoint Endpoint notificado na ocorrência do evento Texto(500)
chaveSecreta Chave secreta enviada na notificação Texto(100)
dataRegistro Data de registro da assinatura Data(dd-MM-yyyy HH:mm:ss)
dataExclusao Data de exclusão da assinatura Data(dd-MM-yyyy HH:mm:ss)
motivoExclusao Motivo da exclusão Texto(200)
dataUltimoSucesso Data da última notificação com retorno de sucesso Data(dd-MM-yyyy HH:mm:ss)

Alterar subscrição

Exemplo de envio de dados para alteração de uma subscrição ativa:

{
  "id": 8, 
  "evento": "id_evento",
  "endpoint": "https://endpoint_a_ser_notificado",
  "chaveSecreta": "0484a6e22cf66a2d3da8953789f8c6b3"
}

Endpoint:

PUT https://<url>/portal/api/ext/webhook/{id}

Content-Type:

application/json

Parâmetros de Entrada:

Nome Descrição Tipo Local Detalhes
id Identificador da subscrição Número(10), obrigatório JSON
evento Identificador do evento Texto(40), obrigatório JSON
endpoint Endpoint a ser notificado na ocorrência do evento Texto(500), obrigatório JSON Deve ser uma URL segura (HTTPS).
chaveSecreta Chave secreta que poderá ser usada para verificação na recepção da notificação Texto(100), opcional JSON Essa chave, com até 100 caracteres, será enviada no cabeçalho 'Secret' da requisição POST de notificação.

Resposta:

Nome Descrição Tipo
id Identificador da subscrição Número(10)
evento Identificador do evento (consultar na seção ‘Relação de eventos para subscrição’) Texto(40)
endpoint Endpoint a ser notificado na ocorrência do evento Texto(500)

Excluir subscrição

Exemplo de envio de dados para exclusão de uma subscrição ativa:

{
  "id": 8
}

Endpoint:

DELETE https://<url>/portal/api/ext/webhook/{id}

Content-Type:

application/json

Parâmetros de Entrada:

Nome Descrição Tipo Local Detalhes
id Identificador da subscrição Número(10), obrigatório JSON

Resposta:

Não há parâmetros na resposta.

Consultar falhas

Permite consultar falhas no envio de eventos subscritos pelo usuário. Os registros de falhas estarão disponíveis para consulta por um período de 30 dias.

Exemplo de envio de dados para consultar falhas de envio:

{
  "data": 17092018
}

Endpoint:

GET https://<url>/portal/api/ext/webhook/falhas

Content-Type:

application/json

Parâmetros de Entrada:

Nome Descrição Tipo Local Detalhes
data Data do registro no formato ddMMyyyy Texto(8), opcional JSON Quando não informada, será considerada a data corrente.

Resposta:

Nome Descrição Tipo
id Identificador do registro Número(10)
data Data/hora do registro no formato dd-MM-yyyy HH24:mm:ss no fuso horário de Brasília Texto(19)
descricao Descrição do erro Texto
evento Identificador do evento relacionado Texto(40)
conteudo Conteudo enviado ao endpoint Texto

Evento de notificação

Na ocorrência de um evento que gera notificação, os interessados recebem uma requisição POST no endpoint cadastrado na subscrição desse evento. Os seguintes cabeçalhos (headers) são enviados na requisição, além dos cabeçalhos próprios do HTTP:

Cabeçalho Descrição Tipo
destinatario-tipo Indica o tipo de destinário da notificação - CPF (quando a notificação é endereçada a uma pessoa física), CNPJ (quando a notificação é enviada para os representantes de uma pessoa jurídica) ou ORGAO (quando a notificação é envida para um órgão da administração pública) Texto
destinatario-id Identificador do destinatário da mensagem, de acordo com o formato indicado no cabeçalho anterior Texto
secret Chave secreta informada no momento da subscrição do evento Texto(100)
event-type Identificador do evento Texto(40)

O conteúdo do corpo (body) da requisição é definido na especificação de cada evento, na seção Eventos disponíveis.

Eventos disponíveis

Os eventos disponíveis para subscrição estão documentados nas páginas a seguir: