# Visão geral

> O que o Matra Meta Hub faz, como um app se integra e o que pedir à equipe Matra antes de começar.

Fonte: https://metahub.matratecnologia.com/docs/visao-geral

O Matra Meta Hub é a camada entre os apps da Matra e as APIs da Meta. Ele concentra o app aprovado na Meta e expõe uma API REST e webhooks assinados. Assim, o seu app não fala com a Graph API, não guarda token da Meta e não passa por revisão de app própria.

Hoje o hub cobre o **WhatsApp Cloud API**: conexão do número do cliente (inclusive Coexistence, com o app WhatsApp Business no celular), mensagens recebidas e enviadas, mídia, status de entrega, templates, janela de atendimento e custos. Instagram Direct, Messenger e Lead Ads estão planejados.

## Endereços

| O quê | URL |
|---|---|
| API (base de todas as rotas) | `https://api.metahub.matratecnologia.com/v1` |
| Documentação | `https://metahub.matratecnologia.com/docs` |
| Índice para IA | `https://metahub.matratecnologia.com/llms.txt` |
| Documentação inteira num arquivo | `https://metahub.matratecnologia.com/llms-full.txt` |
| OpenAPI 3 das rotas `/v1` | `https://metahub.matratecnologia.com/docs/openapi.json` |

## Conceitos

| Termo | O que é |
|---|---|
| App consumidor | O seu sistema (um CRM, um SaaS). Tem chaves de API, um endpoint de webhook e uma lista de URLs de retorno |
| Workspace | Um cliente final do seu app. Você o cria pela API com o id que ele tem no seu sistema (`externalId`) |
| Conexão | Um número de WhatsApp Business ligado a um workspace. Nasce quando o cliente conclui o fluxo da Meta na página de conexão do hub |
| Evento | Algo que aconteceu (mensagem recebida, status de entrega, conexão criada). Chega ao seu app por webhook assinado |
| Entrega | Uma tentativa de levar um evento ao seu webhook. Tem reentrega automática e reenvio manual |

## Como a integração funciona

1. **Workspace.** O seu backend cria um workspace para o cliente: `POST /v1/workspaces`.
2. **Sessão de conexão.** O backend abre uma sessão (`POST /v1/workspaces/:id/connect-sessions`) e manda o cliente para a `url` devolvida, uma página do hub com o fluxo oficial da Meta (Embedded Signup).
3. **Retorno.** Ao terminar, o navegador volta para o seu `returnUrl` com `?status=connected&connectionId=...`. A confirmação de verdade é o evento `connection.created` no seu webhook.
4. **Ativação.** O hub ativa o número em segundo plano. Quando termina, chega `connection.updated` com `status: "active"`.
5. **Conversa.** Mensagens recebidas chegam como `whatsapp.message.received`. Para responder, use `POST /v1/connections/:id/messages`. O resultado do envio chega como `whatsapp.message.status`.

```
Seu backend ──POST /v1/workspaces──────────────▶ Hub
Seu backend ──POST …/connect-sessions──────────▶ Hub ──▶ url da página de conexão
Cliente     ──abre a url, conclui o fluxo da Meta──▶ volta ao seu returnUrl
Hub         ──webhook connection.created / .updated──▶ seu endpoint
Hub         ──webhook whatsapp.message.received──────▶ seu endpoint
Seu backend ──POST …/messages (Idempotency-Key)──▶ Hub ──▶ Meta
Hub         ──webhook whatsapp.message.status────────▶ seu endpoint
```

## O que pedir à equipe Matra

Antes da primeira chamada, a equipe Matra cadastra o seu app no hub e entrega:

- **Chave de API** (`mh_live_...`), mostrada uma única vez. Guarde num cofre de segredos, só no backend.
- **Endpoint de webhook:** a equipe cadastra a URL que você informar (HTTPS público, sem redirect) e entrega o **segredo de assinatura** (`whsec_...`), também mostrado uma vez.
- **URLs de retorno:** a lista de `returnUrl` aceitas na sessão de conexão. A comparação ignora query e fragmento.

Contato: matratecnologia@gmail.com ou WhatsApp +55 (43) 99914-0409.

## Regras que valem em toda a API

- **Autenticação:** `Authorization: Bearer <chave>` em toda rota de `/v1`. A API é server-to-server: nunca chame do navegador.
- **Erros:** decida pelo campo `code` da resposta, nunca pela `message` (ela vem traduzida).
- **Recurso de outro app:** responde 404, nunca 403.
- **Envio de mensagem:** exige o header `Idempotency-Key`. Repetir com a mesma chave não envia de novo.
- **Webhooks:**
  - assinados com HMAC-SHA256 sobre `` `${x-hub-timestamp}.${corpo cru}` ``;
  - entrega "pelo menos uma vez": deduplique pelo `id` do envelope;
  - a ordem de chegada não é garantida.
- **Conteúdo:** nenhuma resposta ou evento de status traz token, PIN ou credencial da Meta. As respostas de envio não trazem o conteúdo da mensagem nem o destinatário.

## Próximos passos

- [Começo rápido](https://metahub.matratecnologia.com/docs/comeco-rapido.md): do workspace à primeira mensagem, com exemplos.
- [Receber webhooks](https://metahub.matratecnologia.com/docs/webhooks.md): verificação da assinatura e o que o receptor precisa tratar.
- [Catálogo de eventos](https://metahub.matratecnologia.com/docs/eventos.md): o formato de cada evento.