Skip to main content
Table of contents

Documentação da API REST

Esta documentação é para desenvolvedores interessados em usar o Gov.br Notifica para enviar e-mails, mensagens de texto ou notificações ao app Gov.br.

Você pode usá-lo para integração direta com a API.

URL Base

https://api.notificacao.servicos.gov.br

Cabeçalhos

Cabeçalho de Autorização

O cabeçalho de autorização é uma chave API que é codificada usando JSON Web Tokens. Você deve incluir um cabeçalho de autorização.

JSON Web Tokens têm um cabeçalho padrão e uma carga útil. O cabeçalho consiste em:

{
  "typ": "JWT",
  "alg": "HS256"
}

A carga útil consiste em:

{
  "iss": "26785a09-ab16-4eb0-8407-a37497a57506",
  "iat": 1568818578
}

JSON Web Tokens são codificados usando uma chave secreta com o seguinte formato:

3d844edf-8d35-48ac-975b-e847b4f122b0

Essa chave secreta faz parte da sua chave API, que segue o formato {key_name}-{iss-uuid}-{secret-key-uuid}.

Por exemplo, se sua [chave API] é my_test_key-26785a09-ab16-4eb0-8407-a37497a57506-3d844edf-8d35-48ac-975b-e847b4f122b0:

  • seu nome de chave de API é my_test_key
  • seu iss (seu id de serviço) é 26785a09-ab16-4eb0-8407-a37497a57506
  • sua chave secreta é 3d844edf-8d35-48ac-975b-e847b4f122b0

iat (emitido às) é a hora atual em UTC em segundos. O token expira em 30 segundos do horário atual.

Consulte o site JSON Web Tokens para obter mais informações sobre como codificar seu cabeçalho de autorização.

Quando você tiver um token codificado e assinado, adicione esse token a um cabeçalho da seguinte maneira:

"Authorization": "Bearer encoded_jwt_token"

Cabeçalho de Conteúdo

O cabeçalho do conteúdo é application/json:

"Content-type": "application/json"

Envie uma mensagem

Você pode usar Gov.br Notifica para enviar mensagens de texto, e-mails e cartas.

Enviar uma mensagem de texto

POST /v2/notifications/sms

Corpo da Requisição

{
  "phone_number": "+557900900123",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Arguments

phone_number (obrigatório)

O número de telefone do destinatário da mensagem de texto. O número deve conter o código do país + código do estado sem o 0, por exemplo: +5561987653462 ou 5561987653462

template_id (obrigatório)

Para encontrar o ID do template:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template desejado.
  3. Selecione Copiar template ID para o clipboard.

personalisation (opcional)

Se um template possuir campos reservados para informações personalizadas, como nome ou número de referência, você deve fornecer seus valores em um dictionary com pares de valores-chave. Por exemplo:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

Você pode omitir esse argumento se um modelo não tiver nenhum campo reservado para informações personalizadas.

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter nenhuma informação pessoal, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

Você pode omitir este argumento se não tiver uma referência.

sms_sender_id (opcional)

Um identificador exclusivo do remetente da notificação por mensagem de texto.

Para encontrar o remetente da mensagem de texto:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Settings.
  3. Na seção Mensagem de Texto, selecione Gerenciar na linha Text Message sender.

Você pode então:

  • copiar o ID do remetente que deseja usar e cole-o no método
  • selecionar Alterar para alterar o remetente padrão que o serviço usará e selecione Salvar
"sms_sender_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Você pode omitir esse argumento se o seu serviço tiver apenas um remetente de mensagem de texto ou se desejar usar o remetente padrão.

Resposta

Se a solicitação for bem-sucedida, o corpo da resposta será json com um código de status 201:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "body": "MESSAGE TEXT",
    "from_number": "SENDER"
  },
  "uri": "[ENDEREÇO DO DOMÍNIO]/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "[ENDEREÇO DO DOMÍNIO]/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
  }
}

Se você estiver usando uma chave de API de teste, todas as suas mensagens retornarão com o status entregue.

Todas as mensagens enviadas usando as chaves lista da equipe e convidados ou ao vivo aparecerão no seu painel.

