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] (#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:

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

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: