import requests

URL = "https://pombo.digital/api/integrations/v1/notifications"
headers = {
    "Authorization": "Bearer sk_live_...",
    "Idempotency-Key": "cobranca-2026-08-31-0001",
}

notification = {
    "template_id": "PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
    "channel": "WHATSAPP",
    "recipient_full_name": "Maria Silva",
    "recipient_tax_id": "12345678901",
    "recipient_tax_id_type": "CPF",
    "recipient_phone": "+5511999998888",
    "parameters": {"{{1}}": "Maria"},
}

requests.post(URL, headers=headers, json=notification)

{
  "notification_id": "<string>",
  "organization_id": "<string>",
  "template_id": "<string>",
  "channel": "WHATSAPP",
  "recipient_full_name": "<string>",
  "recipient_tax_id": "<string>",
  "recipient_tax_id_type": "CPF",
  "recipient_phone": "<string>",
  "recipient_email": "<string>",
  "contact_id": "PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "line_id": "PBD_WALN_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "parameters": {
    "{{1}}": "Maria"
  },
  "message": "<string>",
  "content_sha256": "3b1c8d6e4f2a0b9c7d5e3f1a8c6d2b0e9f7a5c3d1e8f6b4a2c0d9e7f5a3b1c8d",
  "message_format": "<string>",
  "notification_status": "DRAFT",
  "notification_delivery_status": "PENDING",
  "sender": {
    "name": "<string>",
    "tax_id": "<string>",
    "tax_id_type": "CPF",
    "contact_phone": "+5511999998888",
    "contact_email": "jsmith@example.com"
  },
  "sender_phone": "5511952134898",
  "sender_email": "ola@pombo.digital",
  "created_by_type": "<string>",
  "created_by_user_id": "PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "idempotency_key": "<string>",
  "batch_id": "<string>",
  "batch_item_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "sent_at": "2023-11-07T05:31:56Z",
  "delivered_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "created_by_email": "<string>",
  "created_by_name": "<string>",
  "attachments": [
    {
      "attachment_id": "<string>",
      "filename": "<string>",
      "mime_type": "application/pdf",
      "size_bytes": 123,
      "hash": "9f2c1d7a4b6e8f0c2a4d6e8f0b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c",
      "hash_algorithm": "SHA-256",
      "hash_encoding": "hex"
    }
  ]
}

Notificações

Cria uma notificação extrajudicial.

Emite uma notificação extrajudicial certificada para o destinatário informado.

Um modelo é obrigatório. Não existe envio de texto livre: o conteúdo vem de template_id preenchido por parameters. O campo message da resposta é o texto já renderizado.

Chame GET /templates/{id} antes. É de lá que saem as chaves de parameters.

É assíncrona: a resposta confirma a criação, não a entrega. Acompanhe com GET /notifications/{id}.

Consome um envio do saldo da organização. Uma notificação emitida não pode ser cancelada. Envie um Idempotency-Key para que uma repetição não notifique a mesma pessoa duas vezes.

Com anexo, tudo vai numa chamada só. Sem anexo, application/json como sempre; com anexo, multipart/form-data com as partes notification e file. Não existe endpoint separado para subir o arquivo.

channel aceita WHATSAPP ou EMAIL. Qualquer outro valor é recusado com 400 Invalid request: channel must be WHATSAPP or EMAIL.

Um corpo JSON mal formado é recusado com 400, não com 500: {"code": 10400, "http_code": 400, "message": "Invalid request: malformed JSON"}. Uma vírgula sobrando não custa envio nenhum.

POST

notifications

import requests

URL = "https://pombo.digital/api/integrations/v1/notifications"
headers = {
    "Authorization": "Bearer sk_live_...",
    "Idempotency-Key": "cobranca-2026-08-31-0001",
}

notification = {
    "template_id": "PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
    "channel": "WHATSAPP",
    "recipient_full_name": "Maria Silva",
    "recipient_tax_id": "12345678901",
    "recipient_tax_id_type": "CPF",
    "recipient_phone": "+5511999998888",
    "parameters": {"{{1}}": "Maria"},
}

requests.post(URL, headers=headers, json=notification)