Códigos de Erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code Mensagem Como resolver
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]}
Use o tipo correto de API key
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]
Seu serviço não pode enviar esta notificação em trial mode
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte API keys para obter mais informações
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}]
Consulte os limites de taxa de API para obter mais informações
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Consulte os limites de serviço para o número limite
500 [{
"error": "Exception",
"message": "Internal server error"
}]
O Gov.br Notifica não conseguiu processar a solicitação, reenvie sua notificação.

Enviar uma mensagem de texto pelo CPF

POST /v2/notifications/sms-cpf

Corpo da Requisição

{
  "cpf": "99999999999",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Arguments

cpf (obrigatório)

Corresponde ao CPF do destinatário da mensagem.

template_id (obrigatório)

Para encontrar o ID do template:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template desejado.
  3. Selecione Copiar template ID para o clipboard.

personalisation (opcional)

Se um template possuir campos reservados para informações personalizadas, como nome ou número de referência, você deve fornecer seus valores em um dictionary com pares de valores-chave. Por exemplo:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

Caso o template não possua nenhum campo reservado, não é necessário informar o personalisation.

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter informações pessoais, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

Caso não exista nenhuma referência, não é necessário informar o reference.

sms_sender_id (opcional)

Um identificador exclusivo do remetente da notificação por mensagem de texto.

Para encontrar o remetente da mensagem de texto:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Settings.
  3. Na seção Mensagem de Texto, selecione Gerenciar na linha Text Message sender.

Você pode então:

  • copiar o ID do remetente que deseja usar e cole-o no método
  • selecionar Alterar para alterar o remetente padrão que o serviço usará e selecione Salvar
"sms_sender_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Caso o seu serviço tenha apenas um remetente ou deseje utilizar o remetente padrão, não é necessário informar o sms_sender_id.

Resposta

Se a solicitação for bem-sucedida, o corpo da resposta será json com um código de status 201:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "body": "MESSAGE TEXT",
    "from_number": "SENDER"
  },
  "uri": "[ENDEREÇO DO DOMÍNIO]/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "[ENDEREÇO DO DOMÍNIO]/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
  }
}

Se você estiver usando uma chave de API de teste, todas as suas mensagens retornarão com o status entregue.

Todas as mensagens enviadas usando as chaves lista da equipe e convidados ou ao vivo aparecerão no seu painel.

Códigos de Erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code Mensagem Como resolver
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]}
Use o tipo correto de API key
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]
Seu serviço não pode enviar esta notificação em trial mode
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte API keys para obter mais informações
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}]
Consulte os limites de taxa de API para obter mais informações
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Consulte os limites de serviço para o número limite
500 [{
"error": "Exception",
"message": "Internal server error"
}]
O Gov.br Notifica não conseguiu processar a solicitação, reenvie sua notificação.

Enviar um e-mail

POST /v2/notifications/email

Corpo da Requisição

