Referência
Descrição exata e completa, sem tutorial. Para o raciocínio por trás das regras, veja a explicação.
API
Base: https://rsvp.hellomanoel.com/api/v1. Corpos de requisição e resposta em JSON. Envie Accept: application/json.
Autenticação e permissões
Cabeçalho Authorization: Bearer {token}. O token pertence a uma organização e só enxerga os dados dela. Token de pessoa (usuário) não é aceito (401). Tokens não expiram; só deixam de valer quando revogados.
| Permissão (ability) | Libera |
|---|---|
events:read |
GET /events, GET /events/{id} |
rsvps:read |
GET /events/{id}/rsvps |
rsvps:write |
POST /events/{id}/rsvps |
As permissões são independentes: rsvps:write sozinha não permite ler eventos.
Limite de uso
60 requisições por minuto por token. Acima disso: 429 com cabeçalho Retry-After (segundos).
Endpoints
| Método e caminho | Permissão | Descrição |
|---|---|---|
GET /events |
events:read |
Eventos da organização, do mais recente para o mais antigo (starts_at decrescente). Paginado. |
GET /events/{id} |
events:read |
Um evento. |
GET /events/{id}/rsvps |
rsvps:read |
Respostas do evento, por id crescente. Paginado. |
POST /events/{id}/rsvps |
rsvps:write |
Registra uma inscrição pela regra da inscrição aberta. |
Visibilidade dos eventos. A API lista eventos em qualquer estado exceto draft e pending_review. Evento de outra organização, ou em um desses dois estados, responde 404.
POST /events/{id}/rsvps
Só funciona em evento com inscrição aberta (open_rsvp) e visibilidade que permita auto-inscrição. Usa a mesma regra de vagas, fila de espera, aprovação e pagamento do formulário público.
| Campo | Tipo | Regra |
|---|---|---|
guest_name |
string | obrigatório, até 160 caracteres |
email |
string | obrigatório, e-mail válido (RFC), até 180 caracteres |
consent |
boolean | obrigatório e verdadeiro (aceite do uso dos dados) |
communications_consent |
boolean | opcional; se enviado, precisa ser verdadeiro. Só vale quando o evento coleta esse consentimento |
fields |
objeto | respostas às perguntas do evento, chave = id do campo; ids desconhecidos são rejeitados. Obrigatoriedade e opções seguem a configuração de cada campo |
Resultados:
| Situação | Status | Corpo |
|---|---|---|
| Inscrição criada (confirmada, fila, aguardando pagamento ou aprovação) | 201 |
{"data": <Resposta>} (o status indica onde caiu) |
| E-mail já inscrito | 202 |
{"message": "Link de acesso reenviado ao e-mail já inscrito."} e nada é criado |
| Evento não aceita inscrição aberta | 409 |
{"message": "..."} |
| Regra de negócio violada (prazo encerrado, etc.) | 409 |
{"message": "..."} |
| Validação | 422 |
{"message": "...", "errors": {campo: [mensagens]}} |
A API não aceita telefone.
Objeto Evento
| Campo | Tipo | Observação |
|---|---|---|
id |
integer | |
slug |
string | único dentro da organização |
title |
string | |
description |
string | null | |
status |
string | published, closed, completed, cancelled (na API; draft e pending_review não aparecem) |
visibility |
string | public, etc. |
starts_at |
string | null | ISO 8601 |
response_deadline |
string | null | ISO 8601 |
timezone |
string | ex.: America/Sao_Paulo |
capacity |
integer | null | |
venue_name |
string | null | |
venue_address |
string | null | |
url |
string | página pública do evento |
published_at |
string | null | ISO 8601 |
cancelled_at |
string | null | ISO 8601 |
Objeto Resposta (RSVP)
| Campo | Tipo | Observação |
|---|---|---|
id |
integer | |
event_id |
integer | |
status |
string | ver tabela abaixo |
source |
string | null | direct_link, campaign, import, invite |
guest_name |
string | null | |
email |
string | null | pode ser nulo após anonimização |
responded_at |
string | null | ISO 8601 |
confirmed_at |
string | null | ISO 8601 |
waitlisted_at |
string | null | ISO 8601 |
cancelled_at |
string | null | ISO 8601 |
checked_in |
boolean | presença registrada |
Valores de status:
| Valor | Significado |
|---|---|
confirmed |
Confirmada |
pending_payment |
Aguardando pagamento |
pending_approval |
Aguardando aprovação |
waitlisted |
Na lista de espera |
declined |
Recusada |
cancelled |
Cancelada |
tentative |
Resposta prévia |
Dados pessoais: telefone nunca é exposto. O e-mail é.
Paginação
Listagens devolvem data, links (first, last, prev, next) e meta (current_page, per_page, total, ...). 15 itens por página; use ?page=N.
Códigos de resposta
| Status | Quando |
|---|---|
200 / 201 / 202 |
Sucesso (ver POST) |
401 |
Sem token, token inválido/revogado, ou token de pessoa |
403 |
Token sem a permissão exigida pela rota |
404 |
Recurso inexistente, de outra organização, em rascunho/revisão, ou organização suspensa |
409 |
Evento não aceita inscrição aberta, ou regra de negócio impede |
422 |
Dados inválidos |
429 |
Limite de 60 req/min excedido |
Webhooks
Tipos de evento
| Tipo | Quando |
|---|---|
rsvp.status_changed |
Qualquer mudança de status de uma resposta (nova resposta, confirmação, fila, promoção, cancelamento, recusa, importação, aprovação, expiração de oferta) |
checkin.recorded |
Presença registrada |
checkin.reversed |
Check-in desfeito |
checkin.corrected |
Presença corrigida manualmente |
event.published |
Evento publicado |
event.closed |
Inscrições encerradas (manual ou por prazo vencido) |
event.completed |
Evento concluído |
event.cancelled |
Evento cancelado |
ping |
Teste manual na tela de integrações; não aparece entre os tipos assináveis |
Cada endpoint escolhe quais tipos assina; só recebe esses. ping é enviado apenas pelo botão de teste.
Requisição enviada
POST na URL cadastrada, Content-Type: application/json, corpo:
{
"id": "6f1c0c0e-3c1b-4a0e-9a5d-1f1d2c3b4a5e",
"type": "rsvp.status_changed",
"data": { }
}
| Cabeçalho | Valor |
|---|---|
X-Webhook-Id |
UUID da entrega, igual ao id do corpo e estável entre retentativas |
X-Webhook-Event |
o type |
X-Webhook-Timestamp |
segundos Unix do momento desta tentativa |
X-Webhook-Signature |
sha256= + HMAC-SHA256 hex (ver Assinatura) |
Corpo por tipo
data por tipo; <Evento> e <Resposta> são os mesmos objetos da API.
| Tipo | data |
|---|---|
event.published, event.closed, event.completed, event.cancelled |
{"event": <Evento>} |
rsvp.status_changed |
{"rsvp": <Resposta>, "previous_status": string | null}. rsvp.status é o status novo; previous_status é o anterior (null para a primeira resposta) |
checkin.recorded, checkin.reversed, checkin.corrected |
{"rsvp": <Resposta>, "checked_in": boolean} |
ping |
{"message": "ping"} |
O conteúdo é montado no momento em que a ação acontece, não no da entrega. Uma entrega atrasada por retentativas carrega o estado de quando o fato ocorreu.
Assinatura
X-Webhook-Signature = "sha256=" + hex( HMAC_SHA256( chave = segredo,
mensagem = X-Webhook-Timestamp + "." + corpo_bruto ) )
segredo: o valorwhsec_...mostrado ao cadastrar o webhook.corpo_bruto: os bytes exatos recebidos, sem reserializar.- Compare em tempo constante e rejeite timestamps antigos (recomendado: mais de 5 minutos). Exemplos em Verificar a assinatura.
Entrega e retentativas
| Parâmetro | Valor |
|---|---|
| Prazo de resposta | 10 segundos |
| Sucesso | resposta que não seja 4xx/5xx (na prática, responda 2xx) |
| Redirecionamento | não é seguido; um 3xx é tratado como entregue |
| Tentativas por entrega | 5 |
| Espera entre tentativas | 1 min, 5 min, 15 min, 1 h |
| Garantia | pelo menos uma vez; sem garantia de ordem |
| Desativação | após 5 entregas esgotadas seguidas (cada uma com suas 5 tentativas), o endpoint é desativado. Uma entrega bem-sucedida zera a contagem |
| Quando sai | só depois do commit da transação que originou o fato; fato revertido não gera webhook |
| Endpoint removido ou desativado | entregas pendentes são descartadas sem envio |
| Endereço deixou de ser seguro | a entrega falha imediatamente, sem requisição |
Não há histórico de entregas no painel nem reenvio automático de eventos perdidos.
Restrições de URL
- Esquema https obrigatório.
- Sem usuário/senha na URL (
https://user:pass@...). - Até 2048 caracteres.
- Todo endereço IP em que o host resolve precisa ser público. São rejeitados: loopback (
127.0.0.0/8,::1), redes privadas (10/8,172.16/12,192.168/16), link-local (169.254/16, incluindo169.254.169.254), faixas reservadas e IPv6 equivalentes, inclusive IPv4 embutido em IPv6 (::ffff:127.0.0.1). - Qualquer porta é aceita.
- A validação roda no cadastro e em cada entrega, com a conexão fixada nos endereços validados.
Administração
Tela: /admin/integracoes (papel admin da organização corrente; outros papéis recebem 403).
| Item | Regra |
|---|---|
| Nome do token | obrigatório, até 80 caracteres |
| Permissões do token | ao menos uma de events:read, rsvps:read, rsvps:write |
| Texto do token | exibido uma única vez |
| Segredo do webhook | whsec_ + 40 caracteres aleatórios, gerado pelo sistema, exibido uma única vez, guardado cifrado |
| Eventos do webhook | ao menos um dos tipos da tabela |
| Teste | botão Enviar teste enfileira um ping |
| Reativar webhook | não existe; remover e cadastrar de novo |
| Rotação de segredo | não existe; cadastrar um segundo webhook e remover o antigo |
Rotas (admin, sessão autenticada): GET /admin/integracoes, POST /admin/integracoes/tokens, DELETE /admin/integracoes/tokens/{id}, POST /admin/integracoes/webhooks, POST /admin/integracoes/webhooks/{id}/teste, DELETE /admin/integracoes/webhooks/{id}. Recurso de outra organização responde 404.
Auditoria
Registradas em /admin/auditoria, sem segredo e sem URL completa:
| Ação | Rótulo | Conteúdo guardado |
|---|---|---|
integration.token_created |
Token de API criado | nome do token |
integration.token_revoked |
Token de API revogado | nome do token |
webhook.created |
Webhook criado | host da URL |
webhook.deleted |
Webhook removido | host da URL |
Um host que é um endereço IP numérico pode aparecer mascarado ([telefone]) pelo filtro de dados pessoais da auditoria; com nome de domínio aparece normalmente.