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 valor whsec_... 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, incluindo 169.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.