{
  "email_address": "sender@something.com",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Arguments

email_address (obrigatório)

O endereço de e-mail do destinatário.

template_id (obrigatório)

Para encontrar o ID do template:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template desejado.
  3. Selecione Copiar template ID para o clipboard.

personalisation (opcional)

Se um template possuir campos reservados para informações personalizadas, como nome ou número de referência, você deve fornecer seus valores em um dictionary com pares de valores-chave. Por exemplo:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

Caso o template não possua nenhum campo reservado, não é necessário informar o personalisation.

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter informações pessoais, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

Caso não exista nenhuma referência, não é necessário informar o reference.

email_reply_to_id (opcional)

Este é um endereço de e-mail especificado por você para receber respostas de seus usuários. Você deve adicionar pelo menos um endereço de e-mail para resposta antes que seu serviço seja publicado.

Para adicionar um endereço de e-mail para resposta:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Settings.
  3. Na seção Email, selecione Gerenciar na linha Reply-to email address.
  4. Selecione Adicionar endereço de resposta.
  5. Digite o endereço de e-mail que deseja usar e selecione Adicionar.

Por exemplo:

"email_reply_to_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Você pode omitir este argumento se o seu serviço tiver apenas um endereço de e-mail para resposta ou se você quiser usar o endereço de e-mail padrão.

Enviar arquivo por e-mail

Para enviar um arquivo por e-mail, adicione um espaço reservado ao modelo e, em seguida, carregue um arquivo. O espaço reservado conterá um link seguro para baixar o arquivo.

Os links são únicos e indescritíveis. Gov.br Notifica não pode acessar ou descriptografar seu arquivo.

Adicione detalhes de contato à página de download do arquivo

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Configurações.
  3. Na seção Email, selecione Gerenciar na linha Enviar arquivos por e-mail.
  4. Insira os detalhes do contato que deseja usar e selecione Salvar.

Adicione um marcador de posição ao template

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template de email relevante.
  3. Selecione Editar.
  4. Adicione um espaço reservado ao modelo de email usando colchetes duplos. Por exemplo:

“Download your file at: ((link_to_file))”

Envie seu arquivo

Você pode fazer upload de arquivos PDF, CSV, .odt, .txt e documentos do MS Word. Seu arquivo deve ser menor que 2 MB. Entre em contato com a equipe do Gov.br Notifica se você precisar enviar outros tipos de arquivo. Você precisará converter o arquivo em uma string codificada em base64.

Passe a string codificada para um objeto com uma chave file e coloque-a no argumento de personalização. Por exemplo:

"personalisation":{
  "first_name": "Amala",
  "application_date": "2018-01-01",
  "link_to_file": {"file": "file as base64 encoded string"}
}

Arquivos CSV

Uploads para arquivos CSV devem definir o sinalizador is_csv como true para garantir que ele seja baixado como um arquivo .csv. Por exemplo:

"personalisation":{
  "first_name": "Amala",
  "application_date": "2018-01-01",
  "link_to_file": {"file": "CSV file as base64 encoded string", "is_csv": true}
}

Response

Se a solicitação ao cliente for bem-sucedida, o cliente retornará um dict:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "MESSAGE TEXT",
    "from_email": "SENDER EMAIL"
  },
  "uri": "[ENDEREÇO DO DOMÍNIO]/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "[ENDEREÇO DO DOMÍNIO]/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

Códigos de erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code mensagem como resolver
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]}
Use o tipo correto de chave API
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]
Seu serviço não pode enviar esta notificação em modo de teste
400 [{
"error": "BadRequestError",
"message": "Unsupported file type '(FILE TYPE)'. Supported types are: '(ALLOWED TYPES)"
}]
Tipo de arquivo errado. Você só pode fazer upload de arquivos .pdf, .csv, .txt, .doc, .docx ou .odt
400 [{
"error": "BadRequestError",
"message": "File did not pass the virus scan"
}]
O arquivo contém um vírus
400 [{
"error": "BadRequestError",
"message": "Send files by email has not been set up - add contact details for your service at https://www.notifications.service.gov.uk/services/(SERVICE ID)/service-settings/send-files-by-email"
}]
Veja como adicionar detalhes de contato à página de download de arquivos
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte chaves API para mais informações
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}]
Consulte limites de taxa de API para mais informações
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Consulte os limites de serviços para o número limite
500 [{
"error": "Exception",
"message": "Internal server error"
}]
Gov.br Notifica não conseguiu processar a solicitação, reenvie sua notificação.

Enviar um e-mail por CPF

POST /v2/notifications/email-cpf

Corpo da Requisição

{
  "cpf": "99999999999",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Arguments

cpf (obrigatório)

Corresponde ao CPF do destinatário da mensagem.

template_id (obrigatório)

Para encontrar o ID do template:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template desejado.
  3. Selecione Copiar template ID para o clipboard.

personalisation (opcional)

Se um template possuir campos reservados para informações personalizadas, como nome ou número de referência, você deve fornecer seus valores em um dictionary com pares de valores-chave. Por exemplo:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

Caso o template não possua nenhum campo reservado, não é necessário informar o personalisation

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter informações pessoais, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

Caso não exista nenhuma referência, não é necessário informar o reference.

email_reply_to_id (opcional)

Este é um endereço de e-mail especificado por você para receber respostas de seus usuários. Você deve adicionar pelo menos um endereço de e-mail para resposta antes que seu serviço seja publicado.

Para adicionar um endereço de e-mail para resposta:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Settings.
  3. Na seção Email, selecione Gerenciar na linha Reply-to email address.
  4. Selecione Adicionar endereço de resposta.
  5. Digite o endereço de e-mail que deseja usar e selecione Adicionar.

Por exemplo:

"email_reply_to_id": "8e222534-7f05-4972-86e3-17c5d9f894e2"

Caso o seu serviço tenha apenas um e-mail de resposta ou deseje utilizar o e-mail de resposta padrão, não é necessário informar o email_reply_to_id.

Response

Se a solicitação ao cliente for bem-sucedida, o cliente retornará um dict:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "subject": "SUBJECT TEXT",
    "body": "MESSAGE TEXT",
    "from_email": "SENDER EMAIL"
  },
  "uri": "[ENDEREÇO DO DOMÍNIO]/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "[ENDEREÇO DO DOMÍNIO]/v2/template/f33517ff-2a88-4f6e-b855-c550268ce08a"
  }
}

