API do Rino · v1

Integrar o Rino ao seu sistema

Quatro endereços, autenticação por chave e respostas em JSON. Serve para criar eventos a partir do seu próprio painel, puxar os números para o seu BI e embutir o criador de foto dentro do site do seu cliente.

As chaves

As chaves são criadas no painel do evento, na aba API e site, e aparecem uma única vez. Guardamos apenas o resumo criptográfico delas — nem nós conseguimos mostrar de novo. É o comportamento correto: um backup nosso que vazasse não viraria acesso à sua conta.

rino_sk_… (gestão)

Fica no seu servidor. Lê e escreve dados da conta. Nunca coloque no navegador: qualquer pessoa que abra o código-fonte da página a encontra.

rino_pk_… (pública)

Pode ficar no navegador, dentro do site do seu cliente. Só responde para os domínios que você cadastrar — chave pública sem lista de domínio é chave de qualquer um.

Envie no cabeçalho Authorization: Bearer <chave> ou em x-rino-key. O parâmetro ?key= também funciona, mas evite: endereço com chave dentro fica gravado em log de servidor e em histórico de navegador.

Os endereços

GET/api/v1/eventoschave de gestao

Lista os eventos da conta, do mais recente para o mais antigo (até 200).

Chamada

curl https://rinoavatar.com.br/api/v1/eventos \
  -H "Authorization: Bearer rino_sk_..."

Resposta

{
  "eventos": [
    {
      "id": "8081f700-1e8f-48ad-bff0-641a1e5cdc93",
      "endereco": "festa-julina",
      "url": "https://rinoavatar.com.br/festa-julina",
      "nome": "Festa Julina 2026",
      "protagonista": "Prefeitura de Exemplo",
      "tipo": "evento",
      "status": "active",
      "criado_em": "2026-06-01T12:00:00Z"
    }
  ]
}
POST/api/v1/eventoschave de gestao

Cria um evento. Nasce como rascunho — publicar continua sendo ação humana no painel.

nome
obrigatórioNome interno do evento. Mínimo 2 caracteres.
endereco
O endereço público. Sem ele, é derivado do nome. Se já existir, a resposta é 409.

Chamada

curl -X POST https://rinoavatar.com.br/api/v1/eventos \
  -H "Authorization: Bearer rino_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"nome":"Festa Julina 2026","endereco":"festa-julina"}'

Resposta

{
  "id": "8081f700-...",
  "endereco": "festa-julina",
  "url": "https://rinoavatar.com.br/festa-julina",
  "nome": "Festa Julina 2026",
  "status": "draft"
}
GET/api/v1/relatoriochave de gestao

Os números do evento, agregados — os mesmos do relatório em PDF.

evento
obrigatórioO id ou o endereço público do evento.
dias
Janela de apuração. Padrão 90, mínimo 1, máximo 365.

Chamada

curl "https://rinoavatar.com.br/api/v1/relatorio?evento=festa-julina&dias=30" \
  -H "Authorization: Bearer rino_sk_..."

Resposta

{
  "evento": { "nome": "...", "slug": "festa-julina", ... },
  "uso": { "visitas": 4210, "geracoes": 1240, "downloads": 980, ... },
  "funil": { "abriu": 4210, "gerou": 1240, "baixou": 980, ... },
  "mural": { "publicadas": 610, "aprovadas": 604, "no_telao": 588 },
  "telao": { "minutos": 312, "fotos_exibidas": 5840 },
  "patrocinadores": [ { "nome": "...", "exposicoes": 1240, "cliques": 87 } ]
}
GET/api/v1/embedchave de publica

Confere se o domínio pode usar a chave e devolve o endereço para embutir o criador de foto no site do cliente.

evento
obrigatórioO endereço público do evento.

Chamada

fetch('https://rinoavatar.com.br/api/v1/embed?evento=festa-julina', {
  headers: { 'x-rino-key': 'rino_pk_...' },
}).then((r) => r.json())

Resposta

{
  "evento": "festa-julina",
  "nome": "Festa Julina 2026",
  "url": "https://rinoavatar.com.br/festa-julina?embed=1"
}

Erros

401Chave ausente, inválida ou revogada.
403Chave do escopo errado, ou domínio fora da lista (chave pública).
404O evento não existe — ou existe e é de outra conta. A resposta é a mesma de propósito: dizer "existe, mas não é sua" entregaria a existência do evento de um concorrente.
409O endereço público pedido já está em uso.
422Falta um parâmetro obrigatório ou ele está fora do formato.

O corpo do erro é sempre { "erro": "mensagem" }. As mensagens são escritas para quem está integrando, não para o público final.

O que a API ainda não faz

  • Não publica evento. Publicar é ação humana no painel, com a lista de conferência antes. Um evento publicado sem moldura e sem aviso de imagem vira problema jurídico, não bug.
  • Não sobe moldura nem arte. Arquivo entra pelo painel, onde o enquadramento é conferido na hora.
  • Não entrega foto de participante. Nem por chave de gestão. As fotos têm prazo, autorização vinculada e endereço assinado de curta duração — é o que a nossa política de privacidade promete, e API que contornasse isso tornaria a promessa falsa.
  • Não tem webhook de saída ainda. Para saber de evento novo, consulte. Integração de leads com CRM existe, mas é configurada no painel, não pela API.
  • Não tem limite de chamadas publicado. Não porque não haja proteção — há —, mas porque ainda não medimos o número que valeria escrever aqui. Prefira consultar a cada minutos, e não a cada segundo.

Versão

O caminho carrega a versão (/api/v1/). Mudança que quebre integração existente vai para /api/v2/ — a v1 não muda de comportamento debaixo de quem já está usando. Campo novo numa resposta não conta como quebra: escreva o seu código para ignorar o que não conhece.