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. Esses envios podem ser feitos individualmente, com um CPF como destinatário, ou podem ser feitos em lote, com um arquivo de entrada onde cada linha corresponde a um envio de 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'