Códigos de erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code mensagem como resolver
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]}
Use o tipo correto de chave API
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]
Seu serviço não pode enviar esta notificação em modo de teste
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte chaves API para mais informações
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}]
Consulte limites de taxa de API para mais informações
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Consulte os limites de serviços para o número limite
500 [{
"error": "Exception",
"message": "Internal server error"
}]
Gov.br Notifica não conseguiu processar a solicitação, reenvie sua notificação.

Enviar notificações ao app Gov.br

POST /v2/notifications/govbrcpf

Corpo da Requisição

{
  "cpf": "99999999999",
  "template_id": "f33517ff-2a88-4f6e-b855-c550268ce08a"
}

Arguments

cpf (obrigatório)

Corresponde ao CPF do destinatário da mensagem.

template_id (obrigatório)

Para encontrar o ID do template:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página Templates e selecione o template desejado.
  3. Selecione Copiar template ID para o clipboard.

personalisation (opcional)

Se um template possuir campos reservados para informações personalizadas, como nome ou número de referência, você deve fornecer seus valores em um dictionary com pares de valores-chave. Por exemplo:

"personalisation": {
  "first_name": "Amala",
  "application_date": "2018-01-01",
}

Caso o template não possua nenhum campo reservado, não é necessário informar o personalisation

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter informações pessoais, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

Caso não exista nenhuma referência, não é necessário informar o reference.

Response

Se a solicitação for bem-sucedida, o corpo da resposta será json com um código de status 201:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a",
  "reference": "STRING",
  "content": {
    "body": "MESSAGE TEXT",
  },
  "uri": "[ENDEREÇO DO DOMÍNIO]/v2/notifications/740e5834-3a29-46b4-9a6f-16142fde533a",
  "template": {
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a",
    "version": 1,
    "uri": "[ENDEREÇO DO DOMÍNIO]/v2/template/ceb50d92-100d-4b8b-b559-14fa3b091cd"
  }
}

Códigos de erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code Mensagem Como resolver
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient using a team-only API key"
]}
Use o tipo correto de API key
400 [{
"error": "BadRequestError",
"message": "Can't send to this recipient when service is in trial mode - see https://www.notifications.service.gov.uk/trial-mode"
}]
Seu serviço não pode enviar esta notificação em trial mode
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte API keys para obter mais informações
429 [{
"error": "RateLimitError",
"message": "Exceeded rate limit for key type TEAM/TEST/LIVE of 3000 requests per 60 seconds"
}]
Consulte os limites de taxa de API para obter mais informações
429 [{
"error": "TooManyRequestsError",
"message": "Exceeded send limits (LIMIT NUMBER) for today"
}]
Consulte os limites de serviço para o número limite
500 [{
"error": "Exception",
"message": "Internal server error"
}]
O Gov.br Notifica não conseguiu processar a solicitação, reenvie sua notificação.

Obter status da mensagem

O status da mensagem depende do tipo de mensagem enviada.

Você só pode obter o status das mensagens com 7 dias ou mais recentes.

Status - email

Status Informação
Criado Gov.br Notifica colocou a mensagem em uma fila, pronta para ser enviada ao provedor. Deve permanecer neste estado apenas por alguns segundos.
Enviando Gov.br Notifica está enviando a mensagem para o provedor de e-mail.
Enviado/Entregue Gov.br Notifica entregou a mensagem para o provedor de e-mail. O provedor tentará entregar a mensagem ao destinatário por até 72 horas. A API do cliente Gov.br Notifica retorna esse status como Enviado. O aplicação cliente do Gov.br Notifica retorna esse status como Entregue.
Falhou Isso abrange todos os status de falha:
- permanent-failure - “O provedor não conseguiu entregar a mensagem porque o endereço de e-mail estava errado. Você deve remover esses endereços de e-mail de seu banco de dados.”
- temporary-failure - “O provedor não conseguiu entregar a mensagem. Isso pode acontecer quando a caixa de entrada do destinatário está cheia. Você pode tentar enviar a mensagem novamente.”
- technical-failure - “Sua mensagem não foi enviada porque houve um problema entre o Notifica e o provedor de e-mail.
Você terá que tentar enviar suas mensagens novamente.”

