# Matra Meta Hub

> API REST e webhooks assinados para apps integrarem o WhatsApp Cloud API (Meta) sem falar com a Graph API: conexão do número do cliente pelo Embedded Signup, mensagens recebidas e enviadas, mídia, status de entrega, templates, janela de atendimento e custos. Documentação em português do Brasil.

Regras essenciais:

- Base da API: https://api.metahub.matratecnologia.com/v1 (só server-to-server; nunca do navegador).
- Autenticação: header `Authorization: Bearer mh_live_...` em toda rota. Chave, segredo de webhook e URLs de retorno são entregues pela equipe Matra.
- Erro: `{ statusCode, error, code, message }`. Decida pelo `code`; a `message` vem traduzida. Recurso de outro app responde 404.
- Listagens: `page` e `limit` (máx. 100); resposta `{ data, meta: { total, page, limit, totalPages, hasNext } }`.
- Envio de mensagem: `POST /v1/connections/:connectionId/messages` exige o header `Idempotency-Key`; responde 202 e o resultado chega por webhook. Estado `uncertain` não deve ser reenviado automaticamente.
- Webhook: `x-hub-signature` = `sha256=` + HMAC-SHA256 hex de `${x-hub-timestamp}.${corpo cru}` com o segredo do endpoint; recuse timestamp com mais de 5 min de diferença; responda 2xx em até 10 s.
- Entrega "pelo menos uma vez" e sem ordem garantida: deduplique pelo `id` do envelope e ordene por `createdAt`.
- Contato: identifique pelo `userId` (BSUID); o telefone pode faltar.
- Especificação OpenAPI 3 das rotas: https://metahub.matratecnologia.com/docs/openapi.json

## Documentação

- [Visão geral](https://metahub.matratecnologia.com/docs/visao-geral.md): O que o Matra Meta Hub faz, como um app se integra e o que pedir à equipe Matra antes de começar.
- [Começo rápido](https://metahub.matratecnologia.com/docs/comeco-rapido.md): Do workspace à primeira mensagem enviada, com exemplos em curl e TypeScript.
- [Autenticação e convenções](https://metahub.matratecnologia.com/docs/autenticacao.md): Chave de API, limites de taxa, formato de erro, paginação e idempotência.
- [Workspaces](https://metahub.matratecnologia.com/docs/workspaces.md): Um workspace por cliente final do seu app: criar, listar, renomear e desativar.
- [Conexão do WhatsApp](https://metahub.matratecnologia.com/docs/conexoes.md): Como o cliente final conecta o número dele pela página do hub, e o recurso de conexão.
- [Mensagens](https://metahub.matratecnologia.com/docs/mensagens.md): Identidade do contato, envio idempotente, estados do envio, leitura e janela de atendimento.
- [Mídia](https://metahub.matratecnologia.com/docs/midia.md): Upload de mídia para envio e download da mídia recebida.
- [Templates](https://metahub.matratecnologia.com/docs/templates.md): Cache de templates por conta, sincronização, criação e exclusão.
- [Receber webhooks](https://metahub.matratecnologia.com/docs/webhooks.md): Requisição, assinatura HMAC, deduplicação, reentrega e reenvio manual.
- [Catálogo de eventos](https://metahub.matratecnologia.com/docs/eventos.md): Todos os eventos que o hub envia ao seu webhook, com o formato de cada um.
- [Custos e consumo](https://metahub.matratecnologia.com/docs/custos.md): Preço por mensagem entregue, franquia de serviço, consumo do mês e como aplicar o preço.

## Opcional

- [Documentação inteira num arquivo](https://metahub.matratecnologia.com/llms-full.txt): todas as páginas acima, concatenadas.
- [OpenAPI das rotas /v1](https://metahub.matratecnologia.com/docs/openapi.json): schemas exatos de parâmetros, corpos e respostas.