Skip to main content
Mensageria sobre uma API de terceiros tem limites físicos. Esta página diz com clareza o que a Routa promete, o que ela não promete e como você deve projetar sua integração.

​
O que a Routa garante

Nenhuma perda silenciosa

Uma mensagem aceita (202) é gravada de forma durável antes da resposta. Ela nunca desaparece sem deixar rastro: chega ao destino ou vira failed.

Status que não regride

O status só avança. Uma mensagem não volta de read para sent por causa de um aviso atrasado.

Falhas permanentes são visíveis

Toda falha terminal gera message.failed, e as transitórias são retentadas automaticamente.

Eventos recuperáveis

Eventos ficam no log por 90 dias e podem ser consultados e reenviados.

​
O que a Routa não garante

  • Entrega imediata. Aceitar não é entregar. A latência depende do provedor e da fila do canal.
  • Ordem global. Mensagens e eventos podem chegar fora de ordem. Use sequence, occurred_at e o status monotônico para reconciliar.
  • Exatamente uma vez. Não existe entrega exatamente uma vez contra uma API HTTP de terceiros. A garantia é pelo menos uma vez.

​
Envio: aceito, depois assíncrono

  1. A API valida e grava a mensagem e o evento message.accepted na mesma transação. Só então responde 202.
  2. Um worker envia ao provedor, respeitando os limites de taxa do canal.
  3. As confirmações do provedor (sent, delivered, read, failed) atualizam a mensagem e geram eventos.

​
Se algo falha no meio

​
Resultado desconhecido

O caso mais difícil é um timeout contra o provedor: a mensagem pode ou não ter sido enviada. A Routa:
  1. Envia uma referência determinística junto com a mensagem, permitindo deduplicação no provedor.
  2. Antes de tentar de novo, consulta o provedor para saber se ele já registrou a mensagem, quando ele oferece essa consulta.
  3. Se a dúvida persiste, tenta de novo: a garantia é pelo menos uma vez. A duplicidade é rara e honesta, nunca escondida.

​
Recebimento

Mensagens recebidas são persistidas antes de serem processadas, e a Routa deduplica reentregas do provedor. Conteúdo que ela não entende vira content.type = "unsupported": a mensagem não é descartada. Se uma mídia recebida falha em definitivo, a mensagem continua existindo com a mídia unavailable.

​
Eventos e webhooks

  • Cada evento é entregue pelo menos uma vez a cada endpoint assinante, com o mesmo id em todas as tentativas.
  • Uma entrega é retentada por cerca de 20 horas. Depois disso ela fica exhausted e pode ser reenviada. Veja Retentativas e reenvio.
  • GET /v1/events permite reconciliar. Veja Reconciliar eventos.

​
Como projetar sua integração

1

Envie com idempotência

Use Idempotency-Key em todo envio. Veja Idempotência.
2

Não trate 202 como entrega

Confirme a entrega por message.delivered.
3

Processe eventos de forma idempotente

Deduplique por event.id e nunca regrida o status.
4

Tenha um job de conferência

Rode periodicamente GET /v1/events como rede de segurança.

​
Retenção de dados

Períodos de retenção publicados como parte do contrato da API.