> ## Documentation Index > Fetch the complete documentation index at: https://docs.superlead.app/llms.txt > Use this file to discover all available pages before exploring further. # Criar Lead > Cria um lead na sua empresa. Criar lead é sempre uma **ação explícita** — envios de mensagem nunca criam leads como efeito colateral. - O lead entra na **primeira etapa** do funil e aparece imediatamente no painel. - Telefone é **único por empresa**: se já existe um lead com o número, a resposta é `409 lead_already_exists` — recupere-o com `GET /v1/leads?phone=...` e siga normalmente (para automações, trate `409` como sucesso). - Requer funil configurado no painel (`422 funnel_not_configured` caso contrário). Veja o fluxo recomendado **buscar → criar → enviar** em [Leads](/guias/leads). ## OpenAPI ````yaml /openapi.json post /v1/leads openapi: 3.1.0 info: title: Superlead API version: 1.0.0 description: > API oficial do Superlead para envio de mensagens WhatsApp aos **seus leads**. ## Autenticação Toda chamada exige `Authorization: Bearer sk_...` (crie a chave no painel Superlead em Integrações → API). A chave é escopada à sua empresa. ## Início rápido ```bash curl -X POST https://api.superlead.app/v1/whatsapp/messages \ -H "Authorization: Bearer sk_SUACHAVE" \ -H "Idempotency-Key: pedido-8734" \ -H "Content-Type: application/json" \ -d '{"to":"+5511999999999","type":"text","text":{"body":"Olá!"}}' ``` No n8n: nó **HTTP Request**, método POST, header Authorization como acima. ## Endereçamento O campo `to` aceita **telefone E.164** (`+5511999999999`) ou **BSUID** (`BR.13491208655302741918` — o `fromUserId` entregue nos webhooks quando o contato usa username do WhatsApp; usernames nunca endereçam). O destinatário precisa ser um lead existente da sua empresa — o envio nunca cria leads. Para outreach, crie antes com `POST /v1/leads`. Use `external_id` para reconciliar com o seu sistema. ## Janela de 24h (regra da Meta) Mensagens de formato livre (text, image, ...) só são entregues se o lead falou com você nas últimas 24 horas. Fora da janela, use `type: "template"` com um template aprovado (liste-os em `GET /v1/whatsapp/templates`). Fora da janela a Meta pode rejeitar o envio na hora (`outside_24h_window`) OU aceitá-lo (201, status `accepted`) e falhá-lo de forma assíncrona segundos depois — a mensagem passa ao status `failed`. Confirme em `GET /v1/whatsapp/messages/{id}` ou pelo webhook `whatsapp.message.updated`. ## Idempotência Envie o header `Idempotency-Key` (recomendado). Retries com a mesma chave e mesmo body retornam a resposta original sem reenviar. Validade: 24h. ## Rate limit 60 requisições/min por chave (headers `X-RateLimit-*`; `429` inclui `Retry-After`). ## Status da mensagem A resposta traz o status inicial. Acompanhe `sent → delivered → read` (ou `failed`) pelos webhooks do Superlead (evento `whatsapp.message.updated`) ou por `GET /v1/whatsapp/messages/{id}`. O evento de status identifica a mensagem pelo `wamid` retornado na resposta do envio. ## Erros Envelope estável `{ "error": { "code", "message", "request_id" } }`. Trate códigos desconhecidos pelo HTTP status (novos códigos são mudança aditiva). | HTTP | code | Meaning | |---|---|---| | 400 | `invalid_request` | The request body is invalid. Check the details field and the API reference. | | 401 | `invalid_api_key` | Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. | | 404 | `lead_not_found` | No lead matches this recipient in your company. The API only messages existing leads. | | 404 | `message_not_found` | No message with this id exists in your company. | | 404 | `stage_not_found` | No funnel stage with this id exists in your company. List valid stages with GET /v1/funnel/stages. | | 409 | `idempotency_conflict` | This Idempotency-Key was already used with a different request body, or the original request is still in progress. | | 409 | `lead_already_exists` | A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages. | | 422 | `funnel_not_configured` | Your company has no funnel stages configured. Set up the funnel in the Superlead panel first. | | 422 | `no_active_connection` | Your company has no active WhatsApp connection. Connect a number in the Superlead panel first. | | 422 | `connection_expired` | Your WhatsApp connection is no longer authorized. Reconnect it in the Superlead panel. | | 422 | `channel_capability_unsupported` | Your company's WhatsApp connection type does not support this operation. | | 422 | `outside_24h_window` | Free-form messages require the lead to have messaged you within the last 24 hours. Send an approved template instead. | | 422 | `template_not_found` | Template not found. Check the exact name and language with GET /v1/whatsapp/templates. | | 422 | `template_params_invalid` | Template parameters do not match the approved template. Check count, format and language. | | 422 | `recipient_unavailable` | The recipient cannot receive this message on WhatsApp right now. | | 422 | `media_unsupported` | WhatsApp could not fetch or process the media. Check that the link is public and direct, the format is supported and the file is within the size limit for its type. | | 422 | `message_blocked` | Meta blocked this message (spam or ecosystem limits). Reduce volume to this recipient and review quality. | | 429 | `rate_limit_exceeded` | Rate limit for this API key exceeded. Retry after the time in the Retry-After header. | | 429 | `channel_rate_limit` | WhatsApp is throttling your number. Slow down and retry later. | | 502 | `channel_error` | The messaging provider returned an unexpected error. Our team was notified; retry later. | | 500 | `internal_error` | Internal error. Our team was notified; retry later. | ## Versionamento Caminho `/v1/`. Mudanças incompatíveis só em `/v2/`. Campos novos opcionais podem aparecer a qualquer momento — ignore campos desconhecidos. servers: - url: https://api.superlead.app description: Produção security: [] paths: /v1/leads: post: summary: Criar Lead description: >- Cria um lead na sua empresa. Criar lead é sempre uma **ação explícita** — envios de mensagem nunca criam leads como efeito colateral. - O lead entra na **primeira etapa** do funil e aparece imediatamente no painel. - Telefone é **único por empresa**: se já existe um lead com o número, a resposta é `409 lead_already_exists` — recupere-o com `GET /v1/leads?phone=...` e siga normalmente (para automações, trate `409` como sucesso). - Requer funil configurado no painel (`422 funnel_not_configured` caso contrário). Veja o fluxo recomendado **buscar → criar → enviar** em [Leads](/guias/leads). operationId: createLead requestBody: required: true content: application/json: schema: type: object required: - name - phone additionalProperties: false properties: name: type: string minLength: 1 maxLength: 200 description: Nome do lead, até 200 caracteres. example: João Silva phone: type: string pattern: ^\+[1-9]\d{6,14}$ description: >- Telefone em **E.164**: `+`, código do país, DDD e número (ex.: `+5511999999999`). Único por empresa. example: '+5511999999999' source: type: string minLength: 1 maxLength: 120 description: >- Origem do lead exibida no painel (ex.: `Indicação`, `Site`). Sem valor, o lead entra como `Não Rastreado`. example: Indicação channel: type: string minLength: 1 maxLength: 120 description: 'Canal de origem (ex.: `WhatsApp`, `Instagram`).' example: WhatsApp entry_point: type: string minLength: 1 maxLength: 120 description: >- Ponto de entrada da conversão (ex.: `formulario-site`, `ctwa`). example: formulario-site email: type: string format: email description: E-mail do lead. example: joao@empresa.com notes: type: string maxLength: 2000 description: Observações livres, até 2000 caracteres. example: Pediu orçamento do plano anual. utm_source: type: string maxLength: 255 description: 'Atribuição de campanha: origem (ex.: `google`, `facebook`).' example: google utm_medium: type: string maxLength: 255 description: 'Atribuição de campanha: mídia (ex.: `cpc`, `social`).' example: cpc utm_campaign: type: string maxLength: 255 description: 'Atribuição de campanha: nome da campanha.' example: lancamento-julho utm_term: type: string maxLength: 255 description: 'Atribuição de campanha: termo de busca.' example: crm whatsapp utm_content: type: string maxLength: 255 description: 'Atribuição de campanha: variação do anúncio.' example: video-a examples: minimo: summary: Mínimo (nome + telefone) value: name: João Silva phone: '+5511999999999' completo: summary: Com origem e atribuição value: name: João Silva phone: '+5511999999999' source: Meta Ads channel: WhatsApp entry_point: ctwa email: joao@empresa.com utm_source: facebook utm_medium: cpc utm_campaign: lancamento-julho responses: '201': description: Lead criado na primeira etapa do funil. content: application/json: schema: type: object properties: id: type: string description: >- Id do lead (`lead_...`). Guarde-o para editar, mover de etapa e consultar. example: lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f name: type: string description: Nome do lead. example: João Silva phone: type: string description: Telefone em E.164. example: '+5511999999999' source: type: string description: Origem do lead (ou `Não Rastreado`). example: Indicação channel: type: - string - 'null' description: Canal de origem. example: WhatsApp entry_point: type: - string - 'null' description: Ponto de entrada da conversão. example: formulario-site funnel_stage: type: - string - 'null' description: Nome da etapa em que o lead entrou (a primeira do funil). example: 1º Contato created_at: type: string format: date-time description: Data de criação (ISO 8601, UTC). example: '2026-07-08T12:00:00.000Z' example: id: lead_0b5f8a3e-1a2b-3c4d-5e6f-7a8b9c0d1e2f name: João Silva phone: '+5511999999999' source: Indicação channel: WhatsApp entry_point: formulario-site funnel_stage: 1º Contato created_at: '2026-07-08T12:00:00.000Z' '400': description: >- `invalid_request` — o body ou os parâmetros da requisição são inválidos. O campo `details` aponta cada campo com problema. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_request message: The request body is invalid. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 details: - path: to message: Required '401': description: >- `invalid_api_key` — chave de API ausente, malformada ou revogada. Envie `Authorization: Bearer sk_...`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: invalid_api_key message: >- Missing or invalid API key. Send it as 'Authorization: Bearer sk_...'. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '409': description: >- `lead_already_exists` — já existe um lead com este telefone na sua empresa. Recupere-o com `GET /v1/leads?phone=...`. Em automações, trate como sucesso. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: lead_already_exists message: >- A lead with this phone number already exists in your company. You can message it directly via POST /v1/whatsapp/messages. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '422': description: >- `funnel_not_configured` — a empresa não tem etapas de funil configuradas. Configure o funil no painel Superlead antes de criar leads pela API. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: funnel_not_configured message: >- Your company has no funnel stages configured. Set up the funnel in the Superlead panel first. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 '429': description: >- `rate_limit_exceeded` — limite de 60 requisições/min da chave excedido (aguarde o `Retry-After`). `channel_rate_limit` — o WhatsApp está limitando o seu número; reduza o ritmo. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: rate_limit_exceeded message: >- Rate limit for this API key exceeded. Retry after the time in the Retry-After header. request_id: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 security: - apiKey: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string description: >- Código estável do erro (ex.: `lead_not_found`). Novos códigos podem surgir a qualquer momento — trate códigos desconhecidos pelo HTTP status. example: lead_not_found message: type: string description: >- Descrição legível do erro, em inglês. O texto pode mudar — não faça parsing dele; use `code`. request_id: type: string description: >- Id único desta requisição. Inclua ao reportar um problema ao suporte. example: req_01J9X7K2M3N4P5Q6R7S8T9V0W1 upstream_code: type: number description: >- Código numérico original da Meta, presente quando o erro veio do WhatsApp (ex.: `131047` para fora da janela de 24h). example: 131047 details: type: array description: >- Erros de validação campo a campo. Presente em respostas `400 invalid_request`. items: type: object properties: path: type: string description: 'Caminho do campo inválido no body (ex.: `text.body`).' message: type: string description: O que está errado com o campo. securitySchemes: apiKey: type: http scheme: bearer description: >- Chave de API da sua empresa (`sk_...`). Crie no painel Superlead em **Integrações → API** e envie em toda chamada como `Authorization: Bearer sk_...`. Veja [Autenticação](/guias/autenticacao). ````