Skip to main content
POST

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

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

​
template_id
string
required

O modelo a usar. Em WhatsApp precisa estar APPROVED.

Example:

"PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0N"

​
channel
enum<string>
required

Em maiúsculas. Qualquer outro valor é recusado com 400 Invalid request: channel must be WHATSAPP or EMAIL.

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}}.

Os marcadores do rodapé do remetente não estão entre elas e não devem ser enviados. São as três últimas variáveis do modelo, chamadas __sender_name, __sender_tax_id e __sender_phone, e o Pombo as preenche a partir do sender. Mandar o marcador de qualquer uma delas em parameters faz a chamada ser recusada.

Example:
​
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.

contact_phone e contact_email são independentes: declare um, o outro ou os dois. Nenhum dos dois é obrigatório sozinho, mas em WhatsApp, num modelo que carrega o rodapé do remetente, pelo menos um dos dois precisa estar presente, e um envio que não declara nenhum é recusado. Em e-mail nada muda: o rodapé é montado no momento do envio e simplesmente omite a linha de contato.

​
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

O registro do que foi substituído na mensagem: as variáveis que você enviou mais os valores do rodapé do remetente que o Pombo preencheu a partir do sender. É por isso que o registro se descreve sozinho.

Não copie este mapa para um envio novo. Os três valores do rodapé não são seus para enviar, e a chamada é recusada. Reaproveite apenas as chaves que estão em variables do modelo.

Example:
​
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
enum<string>

Se message é HTML ou texto simples. Sempre em minúsculas.

Available options:
html,
text
​
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

O remetente como a notificação o devolve. São os dados que identificam a parte no laudo.

Os contatos de resposta não voltam aqui. Eles são declarados no envio e entregues no rodapé da mensagem, e não ficam guardados em nenhuma coluna 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
enum<string>

Quem criou a notificação: api_key quando ela veio desta API, user quando alguém a criou pelo painel.

É o campo que qualifica created_by_user_id, e o único jeito correto de saber o que ele traz. Não deduza pelo formato do identificador.

Available options:
api_key,
user
​
created_by_user_id
string

O nome engana. Quando created_by_type é api_key, este campo traz o identificador da credencial que fez o envio, PBD_APIKEY_..., e não um identificador de usuário. Com mais de uma credencial, é assim que você sabe qual delas enviou o quê.

Quando created_by_type é user, a notificação foi criada no painel e o campo traz o identificador interno de quem a criou, PBD_USR_.... É opaco de propósito: o nome e o e-mail dessa pessoa não são devolvidos por esta API.

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.

​
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.