Integrando com o Avisa BR¶

A integração de um sistema do cliente com o Avisa 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

Somente acessos às APIs via gateway.apiserpro.serpro.gov.br com Protocolos de Segurança TLS 1.2 e 1.3 serão aceitos (exceto para produtos INFOCONV ou ConectaGov). Protocolos de Segurança TLS 1.0 ou 1.1 não obterão integração com o serviço. Mais informações: Desligamento protocolos TLS 1.0 e 1.1 - Central de Ajuda.

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 Avisa. Para obtê-lo, é preciso ter em mãos as credenciais do cliente, conforme passo a passo a seguir.

Como autenticar¶

As APIs disponibilizadas pela plataforma API SERPRO utilizam o protocolo OAuth2 para
realizar a autenticação e autorização de acesso das APIs contratadas.
Siga os passos abaixo para se autenticar e consumir a api do Avisa.

1. Primeiro passo - Obtenha Consumer Key e Consumer Secret¶

Para consumir as APIs, você deverá utilizar os dois códigos (Consumer Key e Consumer Secret) disponibilizados na Área do Cliente.
Esses códigos servem para identificar o contrato.
As credenciais de acesso devem ser obtidas a partir da área do cliente Serpro.

Exemplos de códigos:

Consumer Key: dt0R21PGoYp1iyK2n2ACOH9REdUb   
Consumer Secret: ObRsAJWOL4fv2Tp27D1vd8fB3aje

Aviso importante

O Consumer Key e Consumer Secret identificam seu usuário e seu contrato com o SERPRO. Mantenha essas informações protegidas.

2. Segundo passo - Solicite o Bearer Token¶

Para consultar as APIs, é necessário obter um token de acesso temporário (Bearer).
Esse token possui um tempo de validade e sempre que expirado, este passo de requisição de um novo token de acesso deve ser repetido.

Como solicitar o Token de Acesso (Bearer)¶

Para solicitar o token temporário é necessário realizar uma requisição HTTP POST para o endpoint
Token https://gateway.apiserpro.serpro.gov.br/token, informando as credenciais de acesso (consumerKey:consumerSecret)
no HTTP Header Authorization, no formato base64, conforme exemplo abaixo.

[HEAD] Authorization: Basic base64(Consumer Key:Consumer Secret) 
[HEAD] Content-Type: application/x-www-form-urlencoded 
[POST] grant_type=client_credentials

Para utilização no parâmetro Authorization, é necessário concatenar os códigos Consumer Key e Consumer Secret,
eparados pelo caracter ":", e converter o resultado em BASE64.
No exemplo a seguir, é retornada a string ZGphUjIx[...]IzT3RlCg:

echo -n "djaR21PGoYp1iyK2n2ACOH9REdUb:ObRsAJWOL4fv2Tp27D1vd8fB3Ote" | base64

Resultado:

ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg

Abaixo segue um exemplo de chamada via cUrl:

curl -k -d "grant_type=client_credentials" \
-H "Authorization: Basic ZGphUjIxUEdvWXAxaXlLMm4yQUNPSDlSRWRVYjpPYlJzQUpXT0w0ZnYyVHAyN0QxdmQ4ZkIzT3RlCg" \
https://gateway.apiserpro.serpro.gov.br/token

Content-type

Caso experiencie erros de "415 Unsupported Media Type" na chamada de solicitação do Token, utilize o campo do Header "Content-Type" com o valor "application/x-www-form-urlencoded"

[HEAD] Content-type: "application/x-www-form-urlencoded"

3. Terceiro passo - Receba o Token¶

Como resultado do passo anterior, o endpoint informará o token de acesso a API, no campo access_token da mensagem json de retorno.
Este token deve ser informado nos próximos passos.

Receba o Token¶

Como resultado, o endpoint informará o token de acesso a API, no campo access_token da mensagem json de retorno. Este token deve ser informado nos próximos passos.

{
    "scope": "am_application_scope default", 
    "token_type": "Bearer", 
    "expires_in": 3295, 
    "access_token": "eyJraWQiOiJyc2ExIiwiYWxnIjoiUlMyNTYifQ.eyJzdWIiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJpc3MiOiJOb3RpZmljYSBCUiAtIEhvbW9sb2dhw6fDo28iLCJhdWQiOiJlMzFkYzMwMy1mMGI4LTQ4M2QtYmFiNy02Y2JmOTM0NDVlOTMiLCJleHAiOjE2NjU2OTg1NjksImp0aSI6IlJZOVBoYkFxR0NMd3JKbm1Hb0tialEiLCJpYXQiOjE2NjU2OTEzNjksIm5iZiI6MTY2NTY5MTI0OX0.ApsFi0P_s4TULGIoYJpsZRvHEoodaOkIehFYBdGAIchr8FTV5Smak4NENTarEroebPIEJ6M99Gprhk1zFu5C7a6AIo2YDAZPEsU06s2fMBxIc0auG9qN75MvkTdawsLogv4K4AwxYLc2nsq-dL5t1KZAVCVaVPs99g-JCaPXBmT1Y0U16MW3iDOjHusnRYjFNxEp_sEQAjzktb4R3NZZ69qVay7ima0X8RA2cA9E8m-IcvcnSpzk87t5k1CFdYYTQ5l--tBqsQLBQiHGvw01R4oW2g3859G63Gkld101WyR7UJOcDVPZdyjaORRRSZVhA-Nde7H1P7P9FeMGODa2-w"
}

Renovação do Token de Acesso¶

Atentar que sempre que o token de acesso temporário expirar, o gateway vai retornar um HTTP CODE 401 após realizar
uma requisição para uma API. Neste caso, deve ser repetido o Segundo Passo "Como solicitar o Token de Acesso (Bearer)" para geração de um novo token de acesso temporário.

O produto final é 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 Avisa 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 Avisa 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¶

Ambiente de produçãoAmbiente de homologação

curl --request POST \
  --url https://gateway.apiserpro.serpro.gov.br/avisabr/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"}' \

curl --request POST \
  --url https://gateway.apiserpro.serpro.gov.br/avisabr-hom/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 Avisa 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¶

Ambiente de produçãoAmbiente de homologação

curl --request POST \
  --url https://gateway.apiserpro.serpro.gov.br/avisabr/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'

curl --request POST \
  --url https://gateway.apiserpro.serpro.gov.br/avisabr-hom/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¶

Ambiente de produçãoAmbiente de homologação

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

curl --request GET \
      --url https://gateway.apiserpro.serpro.gov.br/avisabr-hom/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¶

Ambiente de produçãoAmbiente de homologação

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

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