> ## Documentation Index > Fetch the complete documentation index at: https://docs.crmspark.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Estimar tamanho do público-alvo > Calcula quantos chats corresponderiam aos filtros informados, sem criar campanha. ## OpenAPI ````yaml /openapi/gateway.json post /v1/campaigns/audience-preview openapi: 3.0.0 info: title: Spark description: >- Documentação da API pública do Spark CRM. Respostas de erro usam `{ statusCode, code, message }`; trate erros pelo campo `code` (veja catálogo completo abaixo). ## Erros da API Todas as respostas de erro seguem o formato `{ statusCode, code, message }`. O campo **`code`** é estável entre versões — trate erros pelo código, não pela mensagem. | Código | HTTP | Descrição | | --- | ---: | --- | | `API_KEY_MISSING` | 401 | Cabeçalho `X-API-Key` ausente. Inclua a chave em todas as requisições autenticadas. | | `API_KEY_INVALID` | 401 | Prefixo ou valor da API Key não reconhecido. Verifique se copiou a chave correta do painel. | | `API_KEY_WRONG_TYPE` | 401 | O tipo da chave (pública ou privada) não é aceito neste endpoint. | | `DEVELOPERS_DISABLED` | 401 | Habilite o ambiente de desenvolvedores no painel antes de usar a API. | | `SUBSCRIPTION_INACTIVE` | 403 | O tenant não possui plano ativo ou a assinatura está suspensa/cancelada. | | `LEAD_LIMIT_EXCEEDED` | 403 | A operação criaria leads além do limite do plano atual. Faça upgrade ou remova leads. | | `FORM_INACTIVE` | 403 | O formulário existe, mas está desativado e não pode ser exibido nem receber envios. | | `RESOURCE_ACCESS_DENIED` | 403 | O recurso pertence a outro tenant ou a chave não tem escopo para lê-lo. | | `ENTRYPOINT_NOT_FOUND` | 404 | Nenhum entrypoint com o ID informado foi encontrado para o tenant autenticado. | | `FORM_NOT_FOUND` | 404 | Nenhum formulário com o ID público informado foi encontrado para o tenant autenticado. | | `CHAT_NOT_FOUND` | 404 | Nenhum chat com o ID informado foi encontrado para o tenant autenticado. | | `RESOURCE_NOT_FOUND` | 404 | O recurso solicitado não existe ou não está acessível para o tenant autenticado. | | `FORM_ALREADY_SUBMITTED` | 409 | Cada telefone pode enviar apenas uma resposta por formulário. | | `VALIDATION_ERROR` | 400 | Corpo, query ou parâmetros não passaram na validação de schema. | | `INVALID_PHONE` | 400 | O telefone informado não pôde ser normalizado para E.164. | | `ENTRYPOINT_PLATFORM_UNSUPPORTED` | 400 | O entrypoint informado pertence a uma plataforma não suportada pela operação. | | `PLATFORM_UNSUPPORTED` | 400 | Valor de filtro `platform` inválido ou não suportado. | | `FORM_MISSING_ENTRYPOINTS` | 400 | O formulário não possui entrypoints de destino configurados para receber leads. | | `FORM_INVALID_ANSWERS` | 400 | Perguntas ausentes, duplicadas, desconhecidas ou com opções inválidas. | | `FORM_INVALID_DESTINATION` | 400 | Um ou mais entrypoints configurados no formulário são inválidos ou inacessíveis. | | `MEDIA_UPLOAD_EMPTY` | 400 | O upload multipart não incluiu nenhum arquivo. | | `MEDIA_UPLOAD_TOO_MANY_FILES` | 400 | Mais arquivos foram enviados do que o permitido por requisição. | | `MEDIA_FILE_TOO_LARGE` | 400 | Um ou mais arquivos ultrapassam o limite de tamanho. | | `MEDIA_INVALID_FORMAT` | 400 | O tipo MIME ou conteúdo do arquivo não é aceito para upload de mídia. | | `INVALID_REQUEST` | 400 | A combinação de campos ou parâmetros da requisição não é permitida. | | `UNPROCESSABLE_REQUEST` | 422 | A requisição está bem formada, mas não pode ser processada no estado atual. | | `MESSAGE_CAMPAIGN_NOT_ALLOWED` | 422 | O corpo da mensagem referencia campanha, o que não é permitido na API pública. | | `CAMPAIGN_NOT_FOUND` | 404 | Nenhuma campanha com o ID informado foi encontrada para o tenant autenticado. | | `CAMPAIGN_NAME_ALREADY_EXISTS` | 400 | O nome da campanha deve ser único dentro da organização. | | `CAMPAIGN_TEMPLATE_NOT_FOUND` | 404 | O templateId informado não existe ou não pertence ao tenant autenticado. | | `CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH` | 400 | Templates oficiais só podem ser usados em WhatsApp Business ou Instagram. | | `CAMPAIGN_INVALID_FILTERS` | 422 | Um ou mais filtros possuem campo, operador ou valor incompatível. | | `CAMPAIGN_NOT_DRAFT` | 422 | A campanha já foi iniciada, concluída ou cancelada. | | `CAMPAIGN_ALREADY_PROCESSING` | 422 | Aguarde a conclusão ou cancele a execução atual antes de iniciar novamente. | | `CAMPAIGN_MISSING_COMMON_VARIABLES` | 400 | Informe commonVariables com as chaves var1, var2, etc. exigidas pelo template. | | `CAMPAIGN_SIZE_LIMIT_EXCEEDED` | 422 | Reduza o público-alvo ou ajuste os filtros antes de iniciar. | | `MESSAGE_TEMPLATE_NOT_FOUND` | 404 | Nenhum modelo de mensagem com o ID informado foi encontrado. | | `RATE_LIMIT_EXCEEDED` | 429 | Muitas requisições em curto intervalo. Aguarde e tente novamente. | | `INTERNAL_ERROR` | 500 | Falha inesperada no servidor. Se persistir, contate o suporte. | Schema: [`PublicApiErrorResponse`](#/components/schemas/PublicApiErrorResponse). version: '1.0' contact: {} servers: - url: https://gateway.crmspark.com.br description: Oficial security: [] tags: [] paths: /v1/campaigns/audience-preview: post: tags: - Campaigns summary: Estimar tamanho do público-alvo description: >- Calcula quantos chats corresponderiam aos filtros informados, sem criar campanha. operationId: campaigns_previewAudience_v1 parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AudiencePreviewBodyDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AudiencePreviewResponseSchema' '400': description: >- - `CAMPAIGN_NAME_ALREADY_EXISTS` (400): O nome da campanha deve ser único dentro da organização. - `CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH` (400): Templates oficiais só podem ser usados em WhatsApp Business ou Instagram. - `CAMPAIGN_MISSING_COMMON_VARIABLES` (400): Informe commonVariables com as chaves var1, var2, etc. exigidas pelo template. - `VALIDATION_ERROR` (400): Corpo, query ou parâmetros não passaram na validação de schema. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: CAMPAIGN_NAME_ALREADY_EXISTS: value: statusCode: 400 code: CAMPAIGN_NAME_ALREADY_EXISTS message: Já existe uma campanha com esse nome. CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH: value: statusCode: 400 code: CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH message: Template incompatível com a plataforma selecionada. CAMPAIGN_MISSING_COMMON_VARIABLES: value: statusCode: 400 code: CAMPAIGN_MISSING_COMMON_VARIABLES message: Variáveis manuais do template não foram preenchidas. VALIDATION_ERROR: value: statusCode: 400 code: VALIDATION_ERROR message: Dados da requisição inválidos. '401': description: >- - `API_KEY_MISSING` (401): Cabeçalho `X-API-Key` ausente. Inclua a chave em todas as requisições autenticadas. - `API_KEY_INVALID` (401): Prefixo ou valor da API Key não reconhecido. Verifique se copiou a chave correta do painel. - `API_KEY_WRONG_TYPE` (401): O tipo da chave (pública ou privada) não é aceito neste endpoint. - `DEVELOPERS_DISABLED` (401): Habilite o ambiente de desenvolvedores no painel antes de usar a API. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: API_KEY_MISSING: value: statusCode: 401 code: API_KEY_MISSING message: API Key não fornecida. API_KEY_INVALID: value: statusCode: 401 code: API_KEY_INVALID message: API Key inválida. API_KEY_WRONG_TYPE: value: statusCode: 401 code: API_KEY_WRONG_TYPE message: API Key não autorizada a acessar este recurso. DEVELOPERS_DISABLED: value: statusCode: 401 code: DEVELOPERS_DISABLED message: >- O ambiente de desenvolvedores não está habilitado para este tenant. '403': description: >- - `SUBSCRIPTION_INACTIVE` (403): O tenant não possui plano ativo ou a assinatura está suspensa/cancelada. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: SUBSCRIPTION_INACTIVE: value: statusCode: 403 code: SUBSCRIPTION_INACTIVE message: Sua organização não possui uma assinatura ativa. '404': description: >- - `CAMPAIGN_NOT_FOUND` (404): Nenhuma campanha com o ID informado foi encontrada para o tenant autenticado. - `CAMPAIGN_TEMPLATE_NOT_FOUND` (404): O templateId informado não existe ou não pertence ao tenant autenticado. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: CAMPAIGN_NOT_FOUND: value: statusCode: 404 code: CAMPAIGN_NOT_FOUND message: Campanha não encontrada. CAMPAIGN_TEMPLATE_NOT_FOUND: value: statusCode: 404 code: CAMPAIGN_TEMPLATE_NOT_FOUND message: Modelo de mensagem não encontrado. '422': description: >- - `CAMPAIGN_INVALID_FILTERS` (422): Um ou mais filtros possuem campo, operador ou valor incompatível. - `CAMPAIGN_NOT_DRAFT` (422): A campanha já foi iniciada, concluída ou cancelada. - `CAMPAIGN_ALREADY_PROCESSING` (422): Aguarde a conclusão ou cancele a execução atual antes de iniciar novamente. - `CAMPAIGN_SIZE_LIMIT_EXCEEDED` (422): Reduza o público-alvo ou ajuste os filtros antes de iniciar. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: CAMPAIGN_INVALID_FILTERS: value: statusCode: 422 code: CAMPAIGN_INVALID_FILTERS message: Filtros de público-alvo inválidos. CAMPAIGN_NOT_DRAFT: value: statusCode: 422 code: CAMPAIGN_NOT_DRAFT message: Apenas campanhas em rascunho podem ser iniciadas. CAMPAIGN_ALREADY_PROCESSING: value: statusCode: 422 code: CAMPAIGN_ALREADY_PROCESSING message: Campanha já possui uma execução em andamento. CAMPAIGN_SIZE_LIMIT_EXCEEDED: value: statusCode: 422 code: CAMPAIGN_SIZE_LIMIT_EXCEEDED message: >- Campanha excede o limite de destinatários para a plataforma. '429': description: >- - `RATE_LIMIT_EXCEEDED` (429): Muitas requisições em curto intervalo. Aguarde e tente novamente. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponse' examples: RATE_LIMIT_EXCEEDED: value: statusCode: 429 code: RATE_LIMIT_EXCEEDED message: Limite de requisições excedido. security: - api-key: [] components: schemas: AudiencePreviewBodyDto: type: object properties: filters: type: array description: >- Grupos de filtros de público-alvo. Para restringir por canal, inclua chat.platform. items: type: object properties: combinator: type: string enum: - and - or description: Combina as condições dentro deste grupo. statements: minItems: 1 type: array items: type: object properties: field: type: string enum: - chat.platform - chat.status - chat.monetization - chat.entrypointId - chat.funnelStepId - chat.trackingLinkId - chat.isGroupChat - chat.isAnswered - chat.needsHumanAttention - chat.attentionReason - chat.tagIds - chat.assignedUserId - chat.virtual.participants-count - chat.virtual.dm-participant.contact - chat.virtual.dm-participant.birthDate - chat.virtual.lastMessageAt - chat.virtual.lastUpdateAt description: >- Campo do chat usado na condição. Consulte GET /v1/campaigns/filters/schema para detalhes. operator: type: string enum: - equals - not-equals - contains - not-contains - in - not-in - exists - not-exists - starts-with - ends-with - not-starts-with - not-ends-with - greater-than - less-than - greater-than-or-equal - less-than-or-equal - between - not-between - has-any - has-all - has-none description: >- Operador de comparação. Deve ser compatível com o tipo do campo. value: description: >- Valor principal da condição. Datas em ISO 8601. IDs semânticos como string ou array de strings. anyOf: - type: string - type: number - type: boolean - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: array items: type: string - type: array items: type: number - type: array items: type: boolean - type: array items: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ value2: description: >- Segundo valor para operadores between/not-between ou intervalos. anyOf: - type: string - type: number - type: boolean - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: array items: type: string - type: array items: type: number - type: array items: type: boolean - type: array items: type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ required: - field - operator required: - combinator - statements additionalProperties: false AudiencePreviewResponseSchema: type: object properties: estimatedCount: type: integer minimum: 0 maximum: 9007199254740991 description: Quantidade estimada de chats que receberiam o disparo. required: - estimatedCount additionalProperties: false PublicApiErrorResponse: type: object required: - statusCode - code - message properties: statusCode: type: integer description: Código HTTP da resposta. example: 400 code: type: string description: >- Código estável e legível por máquina. Use este campo — não parseie `message` — para tratar erros no cliente. enum: - API_KEY_MISSING - API_KEY_INVALID - API_KEY_WRONG_TYPE - DEVELOPERS_DISABLED - SUBSCRIPTION_INACTIVE - LEAD_LIMIT_EXCEEDED - FORM_INACTIVE - RESOURCE_ACCESS_DENIED - ENTRYPOINT_NOT_FOUND - FORM_NOT_FOUND - CHAT_NOT_FOUND - RESOURCE_NOT_FOUND - FORM_ALREADY_SUBMITTED - VALIDATION_ERROR - INVALID_PHONE - ENTRYPOINT_PLATFORM_UNSUPPORTED - PLATFORM_UNSUPPORTED - FORM_MISSING_ENTRYPOINTS - FORM_INVALID_ANSWERS - FORM_INVALID_DESTINATION - MEDIA_UPLOAD_EMPTY - MEDIA_UPLOAD_TOO_MANY_FILES - MEDIA_FILE_TOO_LARGE - MEDIA_INVALID_FORMAT - INVALID_REQUEST - UNPROCESSABLE_REQUEST - MESSAGE_CAMPAIGN_NOT_ALLOWED - CAMPAIGN_NOT_FOUND - CAMPAIGN_NAME_ALREADY_EXISTS - CAMPAIGN_TEMPLATE_NOT_FOUND - CAMPAIGN_TEMPLATE_PLATFORM_MISMATCH - CAMPAIGN_INVALID_FILTERS - CAMPAIGN_NOT_DRAFT - CAMPAIGN_ALREADY_PROCESSING - CAMPAIGN_MISSING_COMMON_VARIABLES - CAMPAIGN_SIZE_LIMIT_EXCEEDED - MESSAGE_TEMPLATE_NOT_FOUND - RATE_LIMIT_EXCEEDED - INTERNAL_ERROR message: type: string description: Mensagem legível em português, útil para logs e exibição ao usuário. securitySchemes: api-key: type: apiKey in: header name: X-API-Key ````