Status - mensagem de texto

Status Informação
Criado O Gov.br Notifica colocou a mensagem em uma fila, pronta para ser enviada ao provedor. Ele deve permanecer nesse estado apenas por alguns segundos.
Enviando O Gov.br Notifica está enviando a mensagem para o provedor de SMS.
Enviado/Entregue A mensagem foi entregue para o provedor de SMS. As redes móveis em alguns países não fornecem mais informações de entrega. A API do cliente Gov.br Notifica retorna esse status como Enviado. O aplicação cliente do Gov.br Notifica retorna esse status como Entregue.
Falhou Isso abrange todos os status de falha:
- permanent-failure - “O provedor não conseguiu entregar a mensagem. Isso pode acontecer se o número do telefone estiver errado ou se a operadora rejeitar a mensagem. Se tiver certeza de que esses números de telefone estão corretos, você deve entrar em contato com o suporte de notificação do Gov.br Notifica. Caso contrário, você deve removê-los de seu banco de dados. Você ainda será cobrado por mensagens de texto que não puderem ser entregues.”
- temporary-failure - “O provedor não conseguiu entregar a mensagem. Isso pode acontecer quando o telefone do destinatário está desligado, não há sinal ou a caixa de entrada de mensagens de texto está cheia. Você pode tentar enviar a mensagem novamente. Você ainda será cobrado por mensagens de texto para telefones que não aceitam mensagens.”
- technical-failure - “Sua mensagem não foi enviada porque houve um problema entre o Gov.br Notifica e o provedor.
Você terá que tentar enviar suas mensagens novamente. Você não será cobrado por mensagens de texto afetadas por uma falha técnica.”

Status - Notificação app Gov.br

Status information
Criado O Gov.br Notifica colocou a mensagem em uma fila, pronta para ser enviada ao provedor. Ele deve permanecer nesse estado apenas por alguns segundos.
Enviando O Gov.br Notifica está enviando a mensagem ao Gov.br.
Enviado/Entregue A mensagem foi entregue com sucesso. A API do cliente Gov.br Notifica retorna esse status como Enviado. O aplicação cliente do Gov.br Notifica retorna esse status como Entregue.
Falhou Isso abrange todos os status de falha:
- permanent-failure - “O provedor não pôde entregar a mensagem pois uma notificação idêntica já foi enviada ao destinatário. Você deve remover essa opção de envio ao destinatário do seu banco de dados.”
- temporary-failure - “Sua mensagem não foi enviada porque houve um problema entre o Notifica e o provedor do APP meu gov.br. Você pode tentar enviar a mensagem novamente.”
- technical-failure - “Sua mensagem não foi enviada porque o destinatário não possui o app GOV.BR instalado ou a comunicação com o mesmo não foi possível. Você terá que tentar enviar suas mensagens novamente.”

Obtenha o status de uma mensagem

GET /v2/notifications/{notification_id}

Parâmetros de consulta

notification_id (obrigatório)

O ID da notificação. Você pode encontrar o ID de notificação na resposta à chamada do método de notificação original.

Você também pode encontrá-lo entrando em Gov.br Notifica e indo para a página de integração API.

Você pode filtrar as mensagens retornadas incluindo os seguintes parâmetros opcionais no URL:

Resposta

Se a solicitação for bem-sucedida, o corpo da resposta será json e o código de status será 200:

{
  "id": "740e5834-3a29-46b4-9a6f-16142fde533a", # required string - notification ID
  "reference": "STRING", # optional string
  "email_address": "sender@something.com",  # required string for emails
  "phone_number": "+447900900123",  # required string for text messages
  "line_1": "ADDRESS LINE 1", # required string for letter
  "line_2": "ADDRESS LINE 2", # required string for letter
  "line_3": "ADDRESS LINE 3", # optional string for letter
  "line_4": "ADDRESS LINE 4", # optional string for letter
  "line_5": "ADDRESS LINE 5", # optional string for letter
  "line_6": "ADDRESS LINE 6", # optional string for letter
  "postcode": "STRING", # required string for letter, must be a real UK postcode
  "type": "sms / letter / email", # required string
  "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure", # required string
  "template": {
    "Version": 1
    "id": "f33517ff-2a88-4f6e-b855-c550268ce08a" # required string - template ID
    "uri": "/v2/template/{id}/{version}", # required
  },
  "body": "STRING", # required string - body of notification
  "subject": "STRING" # required string for email - subject of email
  "created_at": "STRING", # required string - date and time notification created
  "created_by_name": "STRING", # optional string - name of the person who sent the notification if sent manually
  "sent_at": "STRING", # optional string - date and time notification sent to provider
  "completed_at:" "STRING" # optional string - date and time notification delivered or failed
}

Códigos de erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code mensagem Como consertar
400 [{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
Verifique o ID de notificação
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte chaves API para mais informações
404 [{
"error": "NoResultFound",
"message": "No result found"
}]
Verifique o ID de notificação

Obtenha o status de várias mensagens

Esta chamada de API retorna uma página de até 250 mensagens e status. Você pode obter as mensagens mais recentes ou as mais antigas especificando um ID de notificação particular no argumento higher_than.

Você só pode obter o status das mensagens com 7 dias ou mais recentes.

GET /v2/notifications

Todas as mensagens

Isso retornará todas as suas mensagens com status. Eles serão exibidos em páginas de até 250 mensagens cada.

Você pode filtrar as mensagens retornadas incluindo os seguintes argumentos opcionais no URL:

Arguments

Você pode omitir qualquer um desses argumentos para ignorar esses filtros.

template_type (opcional)

Você pode filtrar por:

  • email
  • sms
  • gov.br

status (opcional)

Você pode filtrar por cada:

Você pode deixar esse argumento de fora para ignorar esse filtro.

reference (opcional)

Um identificador que você pode criar, se necessário. Esta referência identifica uma única notificação ou um lote de notificações. Não deve conter nenhuma informação pessoal, como nome ou endereço postal. Por exemplo:

"reference": "STRING"

older_than (opcional)

Insira o ID de uma notificação neste argumento. Se você usar este argumento, o método retornará as próximas 250 notificações recebidas mais antigas do que o ID fornecido.

"older_than":"740e5834-3a29-46b4-9a6f-16142fde533a"

Se você deixar esse argumento de fora, o método retornará as 250 notificações mais recentes.

O cliente retorna apenas notificações com 7 dias ou mais. Se a notificação especificada neste argumento tiver mais de 7 dias, o cliente retornará uma resposta vazia.

Resposta

Se a solicitação for bem-sucedida, o corpo da resposta será json e o código de status será 200.

All messages

{
  "notifications": [
    {
      "id": "740e5834-3a29-46b4-9a6f-16142fde533a", # required string - notification ID
      "reference": "STRING", # optional string - client reference
      "email_address": "sender@something.com",  # required string for emails
      "phone_number": "+447900900123",  # required string for text messages
      "line_1": "ADDRESS LINE 1", # required string for letter
      "line_2": "ADDRESS LINE 2", # required string for letter
      "line_3": "ADDRESS LINE 3", # optional string for letter
      "line_4": "ADDRESS LINE 4", # optional string for letter
      "line_5": "ADDRESS LINE 5", # optional string for letter
      "line_6": "ADDRESS LINE 6", # optional string for letter
      "postcode": "STRING", # required for string letter, must be a real UK postcode
      "type": "sms / letter / email", # required string
      "status": "sending / delivered / permanent-failure / temporary-failure / technical-failure", # required string
      "template": {
        "version": 1
        "id": 'f33517ff-2a88-4f6e-b855-c550268ce08a' # required string - template ID
        "uri": "/v2/template/{id}/{version}", # required
      },
      "body": "STRING", # required string - body of notification
      "subject": "STRING" # required string for email - subject of email
      "created_at": "STRING", # required string - date and time notification created
      "created_by_name": "STRING", # optional string - name of the person who sent the notification if sent manually
      "sent_at": " STRING", # optional string - date and time notification sent to provider
      "completed_at": "STRING" # optional string - date and time notification delivered or failed
    },
    
  ],
  "links": {
    "current": "/notifications?template_type=sms&status=delivered",
    "next": "/notifications?other_than=last_id_in_list&template_type=sms&status=delivered"
  }
}

Códigos de erro

Se a solicitação não for bem-sucedida, o corpo da resposta é json, consulte a tabela abaixo para obter detalhes.

status_code message Como consertar
400 [{
"error": "ValidationError",
"message": "id is not a valid UUID"
}]
Verifique o ID de notificação
403 [{
"error": "AuthError",
"message": "Error: Your system clock must be accurate to within 30 seconds"
}]
Verifique o relógio do seu sistema
403 [{
"error": "AuthError",
"message": "Invalid token: API key not found"
}]
Use a chave de API correta. Consulte chaves API para mais informações
404 [{
"error": "NoResultFound",
"message": "No result found"
}]
Verifique o ID de notificação

Testando

Todos os testes ocorrem no ambiente de produção. Não há ambiente de teste para Gov.br Notifica.

Teste de fumaça

Se você precisar de teste de fumaça sua integração com o Gov.br Notifica regularmente, você deve usar os seguintes números de telefone e endereços de e-mail para teste de fumaça.

 
Número de telefone
07700900000
07700900111
07700900222
Endereço de e-mail
simulate-delivered@notifications.service.gov.uk
simulate-delivered-2@notifications.service.gov.uk
simulate-delivered-3@notifications.service.gov.uk

Os números de telefone e endereços de e-mail do teste de fumaça validarão a solicitação e simularão uma resposta bem-sucedida, mas não enviarão uma mensagem real, produzirão um recibo de entrega ou manterão a notificação no banco de dados.

Você pode usar esses números e endereços de teste de fumaça com qualquer tipo de chave de API.

Você pode testar todas as funções do cliente Notificação API, exceto:

  • Obtenha o status de uma mensagem
  • Obtenha o status de todas as mensagens

Você não pode usar os números de telefone ou endereço de e-mail do teste de fumaça com essas funções porque eles retornam um falso notification_ID. Se você precisar testar essas funções, use uma chave API de teste e qualquer outro número de telefone ou e-mail.

Outros testes

Você deve usar uma chave de API de teste para fazer um teste sem fumaça, como teste de desempenho ou integração. Você pode usar qualquer número de telefone ou endereço de e-mail de teste que não seja fumante. Você não precisa de uma conta de teste específica do Gov.br Notifica.

Chaves da API

Existem três tipos diferentes de chaves de API:

  • teste
  • lista de equipe e de convidados
  • ao vivo

Quando você configura um novo serviço, ele começa em modo de teste. Um serviço em modo de teste pode criar chaves de lista de teste e equipe e de convidados. Você deve ter um serviço ativo para criar uma chave ativa.

Para criar uma chave de API:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página de Integração da API.
  3. Selecione chaves de API.
  4. Selecione Criar uma chave da API.

Teste

Use uma chave de teste para testar o desempenho de seu serviço e sua integração com Gov.br Notifica.

Mensagens enviadas usando uma chave de teste:

  • gerar respostas realistas
  • resulta em um status entregue
  • não são realmente entregues a um destinatário
  • não aparecem no seu painel
  • não conte para as suas mensagens de texto e e-mail

Para testar as respostas de falha com uma chave de teste, use os seguintes números e endereços:

Número de telefone / endereço de e-mail Resposta
07700900003 temporary-failure
07700900002 permanent-failure
temp-fail@simulator.notify temporary-failure
perm-fail@simulator.notify permanent-failure
qualquer outro número ou endereço válido delivered

Você não precisa revogar as chaves de teste.

Equipe e lista de convidados

Uma chave de equipe e lista de convidados permite que você envie mensagens reais aos membros de sua equipe e endereços / números em sua lista de convidados enquanto seu serviço ainda está em modo de teste.

Você receberá um erro se usar essas teclas para enviar mensagens a alguém que não esteja em sua equipe ou na sua lista de convidados.

As mensagens enviadas com uma chave de equipe e lista de convidados aparecem em seu painel e contam em sua mensagem de texto e e-mail.

Você não precisa revogar as chaves da equipe e da lista de convidados.

Ao Vivo

Você só pode criar chaves ativas quando o serviço estiver ativo. Você pode usar as teclas ativas para enviar mensagens para qualquer pessoa.

As mensagens enviadas com uma tecla ativa aparecem no seu painel e contam contra as suas mensagens de texto e e-mail.

Você deve revogar e recriar essas chaves regularmente. Para revogar uma chave:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página de Integração da API.
  3. Selecione chaves de API.
  4. Selecione Revogar para a chave de API que você deseja revogar.

Você pode ter mais de uma chave ativa por vez.

Você nunca deve enviar mensagens de teste para números ou endereços inválidos usando uma chave ativa.

Limites

Limites de taxa

Você está limitado a enviar 3.000 mensagens por minuto.

Esse limite é calculado em uma base contínua, por tipo de chave de API. Se você exceder o limite, obterá o erro 429 RateLimitError.

Limites diários

Há um limite para o número de mensagens que você pode enviar por dia:

Status do serviço Tipo de chave API Limite diário
Ao vivo Equipe ou ao vivo 250,000
Trial Equipe 50
Ao vivo ou trial Teste Ilimitada

Esses limites são redefinidos à meia-noite.

Limites da rede telefônica

Se você enviar mensagens de texto repetidamente para o mesmo número, as redes telefônicas as bloquearão.

Existe um limite por hora de:

  • 20 mensagens com o mesmo conteúdo
  • 100 mensagens com qualquer conteúdo

Suas mensagens não podem ser entregues se você exceder esses limites.

Chamadas de retorno

Chamadas de retorno são quando o Gov.br Notifica envia solicitações POST para o seu serviço. Você pode obter retornos de chamada quando:

  • uma mensagem de texto ou e-mail que você enviou foi entregue ou falhou
  • seu serviço recebe uma mensagem de texto

Configurar chamadas de retorno

Você deve fornecer:

  • um URL onde o Gov.br Notifica postará o retorno para a chamada
  • um token de portador que o Gov.br Notifica colocará no cabeçalho de autorização das solicitações

Para fazer isso:

  1. Faça login no Gov.br Notifica.
  2. Vá para a página de Integração da API.
  3. Selecione Callbacks.

Recibos de entrega

Quando você envia um e-mail ou mensagem de texto, o Gov.br Notifica envia um recibo para o seu URL de retorno com o status da mensagem. Este é um método automatizado para obter o status das mensagens.

Esta funcionalidade funciona com chaves de API de teste, mas não funciona com números de telefone ou endereços de e-mail de teste de fumaça.

A mensagem de retorno de chamada é formatada em JSON. A chave, a descrição e o formato dos argumentos da mensagem de retorno de chamada serão:

Chave Descrição Formato
id ID de notificação para os recibos de status UUID
reference A referência enviada pelo serviço 12345678
to O endereço de e-mail ou número de telefone do destinatário hello@gov.uk ou 07700912345
status O status da notificação delivered, permanent-failure, temporary-failure ou technical-failure
created_at A hora em que o serviço enviou a solicitação 2017-05-14T12:15:30.000000Z
completed_at A última vez que o status foi atualizado 2017-05-14T12:15:30.000000Z ou nulo
sent_at A hora em que a notificação foi enviada 2017-05-14T12:15:30.000000Z ou nulo
notification_type O tipo de notificação email ou sms

Mensagens de texto recebidas

Se o seu serviço receber mensagens de texto no Gov.br Notifica, o Gov.br Notifica pode encaminhá-las para o seu URL de retorno de chamada assim que chegarem.

Contate a equipe do Gov.br Notifica usando a página de suporte ou converse conosco no Slack para solicitar um número exclusivo para respostas de mensagens de texto.

A mensagem de retorno de chamada é formatada em JSON. A chave, a descrição e o formato dos argumentos da mensagem de retorno de chamada serão:

Chave Descrição Formato
id ID da notificação para a mensagem recebida UUID
source_number O número de telefone de onde a mensagem foi enviada 447700912345
destination_number O número para o qual a mensagem foi enviada (seu número) 07700987654
message A mensagem recebida Hello Notify!
date_received A data e hora UTC em que a mensagem foi recebida pelo Gov.br Notifica 2017-05-14T12:15:30.000000Z

Arquitetura da API

Envie uma mensagem

Obter status da mensagem

Receba mensagens de entrada

Suporte

Relate quaisquer problemas através da página de suporte de notificação do Gov.br Notifica.