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] (#autenticacao).

Como pré-requisito, os sistemas que irão receber as notificações devem aceitar requisições via HTTPS na porta 443/tcp. Devem ser liberadas as faixas de endereço IPv4 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) e 200.198.192.0/18 (200.198.192.1 a 200.198.255.254).

Documentação adicional:

Apresentação do Webhooks: Proposta de Comunicação do PUCOMEX com Intervenientes Públicos do Comércio Exterior.

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:

Não há parâmetros de entrada.

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)

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.

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

Eventos disponíveis

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