{
  "info": {
    "_postman_id": "falefacil-chat-api-v1",
    "name": "Fale Fácil Chat — API v1.1",
    "description": "Coleção completa da API de integração WhatsApp da Fale Fácil Chat.\n\n**Base URL:** `https://b24.falefacilchat.com.br/api.php`\n\n**Autenticação:** Todas as requisições exigem o header `X-Api-Key` com sua chave de API.\n\n**Como usar:**\n1. Importe esta coleção no Postman\n2. Vá em **Variables** e substitua `{{api_key}}` pela sua chave real\n3. Ajuste `{{to}}` com o número de destino\n4. Execute as requisições\n\n**Provedores suportados:** WAPI e Meta Cloud API (detectado automaticamente pela chave).\n\n> Templates (`list_templates`, `send_template`) são exclusivos de conexões Meta.",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://b24.falefacilchat.com.br/api.php",
      "type": "string",
      "description": "URL base da API"
    },
    {
      "key": "api_key",
      "value": "SUBSTITUA_PELA_SUA_CHAVE",
      "type": "string",
      "description": "Sua API Key (visível no painel após geração)"
    },
    {
      "key": "to",
      "value": "5511999990000",
      "type": "string",
      "description": "Número de destino com DDI (apenas dígitos)"
    },
    {
      "key": "media_url_image",
      "value": "https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/280px-PNG_transparency_demonstration_1.png",
      "type": "string",
      "description": "URL de imagem para testes"
    },
    {
      "key": "media_url_document",
      "value": "https://www.w3.org/WAI/WCAG21/Techniques/pdf/pdf-sample.pdf",
      "type": "string",
      "description": "URL de documento PDF para testes"
    },
    {
      "key": "media_url_audio",
      "value": "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
      "type": "string",
      "description": "URL de áudio para testes (idealmente OGG Opus)"
    },
    {
      "key": "template_name",
      "value": "nome_do_seu_template",
      "type": "string",
      "description": "Nome exato do template aprovado no WhatsApp Business Manager"
    },
    {
      "key": "template_lang",
      "value": "pt_BR",
      "type": "string",
      "description": "Idioma do template (pt_BR, en_US, es...)"
    },
    {
      "key": "transfer_id",
      "value": "1",
      "type": "string",
      "description": "ID do usuário ou fila Bitrix24 para transferência de atendimento"
    }
  ],
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-Api-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{api_key}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "item": [

    {
      "name": "📊 Conexão",
      "item": [

        {
          "name": "Status da conexão",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" }
            ],
            "url": {
              "raw": "{{base_url}}?action=status",
              "host": ["{{base_url}}"],
              "query": [{ "key": "action", "value": "status" }]
            },
            "description": "Verifica se o WhatsApp está conectado.\n\n**WAPI:** consulta o servidor em tempo real e atualiza o banco.\n**Meta:** verifica o status registrado na conexão."
          },
          "response": [
            {
              "name": "200 — Conectado",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"connection_id\": 12,\n    \"provider\": \"wapi\",\n    \"phone\": \"5511999990000\",\n    \"internal_id\": \"Comercial 01\",\n    \"status\": \"connected\"\n  }\n}"
            },
            {
              "name": "200 — Desconectado",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"connection_id\": 12,\n    \"provider\": \"wapi\",\n    \"phone\": \"5511999990000\",\n    \"internal_id\": \"Comercial 01\",\n    \"status\": \"disconnected\"\n  }\n}"
            }
          ]
        },

        {
          "name": "Listar conexões",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" }
            ],
            "url": {
              "raw": "{{base_url}}?action=list_connections",
              "host": ["{{base_url}}"],
              "query": [{ "key": "action", "value": "list_connections" }]
            },
            "description": "Lista todas as conexões vinculadas ao cliente da API Key. Útil para sistemas multi-linha."
          },
          "response": [
            {
              "name": "200 — Lista de conexões",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"total\": 2,\n    \"connections\": [\n      {\n        \"id\": 12,\n        \"phone\": \"5511999990000\",\n        \"internal_id\": \"Comercial 01\",\n        \"provider\": \"wapi\",\n        \"status\": \"active\",\n        \"paid_until\": \"2025-12-31\",\n        \"expired\": false\n      },\n      {\n        \"id\": 15,\n        \"phone\": \"5511888880000\",\n        \"internal_id\": \"Suporte\",\n        \"provider\": \"meta\",\n        \"status\": \"active\",\n        \"paid_until\": \"2025-06-30\",\n        \"expired\": false\n      }\n    ]\n  }\n}"
            }
          ]
        }

      ]
    },

    {
      "name": "💬 Enviar mensagem",
      "item": [

        {
          "name": "Enviar texto",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_text\",\n    \"to\": \"{{to}}\",\n    \"message\": \"Olá! Mensagem de teste enviada via *API*. ✓\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia uma mensagem de texto.\n\n**Formatação WhatsApp (WAPI):**\n- `*negrito*`\n- `_itálico_`\n- `~tachado~`\n- ` ```código``` `\n\nPara Meta, o texto é enviado sem formatação."
          },
          "response": [
            {
              "name": "200 — Enviado",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"message_id\": \"3EB0A12345ABCDEF\",\n    \"to\": \"5511999990000\"\n  }\n}"
            }
          ]
        },

        {
          "name": "Enviar texto + registrar no Bitrix24",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_text\",\n    \"to\": \"{{to}}\",\n    \"message\": \"Seu pedido *#1234* foi confirmado e será entregue em até 3 dias úteis. ✓\",\n    \"sendtobitrix24\": true\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia texto e registra a mensagem na conversa do Bitrix24 (apenas WAPI).\n\nO `sendtobitrix24: true` faz com que a mensagem apareça no histórico da conversa do Bitrix como mensagem enviada pelo número WhatsApp."
          },
          "response": []
        }

      ]
    },

    {
      "name": "📎 Enviar mídia",
      "item": [

        {
          "name": "Enviar imagem",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_media\",\n    \"to\": \"{{to}}\",\n    \"type\": \"image\",\n    \"url\": \"{{media_url_image}}\",\n    \"caption\": \"Confira nosso produto! 🛍️\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia uma imagem com legenda opcional.\n\nFormatos: jpg, jpeg, png, gif, webp"
          },
          "response": [
            {
              "name": "200 — Imagem enviada",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"message_id\": \"3EB0A12345ABCDEF\",\n    \"to\": \"5511999990000\",\n    \"type\": \"image\"\n  }\n}"
            }
          ]
        },

        {
          "name": "Enviar vídeo",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_media\",\n    \"to\": \"{{to}}\",\n    \"type\": \"video\",\n    \"url\": \"https://exemplo.com/video.mp4\",\n    \"caption\": \"Assista ao nosso tutorial!\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um vídeo com legenda opcional.\n\nFormatos: mp4, avi, mov\nLimite: 20 MB"
          },
          "response": []
        },

        {
          "name": "Enviar documento (PDF)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_media\",\n    \"to\": \"{{to}}\",\n    \"type\": \"document\",\n    \"url\": \"{{media_url_document}}\",\n    \"caption\": \"Segue a proposta em anexo.\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um documento (PDF, DOCX, XLSX etc.).\n\n**Atenção (WAPI):** o arquivo é baixado pelo servidor e convertido para base64 antes do envio. A URL precisa ser publicamente acessível.\n\nO nome do arquivo exibido no WhatsApp é extraído da URL."
          },
          "response": [
            {
              "name": "422 — URL inacessível",
              "status": "Unprocessable Entity",
              "code": 422,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Could not download document from the provided URL.\",\"ts\":1718000000}"
            },
            {
              "name": "413 — Arquivo muito grande",
              "status": "Content Too Large",
              "code": 413,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Document exceeds 20 MB limit.\",\"ts\":1718000000}"
            }
          ]
        },

        {
          "name": "Enviar áudio (mensagem de voz)",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_media\",\n    \"to\": \"{{to}}\",\n    \"type\": \"audio\",\n    \"url\": \"{{media_url_audio}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um áudio como mensagem de voz (com forma de onda animada no WhatsApp).\n\n**Formato recomendado para WAPI:**\n- Container: OGG\n- Codec: Opus\n- Canais: mono (1 canal)\n\nConversão com ffmpeg:\n```\nffmpeg -i entrada.mp3 -ac 1 -c:a libopus -b:a 32k saida.ogg\n```\n\nArquivos MP3 também são aceitos mas aparecem como áudio comum, sem forma de onda.\n\n> O campo `caption` é ignorado para áudio."
          },
          "response": []
        },

        {
          "name": "Enviar imagem + registrar no Bitrix24",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_media\",\n    \"to\": \"{{to}}\",\n    \"type\": \"image\",\n    \"url\": \"{{media_url_image}}\",\n    \"caption\": \"Foto do produto solicitado.\",\n    \"sendtobitrix24\": true\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia imagem e registra no histórico do Bitrix24 como mensagem enviada (apenas WAPI)."
          },
          "response": []
        }

      ]
    },

    {
      "name": "📋 Templates (Meta)",
      "item": [

        {
          "name": "Listar templates aprovados",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" }
            ],
            "url": {
              "raw": "{{base_url}}?action=list_templates",
              "host": ["{{base_url}}"],
              "query": [{ "key": "action", "value": "list_templates" }]
            },
            "description": "Retorna os templates com status `APPROVED` cadastrados na conta Meta.\n\n**Exclusivo para conexões Meta Cloud API.** Retorna erro 400 em conexões WAPI.\n\nOs templates precisam ser criados previamente no WhatsApp Business Manager."
          },
          "response": [
            {
              "name": "200 — Templates aprovados",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"total\": 1,\n    \"templates\": [\n      {\n        \"name\": \"boas_vindas\",\n        \"language\": \"pt_BR\",\n        \"status\": \"APPROVED\",\n        \"category\": \"MARKETING\",\n        \"components\": [\n          { \"type\": \"HEADER\", \"format\": \"TEXT\", \"text\": \"Olá, {{1}}!\" },\n          { \"type\": \"BODY\",   \"text\": \"Bem-vindo à nossa plataforma. Acesse: {{2}}\" },\n          { \"type\": \"FOOTER\", \"text\": \"Responda PARAR para cancelar.\" }\n        ]\n      }\n    ]\n  }\n}"
            },
            {
              "name": "400 — Não é conexão Meta",
              "status": "Bad Request",
              "code": 400,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Action \\\"list_templates\\\" is only available for Meta (Cloud API) connections.\",\"ts\":1718000000}"
            }
          ]
        },

        {
          "name": "Enviar template — texto simples",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_template\",\n    \"to\": \"{{to}}\",\n    \"template_name\": \"{{template_name}}\",\n    \"template_lang\": \"{{template_lang}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um template sem variáveis.\n\n**Exclusivo Meta.** Templates são a única forma de iniciar uma conversa ou responder fora da janela de 24h.\n\n> `sendtobitrix24` não está disponível para templates."
          },
          "response": [
            {
              "name": "200 — Template enviado",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"message_id\": \"wamid.HBgLNTU...\",\n    \"to\": \"5511999990000\",\n    \"template_name\": \"boas_vindas\",\n    \"template_lang\": \"pt_BR\"\n  }\n}"
            }
          ]
        },

        {
          "name": "Enviar template — com variáveis no corpo",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_template\",\n    \"to\": \"{{to}}\",\n    \"template_name\": \"{{template_name}}\",\n    \"template_lang\": \"{{template_lang}}\",\n    \"components_json\": \"[{\\\"type\\\":\\\"body\\\",\\\"parameters\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"João\\\"},{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"#1234\\\"}]}]\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um template com variáveis no corpo.\n\nO `components_json` é um array JSON serializado como string. Para um template com corpo _\"Olá {{1}}, seu pedido {{2}} foi confirmado\"_, os parâmetros substituem `{{1}}` e `{{2}}` na ordem.\n\n**Estrutura do components_json:**\n```json\n[\n  {\n    \"type\": \"body\",\n    \"parameters\": [\n      { \"type\": \"text\", \"text\": \"João\" },\n      { \"type\": \"text\", \"text\": \"#1234\" }\n    ]\n  }\n]\n```"
          },
          "response": []
        },

        {
          "name": "Enviar template — com cabeçalho de imagem",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"send_template\",\n    \"to\": \"{{to}}\",\n    \"template_name\": \"{{template_name}}\",\n    \"template_lang\": \"{{template_lang}}\",\n    \"header_media_url\": \"{{media_url_image}}\",\n    \"header_media_type\": \"image\",\n    \"components_json\": \"[{\\\"type\\\":\\\"body\\\",\\\"parameters\\\":[{\\\"type\\\":\\\"text\\\",\\\"text\\\":\\\"50%\\\"}]}]\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Envia um template com cabeçalho de imagem e variáveis no corpo.\n\n`header_media_type` aceita: `image`, `video`, `document`.\n\nA imagem/vídeo/documento é baixado pelo servidor, validado por MIME real, enviado para a Meta e então incluído no cabeçalho do template."
          },
          "response": [
            {
              "name": "415 — MIME não permitido",
              "status": "Unsupported Media Type",
              "code": 415,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"MIME type 'image/gif' is not allowed for header_media_type 'image'.\",\"ts\":1718000000}"
            }
          ]
        }

      ]
    },

    {
      "name": "🎧 Atendimento (Bitrix24)",
      "item": [

        {
          "name": "Encerrar atendimento",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"close_chat\",\n    \"to\": \"{{to}}\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Encerra a sessão de atendimento ativa no Bitrix24 para o número informado.\n\n**Requisitos:**\n- Deve existir ao menos uma mensagem trocada após a atualização que grava o `chat_id` interno\n- O token do app precisa ter permissão nos métodos `imopenlines.*`\n\n**Atenção:** se o atendimento foi transferido para outro operador, o close pode falhar com \"not an operator\". Nesse caso, o novo operador precisa encerrar."
          },
          "response": [
            {
              "name": "200 — Atendimento encerrado",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"closed\": true,\n    \"to\": \"5511999990000\",\n    \"chat_id\": 511,\n    \"session_id\": 541\n  }\n}"
            },
            {
              "name": "404 — Chat não encontrado",
              "status": "Not Found",
              "code": 404,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"No active Bitrix24 chat found for this phone number. The chat_id may not have been captured yet — ensure at least one message was exchanged after the update.\",\"ts\":1718000000}"
            },
            {
              "name": "502 — Operador inválido",
              "status": "Bad Gateway",
              "code": 502,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Attempt to close the dialog by a user who is not an operator\",\"ts\":1718000000}"
            }
          ]
        },

        {
          "name": "Transferir atendimento",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"action\": \"transfer_chat\",\n    \"to\": \"{{to}}\",\n    \"transfer_id\": \"{{transfer_id}}\",\n    \"transfer_type\": \"user\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Transfere o atendimento ativo no Bitrix24 para outro operador ou fila.\n\n**Parâmetros:**\n- `to` — telefone do cliente (identifica o chat)\n- `transfer_id` — ID numérico do usuário Bitrix24 ou da fila de atendimento\n- `transfer_type` — `\"user\"` (padrão) para transferir a um operador, `\"queue\"` para transferir a uma fila de atendimento\n\nPara descobrir o ID do usuário Bitrix24, use o método `user.get` da REST API do Bitrix ou consulte o perfil do usuário no painel."
          },
          "response": [
            {
              "name": "200 — Transferido",
              "status": "OK",
              "code": 200,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\n  \"success\": true,\n  \"ts\": 1718000000,\n  \"data\": {\n    \"transferred\": true,\n    \"to\": \"5511999990000\",\n    \"chat_id\": 511,\n    \"transfer_type\": \"user\",\n    \"transfer_id\": 11,\n    \"session_id\": 539\n  }\n}"
            },
            {
              "name": "404 — Chat não encontrado",
              "status": "Not Found",
              "code": 404,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"No active Bitrix24 chat found for this phone number. The chat_id may not have been captured yet — ensure at least one message was exchanged after the update.\",\"ts\":1718000000}"
            }
          ]
        }

      ]
    },

    {
      "name": "⚠️ Erros comuns",
      "item": [

        {
          "name": "401 — API key inválida",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Api-Key", "value": "chave-invalida-aqui" }
            ],
            "url": {
              "raw": "{{base_url}}?action=status",
              "host": ["{{base_url}}"],
              "query": [{ "key": "action", "value": "status" }]
            },
            "description": "Exemplo de requisição com chave inválida para ver o erro 401."
          },
          "response": [
            {
              "name": "401 — Chave inválida",
              "status": "Unauthorized",
              "code": 401,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Invalid API key.\",\"ts\":1718000000}"
            }
          ]
        },

        {
          "name": "400 — action ausente",
          "request": {
            "method": "POST",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" },
              { "key": "Content-Type", "value": "application/json" }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n    \"to\": \"{{to}}\",\n    \"message\": \"Sem action\"\n}",
              "options": { "raw": { "language": "json" } }
            },
            "url": {
              "raw": "{{base_url}}",
              "host": ["{{base_url}}"]
            },
            "description": "Requisição sem o campo `action` para ver o erro 400."
          },
          "response": [
            {
              "name": "400 — action ausente",
              "status": "Bad Request",
              "code": 400,
              "header": [{ "key": "Content-Type", "value": "application/json" }],
              "body": "{\"success\":false,\"error\":\"Parameter \\\"action\\\" is required.\",\"ts\":1718000000}"
            }
          ]
        },

        {
          "name": "429 — Rate limit excedido",
          "request": {
            "method": "GET",
            "header": [
              { "key": "X-Api-Key", "value": "{{api_key}}" }
            ],
            "url": {
              "raw": "{{base_url}}?action=status",
              "host": ["{{base_url}}"],
              "query": [{ "key": "action", "value": "status" }]
            },
            "description": "Exemplo de resposta ao exceder 120 req/min."
          },
          "response": [
            {
              "name": "429 — Rate limit",
              "status": "Too Many Requests",
              "code": 429,
              "header": [
                { "key": "Content-Type", "value": "application/json" },
                { "key": "Retry-After", "value": "23" },
                { "key": "X-RateLimit-Limit", "value": "120" },
                { "key": "X-RateLimit-Remaining", "value": "0" }
              ],
              "body": "{\"success\":false,\"error\":\"Rate limit exceeded. Max 120 requests/minute.\",\"ts\":1718000000}"
            }
          ]
        }

      ]
    }

  ]
}