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 |
Eventos disponíveis
Os eventos disponíveis para subscrição estão documentados nas páginas a seguir: