> ## Documentation Index > Fetch the complete documentation index at: https://docs.pombo.digital/llms.txt > Use this file to discover all available pages before exploring further. # Listar notificações > Lista as notificações da sua organização, da mais recente para a mais antiga. ## OpenAPI ````yaml /api-reference/openapi.yaml get /notifications openapi: 3.1.0 info: title: API do Pombo.Digital version: 1.0.0 description: > Envie notificações extrajudiciais certificadas por WhatsApp ou e-mail, acompanhe a entrega e baixe o laudo com carimbo do tempo ICP-Brasil. A credencial identifica a organização por si só: `organization_id` não é aceito em nenhuma requisição desta API. servers: - url: https://pombo.digital/api/integrations/v1 description: Produção security: - bearerAuth: [] tags: - name: Notificações description: >- Criar uma notificação extrajudicial, acompanhar a entrega e baixar o laudo. - name: Modelos description: >- Modelos de mensagem. Um envio de WhatsApp exige um modelo aprovado pela Meta. - name: Saldo description: O saldo de envios da organização. paths: /notifications: get: tags: - Notificações summary: Listar notificações description: > Lista as notificações da sua organização, da mais recente para a mais antiga. operationId: listNotifications parameters: - name: limit in: query required: false description: > Quantas notificações trazer, de 1 a 50. O padrão é 10. Um valor fora da faixa, ou que não seja um inteiro, é recusado com `400` e a mensagem `limit must be an integer from 1 through 50`. schema: type: integer minimum: 1 maximum: 50 default: 10 - name: after in: query required: false description: > O cursor da próxima página: copie o `next_cursor` da resposta anterior e repita a chamada com ele. **É um valor que você recebe, nunca um que você monta.** Precisa ser um `notification_id`, no formato `PBD_NOT_...`. Um `template_id` ou qualquer outro texto é recusado com `400` e a mensagem `after must be a valid notification cursor`. schema: type: string pattern: ^PBD_NOT_[0-9A-HJKMNP-TV-Z]{26}$ examples: - PBD_NOT_01J9Z2Q8XK3M7WPTV6RB4CYH0N - name: channel in: query required: false description: > Traz só as notificações do canal informado. **A caixa não importa:** `whatsapp`, `WhatsApp` e `WHATSAPP` filtram o mesmo canal. A resposta continua devolvendo `channel` em maiúsculas, que é como o canal fica gravado em uma notificação. Em `GET /templates` o mesmo parâmetro só aceita minúsculas. A diferença acompanha o que cada registro guarda. Um valor fora dos dois canais é recusado com `400`. schema: type: string enum: - whatsapp - email responses: '200': description: > Uma página de notificações. Serve para saber o que saiu, não para acompanhar uma entrega: não há filtro por status e não há como pedir as mais novas que um cursor. Sem cursor, a primeira página é sempre a mais recente. content: application/json: schema: $ref: '#/components/schemas/NotificationList' examples: primeira_pagina: summary: Primeira página, com mais páginas a seguir value: data: - notification_id: PBD_NOT_01J9Z2Q8XK3M7WPTV6RB4CYH0N organization_id: PBD_ORG_01J8A1B2C3D4E5F6G7H8J9K0LM template_id: PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0N channel: WHATSAPP recipient_full_name: Maria Silva recipient_tax_id: '12345678901' recipient_tax_id_type: CPF recipient_phone: '+5511999998888' recipient_email: null contact_id: PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N line_id: PBD_WALN_01J9Z2Q8XK3M7WPTV6RB4CYH0N parameters: '{{1}}': Maria message: Prezada Maria, consta débito de R$ 1.200,00. message_format: text notification_status: PENDING notification_delivery_status: READ sender: name: Vega Cobranças LTDA tax_id: '12345678000199' tax_id_type: CNPJ sender_phone: '5511952134898' sender_email: null created_by_user_id: PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N idempotency_key: cobranca-2026-08-31-0002 created_at: '2026-08-27T14:03:11.482Z' - notification_id: PBD_NOT_01J9Z2Q8XK3M7WPTV6RB4CYG9M organization_id: PBD_ORG_01J8A1B2C3D4E5F6G7H8J9K0LM template_id: PBD_TPL_01J9Z2Q8XK3M7WPTV6RB4CYH0P channel: EMAIL recipient_full_name: João Souza recipient_tax_id: '98765432100' recipient_tax_id_type: CPF recipient_phone: null recipient_email: joao@exemplo.com.br contact_id: PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYG9L line_id: null parameters: '{{1}}': João message:

Prezado João, consta débito em aberto.

message_format: html notification_status: PENDING notification_delivery_status: ENQUEUED sender: name: Vega Cobranças LTDA tax_id: '12345678000199' tax_id_type: CNPJ sender_phone: null sender_email: ola@pombo.digital created_by_user_id: PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N idempotency_key: null created_at: '2026-08-27T13:58:02.117Z' has_more: true next_cursor: PBD_NOT_01J9Z2Q8XK3M7WPTV6RB4CYG9M ultima_pagina: summary: Última página value: data: [] has_more: false next_cursor: null '400': $ref: '#/components/responses/NotificationListBadRequest' '401': $ref: '#/components/responses/Unauthorized' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalError' components: schemas: NotificationList: type: object description: > Uma página de notificações. A paginação é por cursor: não existe número de página e não existe total. Para avançar, repita a chamada com `after` igual ao `next_cursor` que veio aqui, e pare quando `has_more` for `false`. required: - data - has_more - next_cursor properties: data: type: array description: > As notificações da página, da mais recente para a mais antiga. Vem vazio quando não há nenhuma. Cada item é a notificação sem `attachments` e sem `events`: esses dois só aparecem em `GET /notifications/{id}`. Cada item traz a `message` já renderizada e os `parameters` como você os enviou, então uma página carrega dados pessoais do destinatário. items: $ref: '#/components/schemas/Notification' has_more: type: boolean description: Se existe ao menos mais uma página depois desta. next_cursor: type: - string - 'null' description: > O `notification_id` que a próxima chamada deve mandar em `after`. `null` quando `has_more` é `false`. **Repasse este valor como ele veio.** Ele não é montado pelo cliente. examples: - PBD_NOT_01J9Z2Q8XK3M7WPTV6RB4CYH0N Notification: type: object description: > Os campos comuns a uma notificação. O envio e a consulta devolvem esta base com acréscimos: os dois acrescentam `attachments`, porque o arquivo viaja no próprio envio, e a consulta acrescenta `events`, que só existem depois. properties: notification_id: type: string organization_id: type: string description: >- 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: type: string channel: type: string enum: - WHATSAPP - EMAIL recipient_full_name: type: string recipient_tax_id: type: string recipient_tax_id_type: type: string enum: - CPF - CNPJ recipient_phone: type: - string - 'null' recipient_email: type: - string - 'null' contact_id: type: string description: > 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`. examples: - PBD_CNT_01J9Z2Q8XK3M7WPTV6RB4CYH0N line_id: type: - string - 'null' description: A linha de WhatsApp usada no envio. `null` em `EMAIL`. examples: - PBD_WALN_01J9Z2Q8XK3M7WPTV6RB4CYH0N parameters: type: object additionalProperties: true description: > 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. examples: - '{{1}}': Maria message: type: string description: > 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: type: - string - 'null' description: > 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. examples: - 3b1c8d6e4f2a0b9c7d5e3f1a8c6d2b0e9f7a5c3d1e8f6b4a2c0d9e7f5a3b1c8d message_format: type: string enum: - html - text description: Se `message` é HTML ou texto simples. Sempre em minúsculas. notification_status: type: string enum: - DRAFT - PENDING - PROCESSING - COMPLETED - FAILED description: > 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`. notification_delivery_status: $ref: '#/components/schemas/NotificationDeliveryStatus' sender: $ref: '#/components/schemas/SenderResponse' sender_phone: type: - string - 'null' description: > 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. examples: - '5511952134898' sender_email: type: - string - 'null' description: > 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. examples: - ola@pombo.digital created_by_type: type: string enum: - api_key - user description: > 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. created_by_user_id: type: string description: > **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. examples: - PBD_APIKEY_01J9Z2Q8XK3M7WPTV6RB4CYH0N idempotency_key: type: - string - 'null' description: > 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: type: - string - 'null' description: >- O lote a que a notificação pertence, quando veio de um envio em massa. batch_item_id: type: - string - 'null' description: O item do lote correspondente a esta notificação. created_at: type: string format: date-time sent_at: type: - string - 'null' format: date-time description: >- Quando o Pombo entregou a mensagem ao provedor. `null` até o envio ocorrer. delivered_at: type: - string - 'null' format: date-time description: >- Quando o provedor confirmou a entrega ao destinatário. `null` enquanto não houver confirmação. failed_at: type: - string - 'null' format: date-time description: Quando o envio falhou em definitivo. `null` quando não houve falha. Error: type: object description: > O envelope de erro, com quatro campos. **Ramifique pelo status HTTP e por `error_code`. Nunca por `code`.** O `code` vale `10000 + http_code` em um caminho e uma string arbitrária em outro, então não acrescenta nada ao status e muda de tipo entre operações vizinhas. required: - message properties: code: description: > **Não ramifique por este campo.** O tipo muda entre operações vizinhas: um `404` de modelo traz `10404` e um `404` de notificação traz `"NOT_FOUND"`. Para tratar erros em código, use o status HTTP. oneOf: - title: Número, na validação genérica type: integer description: >- `10000 + http_code`. Um `400` genérico traz `10400`, um `404` traz `10404`. examples: - 10400 - title: Texto, nos erros específicos type: string description: Um identificador do erro, como os listados em Erros. examples: - IDEMPOTENCY_KEY_REUSED http_code: type: integer description: > **Opcional.** O status HTTP repetido no corpo. Presente quando o erro é devolvido diretamente, ausente quando é lançado e tratado pelo tratador geral. Nunca exija este campo no cliente. message: type: string description: >- Descrição da falha, para diagnóstico. Em inglês ou em português. Não é estável. error_code: type: string enum: - MISSING_REQUIRED_FIELD - INVALID_SENDER - ORGANIZATION_ID_FORBIDDEN - INVALID_RECIPIENT - TEMPLATE_CONSTANT_FORBIDDEN - FILE_TRANSFER_NOT_AVAILABLE_ON_THIS_LANE - IDEMPOTENCY_KEY_REUSED description: > O campo a usar para ramificar. **Opcional na prática:** alguns `400` igualmente específicos não o trazem, como o de `recipient_tax_id_type` fora do enum e o de `Idempotency-Key` mal formado. Quando estiver ausente, use o status HTTP. InternalError: type: object description: O corpo do `500` é reduzido e **não** traz `http_code`. properties: code: type: string examples: - INTERNAL_ERROR message: type: string examples: - Internal Server Error request_id: type: string description: > O mesmo valor do cabeçalho `x-request-id`. **Registre-o:** é por ele que o suporte encontra a requisição exata. examples: - req_01M1C5ZKGBGRNW6QHXTP2EM7Y7 NotificationDeliveryStatus: type: string enum: - PENDING - ENQUEUED - SENT - DELIVERED - READ - FAILED description: > **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`. SenderResponse: type: object description: > 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. properties: name: type: string description: O nome declarado no envio. tax_id: type: string description: Apenas dígitos, sem pontuação. tax_id_type: type: string enum: - CPF - CNPJ responses: NotificationListBadRequest: description: > Parâmetro de consulta inválido. Repetir sem alterar nada devolve o mesmo erro. content: application/json: schema: $ref: '#/components/schemas/Error' examples: parametro_nao_aceito: summary: 'Sem error_code: parâmetro fora dos três aceitos' description: > A listagem aceita `limit`, `after` e `channel`, e recusa qualquer outro nome. `status`, `template_id`, `q` e `page` caem aqui. value: code: 10400 http_code: 400 message: 'Invalid request: Unsupported query parameter: status' limite_invalido: summary: 'Sem error_code: limit fora da faixa' value: code: 10400 http_code: 400 message: 'Invalid request: limit must be an integer from 1 through 50' cursor_invalido: summary: 'Sem error_code: after que não é um notification_id' description: > O cursor desta listagem é um `PBD_NOT_...`. O cursor de `GET /templates` é recusado aqui. value: code: 10400 http_code: 400 message: 'Invalid request: after must be a valid notification cursor' canal_invalido: summary: 'Sem error_code: channel fora dos dois canais' value: code: 10400 http_code: 400 message: 'Invalid request: channel must be either whatsapp or email' organization_id_proibido: summary: organization_id enviado na consulta value: code: 10400 http_code: 400 message: >- Invalid request: organization_id must not be sent as a query parameter: it is taken from the API key error_code: ORGANIZATION_ID_FORBIDDEN Unauthorized: description: > Credencial ausente, inválida ou revogada. A resposta é **idêntica** nos três casos: o Pombo não informa qual deles ocorreu, para que não se possa descobrir por tentativa quais credenciais já existiram. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalida: summary: Credencial não aceita value: code: 10401 http_code: 401 message: Invalid API key TooManyRequests: description: > Limite de requisições excedido. São três contagens independentes, em janelas de um minuto: 50 por credencial, 200 por organização, 300 por IP. **Espere o que o `Retry-After` manda esperar**, em segundos. Os cabeçalhos `RateLimit-Limit`, `RateLimit-Remaining` e `RateLimit-Reset` vêm em toda resposta, não só no `429`. headers: Retry-After: description: Quantos segundos esperar antes de repetir. schema: type: integer examples: - 43 RateLimit-Limit: description: O teto da janela. schema: type: integer examples: - 200 RateLimit-Remaining: description: Quantas requisições ainda cabem na janela. schema: type: integer examples: - 0 RateLimit-Reset: description: Quantos segundos faltam para a janela virar. schema: type: integer examples: - 43 content: application/json: schema: $ref: '#/components/schemas/Error' examples: limite: summary: Limite excedido value: code: RATE_LIMIT_EXCEEDED http_code: 429 message: Too many requests. Please try again later. InternalError: description: > Erro interno. Em `POST /notifications`, um `500` **não garante que nada foi enviado**: consulte antes de repetir. content: application/json: schema: $ref: '#/components/schemas/InternalError' examples: interno: summary: Erro interno value: code: INTERNAL_ERROR message: Internal Server Error request_id: req_01M1C5ZKGBGRNW6QHXTP2EM7Y7 securitySchemes: bearerAuth: type: http scheme: bearer description: > 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. ````