Ir para o conteúdo

Integrando com o Notifica BR

A integração de um sistema do cliente com o Notifica BR é feita através do consumo de serviços REST (Representational State Transfer - Transferência de Estado Representacional) disponibilizados através de API (Application Programming Interface - Interface de Programação de Aplicação).

Utilização de TLS 1.2 ou 1.3

Apenas conexões utilizando os protocolos de segurança TLS (Transport Layer Security) 1.2 ou 1.3 serão aceitas nas chamadas à API do Notifica BR.

Sobre os dados utilizados nos exemplos

Os dados utilizados nos exemplos são meramente ilustrativos. É preciso substituir os parâmetros das chamadas com as informações da aplicação do cliente que deseja realizar a integração.

Recuperando o token de acesso

Token de acesso é o artefato (chave) que permite que a aplicação cliente acesse os recursos do Notifica. Para obtê-lo, é preciso ter em mãos as credenciais do órgão. Essas credenciais, no formato Basic, são passadas no cabeçalho de autorização da requisição para o token, conforme exemplo a seguir.

💻 Exemplo de chamada ao serviço de token

curl --request GET \
  --url https://notifica.serpro.gov.br/notificabr/v1/token \
  --header 'Authorization: Basic 
  ZTMxZGMzMDMtZjBiOC00ODNkLWJhYjctNmNiZjkzNDQ1ZTkzOjM4OTI5NGVhLWUzZDQtNDNjZS1hY2VmLWJhMzk4NDNiYzlmOA=='

Esse serviço retorna o token de acesso JWT que servirá como autorização para os próximos passos.

Enviando mensagens

De posse do token de acesso, é possível utilizar a API do sistema para enviar mensagens de duas formas:

  • Envio Individual: Para um único destinatário, identificado por CPF ou CNPJ. A obrigatoriedade do CPF depende da configuração do órgão, enquanto o CNPJ é sempre opcional.
  • Envio em Lote: Para múltiplos destinatários, utilizando um arquivo de entrada onde cada linha corresponde a uma mensagem.

Envio de mensagem individual

Para acionar esse serviço, é preciso ter um código de template que foi previamente cadastrado na interface administrativa do Notifica BR.

No exemplo abaixo, foi usado um template que possui os parâmetros de personalização nome e banco.

Canal de envio

A definição do canal de envio a ser utilizado está no cadastro do template. O Notifica se encarrega de enviar a mensagem pelo canal para o qual o template foi cadastrado.

💻 Exemplo de chamada ao serviço de envio de mensagem

curl --request POST \
  --url https://notifica.serpro.gov.br/notificabr/v1/mensagens \
  --header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJpc3MiOiJOb3RpZmljYSBCUiAtIEhvbW9sb2dhw6fDo28iLCJhdWQiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJleHAiOjE2NjU2OTg1NjksImp0aSI6IlJZOVBoYkFxR0NMd3JKbm1Hb0tialEiLCJpYXQiOjE2NjU2OTEzNjksIm5iZiI6MTY2NTY5MTI0OX0.ApsFi0P_s4TULGIoYJpsZRvHEoodaOkIehFYBdGAIchr8FTV5Smak4NENTarEroebPIEJ6M99Gprhk1zFu5C7a6AIo2YDAZPEsU06s2fMBxIc0auG9qN75MvkTdawsLogv4K4AwxYLc2nsq-dL5t1KZAVCVaVPs99g-JCaPXBmT1Y0U16MW3iDOjHusnRYjFNxEp_sEQAjzktb4R3NZZ69qVay7ima0X8RA2cA9E8m-IcvcnSpzk87t5k1CFdYYTQ5l--tBqsQLBQiHGvw01R4oW2g3859G63Gkld101WyR7UJOcDVPZdyjaORRRSZVhA-Nde7H1P7P9FeMGODa2-w' \
  --header 'Content-Type: multipart/form-data' \
  --form cpf=32772813029 \
  --form codigoTemplate=8fcda77a-6f09-4c2c-841a-901342631699 \
  --form 'parametrosTemplate={"nome": "José", "banco": "Caixa"}'

Envio de um lote de mensagens por arquivo

Para acionar esse serviço, é preciso ter um código de template que foi previamente cadastrado na interface administrativa do Notifica BR.

O arquivo de entrada é em formato CSV, conforme especificação. No exemplo, foi usado um arquivo localizado no caminho /home/usuario/arquivos_envio/envio_matriculas_2022.csv de uma máquina com sistema operacional Linux. Também foi utilizado um identificador de lote Envio Matriculas 2022, gerado pela aplicação cliente.

💻 Exemplo de chamada ao serviço de postagem de lote

