# Wafly: contratos e capacidades da API

Conferência documental em 30/10/2026. Esta página orienta a integração; não executa chamadas nem comprova entrega WhatsApp.

## Qual documento usar

| Documento | Escopo conferido | Como interpretar |
|---|---|---|
| [Swagger 2 do bridge](https://wafly.com.br/api-bridge-whats/v2/api-docs) | 120 caminhos; inclui rotas operacionais/internas | Use o contrato de cada operação. A existência de uma rota não garante suporte em todos os motores. |
| [OpenAPI 3.1 do site](https://wafly.com.br/openapi.json) | 108 caminhos: 100 do bridge e 8 do management | Referência curada de integração. O prefixo /api-bridge-whats já está nos caminhos; não acrescente duas vezes. |
| [Guia de endpoints](https://wafly.com.br/api-docs) | API e configuração por recurso | Não suponha que recursos de chamada, grupo, comunidade ou status estejam disponíveis em qualquer conexão. |

Os totais diferem por escopo, não por serem versões equivalentes do mesmo arquivo. O Swagger acrescenta 12 caminhos de instância e 8 caminhos de saúde/monitoramento/internos ausentes da referência estática. A referência estática acrescenta 8 caminhos /api-managment/external/instances que pertencem a outro serviço. Não use rotas internas como contrato público de integração.

## Confira capacidades antes de escolher um recurso

Para o contrato unificado, consulte, em seu backend ou credencial privada:

```http
GET /api-bridge-whats/instances/{instance}/token/{token}/capabilities
Client-Token: SUA_CHAVE_DA_CONTA
```

`instance` é o ID público da instância, não o nome de exibição nem o _id do Mongo. O token deve ser dessa mesma instância. Não cole credenciais em prompts, screenshots, exports públicos ou links compartilhados.

A resposta documentada contém `capabilitiesVersion`, `provider`, `capabilities`, `unifiedMessageTypes`, `mediaSourceTypes` e `explicitlyUnsupportedMessageTypes`. A versão atual do contrato é 4. Leia a resposta da sua conexão; não trate o exemplo de outra conta como autorização.

| Camada | Interpretação |
|---|---|
| Contrato unificado | `capabilities` cobre as funções migradas para essa interface. No FLEX, inclui SEND_TEXT, SEND_MEDIA e IDEMPOTENT_SEND. Não é o catálogo completo das funções legadas. |
| Tipos de mensagem | No FLEX, o contrato unificado declara TEXT, IMAGE, AUDIO, VIDEO e DOCUMENT. LOCATION, STICKER e TEMPLATE são explicitamente não suportados por esse contrato; uma rota legada é uma camada diferente. |
| Chamadas | Consulte /call/capabilities. No Evolution, áudio está em beta; vídeo, grupos, TTS, WebRTC e transcrição não estão incluídos nesse contrato de áudio. Não conclua suporte apenas porque a ação aparece no node. |
| Publicação de status | Consulte GET /status-publication e confira supported, connected e requisitos de público/contatos antes de publicar. Não é a consulta de entrega de uma mensagem de texto. |
| Comunidades | A listagem é GET /communities, com array de objetos id/name. O schema Community do Swagger documenta esses dois campos. Requisitos do motor, permissões e disponibilidade continuam valendo. |

A rota de capacidades não ativa funcionalidades, contrata API Oficial ou garante o gate comercial de um produto. Não migre, reinicie ou desconecte uma sessão para preencher um relatório.

## Envio, recebimento e entrega são etapas diferentes

1. No n8n, **Message → Send Text** realiza o envio com sua credencial Wafly API. A aceitação e o messageId são evidência de processamento, não de entrega ao destinatário.
2. Para receber, use **Webhook** nativo com método POST e a **Production URL** do workflow publicado/ativo. **Wafly → Webhook → Set Webhook** configura essa URL; não é um trigger.
3. GET /webhook lê a URL de recebimento armazenada. PUT /update-webhook-received grava `{ "value": "https://SEU_N8N/webhook/SEU_CAMINHO" }`. Use URL sua e proteja os dados recebidos.
4. GET /messages/{messageId}/status consulta o mesmo ID. Diferencie aceite, entrega técnica, leitura técnica e resultado desconhecido; não atribua leitura humana automaticamente.
5. O webhook unificado de status usa PUT /update-webhook-message-status e GET /webhook-message-status. É distinto de /update-webhook-delivery, que pertence ao contrato legado. Escolha a camada documentada para sua integração e reconcilie o mesmo messageId.

Os caminhos acima, salvo os links completos, são relativos a /api-bridge-whats/instances/{instance}/token/{token}. Não use GET de status legado como teste de conexão em monitoramentos: algumas implementações podem inicializar sessão. Não gere tráfego ou envios para fabricar prova.

## n8n Cloud: disponibilidade e validação

O registro oficial do n8n lista **n8n-nodes-wafly 1.6.1** como publicado, conferido em 30/10/2026. O checksum publicado no registro coincide com o tarball 1.6.1 do npm. O catálogo lista 119 operações, incluindo Send Text e Set Webhook; isso não certifica suporte de todas as operações em cada conexão.

O pacote foi executado em n8n 2.43.7 local isolado contra uma API simulada: 119 operações e preservação de expressões/item linking passaram. Nenhum WhatsApp real foi enviado. Não foi concluído um round trip em uma conta n8n Cloud. Templates existentes exigem validação individual; use o [tutorial e starter HTTP seguro](https://wafly.com.br/tutoriais/whatsapp-api-n8n/) como alternativa.

Fontes: [instalação oficial n8n](https://docs.n8n.io/integrations/community-nodes/installation-and-management/install-verified-community-nodes/), registro público do n8n para n8n-nodes-wafly e contratos publicados acima. Wafly Flex conecta por QR/pareamento e não é a API Oficial da Meta.