# Routa

> Documentação oficial da Routa: infraestrutura de mensageria para WhatsApp com uma API REST simples, SDK oficial e webhooks confiáveis.

- [Introdução](https://docs.routa.chat/index.md): A Routa é a infraestrutura de mensageria para WhatsApp: uma API REST consistente para enviar e receber mensagens sem lidar com a complexidade do provedor.
- [Início rápido](https://docs.routa.chat/quickstart.md): Crie uma chave de API e envie sua primeira mensagem de WhatsApp em menos de 30 segundos.
- [Chaves de API](https://docs.routa.chat/authentication.md): Como autenticar suas requisições à API da Routa, quais escopos cada rota exige e como manter suas chaves seguras.
- [Ambientes: produção e teste](https://docs.routa.chat/environments.md): Entenda a diferença entre projetos live e test e como a chave de API define o ambiente das suas requisições.
- [Modelo de dados](https://docs.routa.chat/concepts/data-model.md): Organizações, projetos, canais e identificadores: como os recursos da Routa se relacionam.
- [Mensagens e ciclo de vida](https://docs.routa.chat/concepts/messages.md): O objeto mensagem, os tipos de conteúdo e como o status evolui de accepted até read ou failed.
- [Eventos](https://docs.routa.chat/concepts/events.md): O log de eventos normalizados da Routa: formato, tipos, versionamento e como consumi-los com segurança.
- [Templates](https://docs.routa.chat/concepts/templates.md): Como submeter, acompanhar a aprovação e enviar templates de WhatsApp, incluindo cabeçalho, rodapé e botões.
- [Mídia](https://docs.routa.chat/concepts/media.md): Como a Routa armazena imagens, áudios, vídeos e documentos, quais tipos são aceitos e como obter uma URL temporária.
- [Enviar uma mensagem de texto](https://docs.routa.chat/guides/send-text-message.md): Envie texto por WhatsApp com POST /v1/messages, use idempotência e metadados e trate as respostas.
- [Enviar um template](https://docs.routa.chat/guides/send-template-message.md): Submeta um template, aguarde a aprovação e envie-o com parâmetros usando POST /v1/messages.
- [Receber mensagens](https://docs.routa.chat/guides/receive-messages.md): Receba mensagens de clientes por webhook (message.received), consulte o histórico e baixe a mídia recebida.
- [Acompanhar a entrega](https://docs.routa.chat/guides/track-delivery.md): Descubra se uma mensagem chegou ao destinatário usando webhooks, consulta direta ou o log de eventos.
- [Visão geral dos webhooks](https://docs.routa.chat/webhooks/overview.md): Receba eventos normalizados da Routa no seu servidor HTTPS: como registrar um endpoint, o formato das entregas e os limites.
- [Verificar assinaturas](https://docs.routa.chat/webhooks/signatures.md): Valide o header Routa-Signature para garantir que cada webhook veio da Routa e não foi alterado.
- [Retentativas e reenvio](https://docs.routa.chat/webhooks/retries-and-replay.md): Como a Routa retenta entregas que falham, quando um endpoint é desativado e como reenviar entregas esgotadas.
- [Tipos de evento](https://docs.routa.chat/webhooks/event-types.md): Referência dos eventos de mensagem, canal e template que a Routa entrega por webhook e pelo log de eventos.
- [Reconciliar eventos](https://docs.routa.chat/webhooks/reconciliation.md): Recupere eventos perdidos consultando GET /v1/events depois de uma indisponibilidade do seu servidor.
- [Idempotência](https://docs.routa.chat/reliability/idempotency.md): Use o header Idempotency-Key para repetir um envio com segurança, sem criar mensagens duplicadas.
- [Limites de taxa](https://docs.routa.chat/reliability/rate-limits.md): Limites de requisições por projeto, os headers RateLimit e como reagir a um 429.
- [Paginação](https://docs.routa.chat/reliability/pagination.md): Percorra listas grandes com paginação por cursor: parâmetros, formato da resposta e iteração no SDK.
- [Garantias de entrega](https://docs.routa.chat/reliability/delivery-guarantees.md): O que a Routa garante e o que não garante sobre o envio e a entrega de mensagens, e como projetar sua integração com isso.
- [Erros](https://docs.routa.chat/errors/overview.md): O formato dos erros da API, os tipos de erro e como decidir entre corrigir a requisição, tentar de novo ou escalar.
- [Códigos de erro](https://docs.routa.chat/errors/error-codes.md): Catálogo dos códigos de erro da API de dados da Routa, com status HTTP, causa provável e como resolver.
- [Uso](https://docs.routa.chat/billing/usage.md): Consulte o uso medido do seu projeto por métrica, canal e período com GET /v1/usage.
- [Planos e franquia](https://docs.routa.chat/billing/plans-and-quota.md): Como a franquia de mensagens do seu plano funciona, o que acontece quando ela acaba e como habilitar o excedente.
- [Referência da API](https://docs.routa.chat/api-reference/introduction.md): URL base, autenticação, formato de resposta, paginação, idempotência, limites e convenções da API REST da Routa.
- [Enviar mensagem](https://docs.routa.chat/api-reference/endpoint/messages/send.md): Envia uma mensagem de texto ou de template por um canal.
- [Listar mensagens](https://docs.routa.chat/api-reference/endpoint/messages/list.md): Lista as mensagens do projeto, da mais recente para a mais antiga, com paginação por cursor. Filtre por `direction` para ver só as recebidas ou só as enviadas.
- [Consultar mensagem](https://docs.routa.chat/api-reference/endpoint/messages/retrieve.md): Retorna uma mensagem com o status atual e os horários de cada etapa (`sent_at`, `delivered_at`, `read_at`, `failed_at`).
- [Marcar mensagem como lida](https://docs.routa.chat/api-reference/endpoint/messages/mark-read.md): Marca uma mensagem **recebida** (`inbound`) como lida e envia a confirmação de leitura ao remetente. Para uma mensagem enviada por você, retorna `422` com o código `message_direction_invalid`.
- [Listar eventos](https://docs.routa.chat/api-reference/endpoint/events/list.md): Lista os eventos do projeto em ordem crescente de `sequence`, do mais antigo para o mais recente. É o caminho de **reconciliação** para quem perdeu entregas de webhook: guarde o `id` do último evento processado e passe-o em `after`.
- [Criar endpoint de webhook](https://docs.routa.chat/api-reference/endpoint/webhooks/create.md): Registra uma URL para receber eventos. A resposta inclui o `secret` de assinatura, **exibido uma única vez**. Guarde-o para [verificar as assinaturas](/webhooks/signatures).
- [Listar endpoints de webhook](https://docs.routa.chat/api-reference/endpoint/webhooks/list.md): Lista os endpoints de webhook do projeto (no máximo 5). O `secret` nunca é retornado nas listagens.
- [Consultar endpoint de webhook](https://docs.routa.chat/api-reference/endpoint/webhooks/retrieve.md): Retorna um endpoint, incluindo `status`, `consecutive_failures` e os horários do último sucesso e da última falha.
- [Atualizar tipos assinados](https://docs.routa.chat/api-reference/endpoint/webhooks/update.md): Substitui a lista de tipos de evento assinados pelo endpoint. A lista não pode ser vazia e aceita curingas como `message.*`.
- [Rotacionar segredo](https://docs.routa.chat/api-reference/endpoint/webhooks/rotate-secret.md): Gera um novo segredo de assinatura e o retorna. O segredo anterior continua válido por **24 horas**, e durante esse período as entregas são assinadas com os dois. Veja [Verificar assinaturas](/webhooks/signatures).
- [Desativar endpoint](https://docs.routa.chat/api-reference/endpoint/webhooks/disable.md): Pausa as entregas para o endpoint (`status: disabled_by_user`). Os eventos continuam sendo gravados no log.
- [Reativar endpoint](https://docs.routa.chat/api-reference/endpoint/webhooks/enable.md): Reativa um endpoint desativado e **reenvia em lote** todas as entregas esgotadas. A resposta informa quantas foram reenviadas em `replayed_count`.
- [Listar entregas](https://docs.routa.chat/api-reference/endpoint/webhooks/list-deliveries.md): Lista as entregas de um endpoint, da mais recente para a mais antiga. Filtre por `state=exhausted` para ver as entregas que esgotaram as tentativas. As entregas ficam consultáveis por 30 dias.
- [Reenviar uma entrega](https://docs.routa.chat/api-reference/endpoint/webhooks/replay-delivery.md): Reenvia uma entrega no estado `exhausted`. Uma entrega em outro estado retorna `409` com o código `webhook_delivery_not_replayable`.
- [Reenviar todas as entregas esgotadas](https://docs.routa.chat/api-reference/endpoint/webhooks/replay-deliveries.md): Reenvia, de uma vez, todas as entregas esgotadas do endpoint. Retorna a quantidade reenviada.
- [Submeter template](https://docs.routa.chat/api-reference/endpoint/templates/create.md): Cria um template e o envia ao WhatsApp para aprovação. A aprovação é decidida pelo provedor, no tempo dele. Acompanhe pelos eventos `template.*` ou consultando o template.
- [Listar templates](https://docs.routa.chat/api-reference/endpoint/templates/list.md): Lista os templates do projeto com paginação por cursor. Filtre por canal com `channel`.
- [Consultar template](https://docs.routa.chat/api-reference/endpoint/templates/retrieve.md): Retorna um template com o `status` de aprovação atual. Se ele foi rejeitado, `rejection_reason` indica o motivo.
- [Enviar mídia de cabeçalho](https://docs.routa.chat/api-reference/endpoint/templates/upload-media.md): Envia uma imagem, um vídeo ou um documento para usar como cabeçalho de um template. Envie os bytes do arquivo **diretamente no corpo**, com o `Content-Type` do arquivo. O formato é deduzido do tipo.
- [Enviar ou hospedar mídia](https://docs.routa.chat/api-reference/endpoint/media/upload.md): Armazena um arquivo de mídia sob custódia da Routa. Há duas formas, escolhidas pelo `Content-Type`:
- [Consultar mídia](https://docs.routa.chat/api-reference/endpoint/media/retrieve.md): Retorna o objeto de mídia com uma **URL assinada nova**, válida por 15 minutos, quando `status` é `ready`. Se estiver `pending`, repita a consulta em instantes.
- [Consultar uso](https://docs.routa.chat/api-reference/endpoint/usage/retrieve.md): Retorna o uso medido do projeto no período, com uma linha por combinação de métrica, tipo de canal e provedor. O dia corrente ainda aberto é lido ao vivo. O intervalo tem no máximo 92 dias.
- [Identificar a chave de API](https://docs.routa.chat/api-reference/endpoint/identity/whoami.md): Resolve a chave de API em uso para a organização, o projeto e os escopos que ela possui. Não tem efeitos colaterais e aceita qualquer chave válida, o que o torna ideal para verificar uma chave.
- [SDK para Node.js](https://docs.routa.chat/sdk/overview.md): O cliente oficial da Routa para TypeScript e JavaScript: instalação, primeiro envio, requisitos e o que ainda não é suportado.
- [Configuração](https://docs.routa.chat/sdk/configuration.md): Opções do cliente Routa: timeout, retentativas, baseURL, logger e fetch, além do comportamento de idempotência.
- [Mensagens](https://docs.routa.chat/sdk/messages.md): Envie, consulte, liste e marque mensagens como lidas com routa.messages.
- [Webhooks](https://docs.routa.chat/sdk/webhooks.md): Crie endpoints de webhook, verifique assinaturas com constructEvent e consulte e reenvie entregas pelo SDK.
- [Paginação](https://docs.routa.chat/sdk/pagination.md): Percorra listas com iteradores assíncronos ou controle o cursor manualmente com .page().
- [Eventos, templates, mídia e uso](https://docs.routa.chat/sdk/resources.md): Os demais recursos do SDK: routa.events, routa.templates, routa.media, routa.usage e routa.whoami.
- [Tratamento de erros](https://docs.routa.chat/sdk/error-handling.md): As classes de erro do SDK, os campos que elas carregam e como tratar autenticação, validação, limite de taxa e cobrança.
- [Tipos e IDs](https://docs.routa.chat/sdk/typescript.md): Como usar os tipos do SDK, os IDs branded e as funções de validação e conversão de identificadores.

## OpenAPI Specs

- [openapi](/openapi.json)

## Optional

- [Painel](https://app.routa.chat)
- [SDK no GitHub](https://github.com/routa-chat/routa-nodejs-sdk)
- [Site](https://routa.chat)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.