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: