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. Atualmente o sender do SMS no Notifica Gov.Br é único. Não é possível alterá-lo.

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 ou o iat gerado.
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 1000 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. Atualmente o sender do SMS no Notifica Gov.Br é único. Não é possível alterá-lo.

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 ou o iat gerado.
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 1000 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)

Ainda não é possível utilizar no Notifica Gov.Br

Enviar arquivo por e-mail

Ainda não é possível utilizar no Notifica Gov.Br

Resposta

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://notificacao.servicos.gov.br/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 ou o iat gerado
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 1000 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)

Ainda não é possível utilizar no Notifica Gov.Br

Resposta

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://notificacao.servicos.gov.br/using-notify/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 ou o iat gerado
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 1000 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.

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",
  },
  "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://notificacao.servicos.gov.br/using-notify/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 ou o iat gerado.
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 1000 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 de e-mail. 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. 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. O provedor de e-mail tentará entregar a mensagem ao destinatário por até 72 horas.
Falhou Isso abrange todos os status de falha:
- permanent-failure - “O Notifica não conseguiu entregar o e-mail para o provedor.”
- temporary-failure - “O Notifica não conseguiu entregar o email ao provedor. 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ê pode 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 de SMS. 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. 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. O provedor de SMS tentará entregar a mensagem ao destinatário por até 24 horas.
Falhou Isso abrange todos os status de falha:
- permanent-failure - “O Notifica não conseguiu entregar a mensagem ao provedor.”
- temporary-failure - “O Notifica não conseguiu entregar a mensagem ao provedor. Você pode tentar enviar a mensagem novamente.”
- technical-failure - “Sua mensagem não foi enviada porque houve um problema entre o Gov.br Notifica e o provedor.
Você pode tentar enviar suas mensagens novamente.”

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 do aplicativo. Ele deve permanecer nesse estado apenas por alguns segundos.
Enviando O Gov.br Notifica está enviando a mensagem ao aplicativo do Gov.br.
Enviado/Entregue A mensagem foi entregue com sucesso no aplicativo. 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.”
- temporary-failure - “Sua mensagem não foi enviada porque houve um problema entre o Notifica e o provedor do aplicativo 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 aplicativo GOV.BR instalado ou a comunicação com o mesmo não foi possível. Você pode tentar que tentar enviar suas mensagens novamente mais tarde.”

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 ou o iat gerado
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 ou o iat gerado
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 no 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 de fumaça. 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 (Produção)

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

As mensagens enviadas com uma chave 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 1.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 150,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

Arquitetura da API

Envie uma mensagem

Importante ressaltar que a parte da resposta entre o recipient e o provider ainda não estão disponíveis no Notifica Gov.Br

Obter status da mensagem

Suporte

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