curl --request POST \
  --url https://notifica.serpro.gov.br/notificabr/v1/lotes \
  --header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJpc3MiOiJOb3RpZmljYSBCUiAtIEhvbW9sb2dhw6fDo28iLCJhdWQiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJleHAiOjE2NjU2OTg1NjksImp0aSI6IlJZOVBoYkFxR0NMd3JKbm1Hb0tialEiLCJpYXQiOjE2NjU2OTEzNjksIm5iZiI6MTY2NTY5MTI0OX0.ApsFi0P_s4TULGIoYJpsZRvHEoodaOkIehFYBdGAIchr8FTV5Smak4NENTarEroebPIEJ6M99Gprhk1zFu5C7a6AIo2YDAZPEsU06s2fMBxIc0auG9qN75MvkTdawsLogv4K4AwxYLc2nsq-dL5t1KZAVCVaVPs99g-JCaPXBmT1Y0U16MW3iDOjHusnRYjFNxEp_sEQAjzktb4R3NZZ69qVay7ima0X8RA2cA9E8m-IcvcnSpzk87t5k1CFdYYTQ5l--tBqsQLBQiHGvw01R4oW2g3859G63Gkld101WyR7UJOcDVPZdyjaORRRSZVhA-Nde7H1P7P9FeMGODa2-w' \
  --header 'Content-Type: multipart/form-data' \
  --form arquivo=@/home/usuario/arquivos_envio/envio_matriculas_2022.csv \
  --form codigoTemplate=8fcda77a-6f09-4c2c-841a-901342631699 \
  --form 'idLoteAplicacaoCliente=Envio Matriculas 2022'

Verificando status de mensagem

De posse do token de acesso e do identificador retornado pelo serviços de envio, é possível consultar o status de envio da mensagem individual ou do lote de mensagens.

Verificação de status de mensagem individual

Com o código identificador da mensagem, o serviço de status pode ser acionado.

No exemplo abaixo, o identificador da mensagem utilizado é f6b20a75-fba4-4f23-8b8f-26675146362e.

💻 Exemplo de chamada ao serviço de status de mensagem

curl --request GET \
  --url https://notifica.serpro.gov.br/notificabr/v1/mensagens/f6b20a75-fba4-4f23-8b8f-26675146362e \
  --header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJpc3MiOiJOb3RpZmljYSBCUiAtIEhvbW9sb2dhw6fDo28iLCJhdWQiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJleHAiOjE2NjU2OTg1NjksImp0aSI6IlJZOVBoYkFxR0NMd3JKbm1Hb0tialEiLCJpYXQiOjE2NjU2OTEzNjksIm5iZiI6MTY2NTY5MTI0OX0.ApsFi0P_s4TULGIoYJpsZRvHEoodaOkIehFYBdGAIchr8FTV5Smak4NENTarEroebPIEJ6M99Gprhk1zFu5C7a6AIo2YDAZPEsU06s2fMBxIc0auG9qN75MvkTdawsLogv4K4AwxYLc2nsq-dL5t1KZAVCVaVPs99g-JCaPXBmT1Y0U16MW3iDOjHusnRYjFNxEp_sEQAjzktb4R3NZZ69qVay7ima0X8RA2cA9E8m-IcvcnSpzk87t5k1CFdYYTQ5l--tBqsQLBQiHGvw01R4oW2g3859G63Gkld101WyR7UJOcDVPZdyjaORRRSZVhA-Nde7H1P7P9FeMGODa2-w'

Verificação de status de um lote

Com o código identificador da mensagem, o serviço de status pode ser acionado.

No exemplo abaixo, o identificador da mensagem utilizado é 42ea0e68-140b-47af-95b9-69fe82f024de.

💻 Exemplo de chamada ao serviço de status de lote

curl --request GET \
  --url https://notifica.serpro.gov.br/notificabr/v1/lotes/42ea0e68-140b-47af-95b9-69fe82f024de \
  --header 'Authorization: Bearer eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJpc3MiOiJOb3RpZmljYSBCUiAtIEhvbW9sb2dhw6fDo28iLCJhdWQiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJleHAiOjE2NjU2OTg1NjksImp0aSI6IlJZOVBoYkFxR0NMd3JKbm1Hb0tialEiLCJpYXQiOjE2NjU2OTEzNjksIm5iZiI6MTY2NTY5MTI0OX0.ApsFi0P_s4TULGIoYJpsZRvHEoodaOkIehFYBdGAIchr8FTV5Smak4NENTarEroebPIEJ6M99Gprhk1zFu5C7a6AIo2YDAZPEsU06s2fMBxIc0auG9qN75MvkTdawsLogv4K4AwxYLc2nsq-dL5t1KZAVCVaVPs99g-JCaPXBmT1Y0U16MW3iDOjHusnRYjFNxEp_sEQAjzktb4R3NZZ69qVay7ima0X8RA2cA9E8m-IcvcnSpzk87t5k1CFdYYTQ5l--tBqsQLBQiHGvw01R4oW2g3859G63Gkld101WyR7UJOcDVPZdyjaORRRSZVhA-Nde7H1P7P9FeMGODa2-w'