{
  "notification_id": "<string>",
  "organization_id": "<string>",
  "template_id": "<string>",
  "channel": "WHATSAPP",
  "recipient_full_name": "<string>",
  "recipient_tax_id": "<string>",
  "recipient_tax_id_type": "CPF",
  "recipient_phone": "<string>",
  "recipient_email": "<string>",
  "contact_id": "PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "line_id": "PBD_WALN_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "parameters": {
    "{{1}}": "Maria"
  },
  "message": "<string>",
  "content_sha256": "3b1c8d6e4f2a0b9c7d5e3f1a8c6d2b0e9f7a5c3d1e8f6b4a2c0d9e7f5a3b1c8d",
  "message_format": "<string>",
  "notification_status": "DRAFT",
  "notification_delivery_status": "PENDING",
  "sender": {
    "name": "<string>",
    "tax_id": "<string>",
    "tax_id_type": "CPF",
    "contact_phone": "+5511999998888",
    "contact_email": "jsmith@example.com"
  },
  "sender_phone": "5511952134898",
  "sender_email": "ola@pombo.digital",
  "created_by_type": "<string>",
  "created_by_user_id": "PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N",
  "idempotency_key": "<string>",
  "batch_id": "<string>",
  "batch_item_id": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "sent_at": "2023-11-07T05:31:56Z",
  "delivered_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "created_by_email": "<string>",
  "created_by_name": "<string>",
  "attachments": [
    {
      "attachment_id": "<string>",
      "filename": "<string>",
      "mime_type": "application/pdf",
      "size_bytes": 123,
      "hash": "9f2c1d7a4b6e8f0c2a4d6e8f0b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c",
      "hash_algorithm": "SHA-256",
      "hash_encoding": "hex"
    }
  ]
}

Authorizations

Authorization

string

header

required

Sua credencial de API no cabeçalho Authorization: Bearer sk_live_.... Crie e revogue credenciais no painel, em Conta → API Keys. O segredo aparece uma única vez, na criação.

A credencial identifica a organização: organization_id não é aceito em nenhuma requisição.

Headers

Idempotency-Key

string

Chave de idempotência do envio. Letras, dígitos, sublinhados e hifens.

Com a mesma chave:

tudo igual, mesmo corpo e, se houver, mesmo arquivo: 200 com o corpo original e o cabeçalho Idempotent-Replayed: true
qualquer diferença, no corpo ou no arquivo: 409 IDEMPOTENCY_KEY_REUSED

O arquivo faz parte da chave, para que dois documentos diferentes nunca sejam confundidos com a mesma notificação. Na prática: para repetir um envio com anexo, reenvie os mesmos bytes.

A chave nunca é liberada. Para repetir um envio que falhou, use uma chave nova.

Até 255 caracteres. Uma chave mal formada é recusada com 400, sem error_code, mas não antes de tudo: o formato do corpo, o channel, file_transfer_id, attachment_id e organization_id são conferidos primeiro, e num multipart/form-data as partes já foram lidas antes disso.

Pattern: ^[A-Za-z0-9_-]+$

Example:

"cobranca-2026-08-31-0001"

Body

template_id

string

required

O modelo a usar. Em WhatsApp precisa estar APPROVED.

Example:

"PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0N"

channel

enum<string>

required

Em maiúsculas.

Available options:

WHATSAPP,

EMAIL

recipient_full_name

string

required

Minimum string length: 1

recipient_tax_id

string

required

CPF (11 dígitos) ou CNPJ (14 dígitos), só dígitos.

Pattern: ^([0-9]{11}|[0-9]{14})$

recipient_tax_id_type

enum<string>

required

Um valor fora de CPF e CNPJ é recusado com 400.

Available options:

CPF,

CNPJ

parameters

object

required

As variáveis do modelo. As chaves são o marcador literal, entre chaves duplas, como "{{1}}". Não é o índice 1 e não é o nome da variável.

As chaves vêm de variables em GET /templates/{id}. Envie {} se o modelo não tiver variáveis. Uma chave faltando é recusada com 400 INVALID_PARAMETERS: Missing required parameter: {{1}}.

Example:

{ "{{1}}": "Maria" }

sender

object

required

Quem aparece como remetente da notificação. Permite enviar em nome próprio ou em nome de um cliente. Em ambos os casos o Pombo mantém o registro de qual credencial emitiu.

Não existe remetente padrão da organização nesta API: o sender é declarado em cada envio.

Hide child attributes

sender.name

string

required

Razão social ou nome do remetente. No máximo 200 caracteres: acima disso a chamada é recusada com 400 INVALID_SENDER e a mensagem sender.name must be at most 200 characters.

Só texto simples. Os caracteres <, > e " e os caracteres de controle (quebras de linha incluídas) são recusados com 400 INVALID_SENDER e a mensagem sender.name must be plain text. O nome é reproduzido literalmente no rodapé do e-mail e no laudo, e uma quebra de linha forjaria uma segunda linha de rodapé.

Required string length: 1 - 200

sender.tax_id

string

required

CPF (11 dígitos) ou CNPJ (14 dígitos), só dígitos.

A quantidade de dígitos não basta: o documento é conferido pelo dígito verificador (MOD-11) e precisa corresponder ao tax_id_type declarado: um CNPJ declarado como CPF é recusado. A recusa é 400 INVALID_SENDER, com a mensagem sender.tax_id must be a valid CPF ou sender.tax_id must be a valid CNPJ.

Pattern: ^([0-9]{11}|[0-9]{14})$

sender.tax_id_type

enum<string>

required

Available options:

CPF,

CNPJ

sender.contact_phone

string | null

Opcional. O telefone para onde o destinatário deve responder, impresso no rodapé da mensagem. Não é o número de origem: esse é sender_phone, e o Pombo é quem o resolve.

Formato internacional, começando por +, com 10 a 15 dígitos. Fora desse formato a chamada é recusada com 400 INVALID_SENDER e a mensagem sender.contact_phone must be in format +CODE_PHONE with 10-15 digits (e.g., +5511999998888).

Ausente, a linha de contato do rodapé é omitida por inteiro: não há queda para o telefone da organização.

Pattern: ^\+[0-9]{10,15}$

Example:

"+5511999998888"

sender.contact_email

string<email> | null

Opcional. Devolvido na resposta da notificação.

recipient_phone

string

Formato internacional, começando por +. Ausente num envio de WhatsApp, a chamada é recusada com 400 e error_code igual a INVALID_RECIPIENT.

Pattern: ^\+[0-9]{10,15}$

Example:

"+5511999998888"

recipient_email

string<email>

Ausente num envio de e-mail, a chamada é recusada com 400 e error_code igual a INVALID_RECIPIENT.

Response

Repetição idempotente. O mesmo Idempotency-Key com o mesmo corpo (e, quando há anexo, o mesmo arquivo) devolve 200 com o corpo original da primeira chamada. Nenhuma notificação nova foi criada e nenhum envio foi descontado.

O 200 é o sinal de repetição: a primeira chamada devolve 201.

A notificação devolvida pelo envio.

notification_id

string

organization_id

string

A organização dona da conta e do saldo. Não confunda com sender, que é em nome de quem a notificação sai.

template_id

string

channel

enum<string>

Available options:

WHATSAPP,

EMAIL

recipient_full_name

string

recipient_tax_id

string

recipient_tax_id_type

enum<string>

Available options:

CPF,

CNPJ

recipient_phone

string | null

recipient_email

string | null

contact_id

string

O contato do destinatário no Pombo. Os contatos são unificados pelo tax_id, então o mesmo CPF devolve o mesmo contact_id nos dois canais. É por isso que dados divergentes produzem 409 CONTACT_CONFLICT.

Example:

"PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N"

line_id

string | null

A linha de WhatsApp usada no envio. null em EMAIL.

Example:

"PBD_WALN_01J9Z2Q8XK3M7WPTV6RB4CYH0N"

parameters

object

As variáveis exatamente como você as enviou, devolvidas para que o registro se descreva sozinho.

Example:

{ "{{1}}": "Maria" }

message

string

A mensagem já renderizada, com parameters aplicados ao modelo. É o artefato que o carimbo do tempo cobre. Existe só na resposta: não há campo message de envio.

content_sha256

string | null

O resumo SHA-256 da mensagem renderizada, em hexadecimal. É a impressão digital do texto que consta no laudo: o equivalente, para a mensagem, do que hash é para o anexo.

Example:

"3b1c8d6e4f2a0b9c7d5e3f1a8c6d2b0e9f7a5c3d1e8f6b4a2c0d9e7f5a3b1c8d"

message_format

string

Se message é HTML ou texto simples.

notification_status

enum<string>

O processamento interno no Pombo. Não indica entrega. Uma mensagem já lida foi observada aqui como PENDING. Para saber se a pessoa recebeu, use notification_delivery_status.

Available options:

DRAFT,

PENDING,

PROCESSING,

COMPLETED,

FAILED

notification_delivery_status

enum<string>

O campo que responde se a mensagem chegou. Caminho normal: PENDING → ENQUEUED → SENT → DELIVERED → READ.

No envio, um EMAIL foi observado em ENQUEUED e um WHATSAPP em SENT.

Nunca retrocede, e FAILED é terminal. Você pode não observar todos os estados intermediários. Em e-mail não espere READ.

Available options:

PENDING,

ENQUEUED,

SENT,

DELIVERED,

READ,

FAILED

sender

object

Quem aparece como remetente da notificação. Permite enviar em nome próprio ou em nome de um cliente. Em ambos os casos o Pombo mantém o registro de qual credencial emitiu.

Não existe remetente padrão da organização nesta API: o sender é declarado em cada envio.

Hide child attributes

sender.name

string

required

Razão social ou nome do remetente. No máximo 200 caracteres: acima disso a chamada é recusada com 400 INVALID_SENDER e a mensagem sender.name must be at most 200 characters.

Required string length: 1 - 200

sender.tax_id

string

required

CPF (11 dígitos) ou CNPJ (14 dígitos), só dígitos.

Pattern: ^([0-9]{11}|[0-9]{14})$

sender.tax_id_type

enum<string>

required

Available options:

CPF,

CNPJ

sender.contact_phone

string | null

Opcional. O telefone para onde o destinatário deve responder, impresso no rodapé da mensagem. Não é o número de origem: esse é sender_phone, e o Pombo é quem o resolve.

Ausente, a linha de contato do rodapé é omitida por inteiro: não há queda para o telefone da organização.

Pattern: ^\+[0-9]{10,15}$

Example:

"+5511999998888"

sender.contact_email

string<email> | null

Opcional. Devolvido na resposta da notificação.

sender_phone

string | null

O número de origem do WhatsApp, resolvido pelo Pombo a partir do pool de linhas. null em EMAIL. É o endereço de onde a mensagem realmente saiu, e é o que vai certificado no laudo. Não é sender.contact_phone, que é para onde o destinatário responde.

Example:

"5511952134898"

sender_email

string | null

O endereço de origem do e-mail, resolvido pelo Pombo. null em WHATSAPP. É o endereço de onde a mensagem realmente saiu, e é o que vai certificado no laudo. Não é sender.contact_email, que é para onde o destinatário responde.

Se a sua organização não tem endereço próprio verificado (o caso comum), a mensagem sai do endereço compartilhado do Pombo, e é ele que aparece aqui.

Example:

"ola@pombo.digital"

created_by_type

string

O tipo de autor do envio, que qualifica created_by_user_id.

created_by_user_id

string

O nome engana. Quando o envio parte de uma credencial de API, este campo traz o identificador da credencial, PBD_APIKEY_..., e não um identificador de usuário.

Example:

"PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N"

idempotency_key

string | null

A chave que você enviou no cabeçalho Idempotency-Key, devolvida aqui para que o registro se descreva sozinho. Só existe na resposta: no envio a chave vai no cabeçalho, nunca no corpo.

batch_id

string | null

O lote a que a notificação pertence, quando veio de um envio em massa.

batch_item_id

string | null

O item do lote correspondente a esta notificação.

created_at

string<date-time>

sent_at

string<date-time> | null

Quando o Pombo entregou a mensagem ao provedor. null até o envio ocorrer.

delivered_at

string<date-time> | null

Quando o provedor confirmou a entrega ao destinatário. null enquanto não houver confirmação.

failed_at

string<date-time> | null

Quando o envio falhou em definitivo. null quando não houve falha.

created_by_email

string | null

Sempre null quando a chamada vem de uma credencial de API.

created_by_name

string | null

O nome da credencial que emitiu a notificação.

attachments

object[]

O anexo que viajou nesta chamada, já validado, guardado e com a sua impressão digital. Vazio quando o envio não levou arquivo.

Confira aqui, sem uma segunda chamada. Como o arquivo entra na mesma requisição, o hash já existe quando o envio responde: compare-o com o resumo do arquivo que você tinha e a verificação termina aqui.

Hide child attributes

attachments.attachment_id

string

O identificador do arquivo guardado, opaco: é o mesmo que aparece no laudo, e serve para citar um anexo específico num chamado de suporte. Não há endpoint para resolvê-lo: tudo o que você precisa conferir já está nos campos ao lado.

attachments.filename

string

O nome já normalizado pelo Pombo, e o nome que o destinatário recebeu. Compare com o que você enviou: pode não ser igual.

attachments.mime_type

enum<string>

Available options:

application/pdf,

image/png,

image/jpeg

attachments.size_bytes

integer

attachments.hash

string

A impressão digital do arquivo, a mesma que consta no laudo.

Example:

"9f2c1d7a4b6e8f0c2a4d6e8f0b1c3d5e7f9a1b3c5d7e9f1a3b5c7d9e1f3a5b7c"

attachments.hash_algorithm

string

Literalmente SHA-256, com hífen e em maiúsculas. Compare a string exata.

Example:

"SHA-256"

attachments.hash_encoding

string

Example:

"hex"

Referência da API

Modelos

Notificações

Cria uma notificação extrajudicial.

Authorizations

Headers

Body

Response