Integrações

API e integrações do Riffas

A leitura de rifas ativas, categorias e da tabela de taxas é pública e não precisa de credencial. Esta página descreve os endpoints, a especificação OpenAPI, o servidor MCP e como pedir acesso autenticado.

OpenAPI Autenticação de agentes

API pública, sem credencial

Base: https://api.riffas.com.br/api/v1. Respostas em JSON com campos em snake_case; listagens vêm paginadas no formato do Laravel (data, meta, links).

Método	Endpoint	Descrição
GET	/raffles	Lista rifas públicas. Filtros: search, category_id, modality, status[], sort, per_page (máx. 200), page.
GET	/raffles/{slug}	Detalhe público de uma rifa.
GET	/raffles/{id}/prizes	Prêmios da rifa.
GET	/raffles/{id}/tickets/available	Números ainda disponíveis.
GET	/raffles/{id}/draw	Resultado do sorteio, quando houver.
GET	/categories	Categorias ativas (id, slug, name).
GET	/pricing-tiers	Faixas da taxa fixa de ativação.
GET	/ngo-raffles	Rifas de ONGs verificadas.
GET	/verified-ngos	ONGs verificadas.
GET	/producers/{slug}	Perfil público do produtor.
GET	/stats/public	Números agregados da plataforma.

Exemplo

curl "https://api.riffas.com.br/api/v1/raffles?status=active&search=iphone&per_page=12" \
  -H "Accept: application/json"

Limites

Endpoints públicos não exigem chave, mas têm limite de requisições por IP no backend.
per_page máximo de 200 na listagem de rifas.
Ordenação suportada: recent, ending_soon, price_asc e price_desc.
A página de compra da rifa fica na aplicação, em app.riffas.com.br/rifa/<slug>.

Servidor MCP

O mesmo conjunto de leituras está exposto como ferramentas MCP em /mcp (Streamable HTTP, sem credencial e sem estado). O card do servidor fica em /.well-known/mcp/server-card.json.

search_raffles

Busca rifas ativas por termo, categoria ou modalidade.

get_raffle

Detalha uma rifa pelo slug.

list_raffle_categories

Lista as categorias para filtrar.

list_pricing_tiers

Retorna a tabela da taxa fixa de ativação.

estimate_raffle_revenue

Simula arrecadação, taxa e líquido de uma rifa.

Chamada

curl -X POST "https://riffas.com.br/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_raffles","arguments":{"search":"iphone"}}}'

No navegador, as mesmas ferramentas são registradas em navigator.modelContext (WebMCP) em todas as páginas do site.

Caminhos autenticados

Token de produtor

Fluxo authorization code + PKCE (S256) para agir nos dados de um produtor, com o token no header Authorization: Bearer. A descoberta fica em /.well-known/oauth-authorization-server. Não há registro dinâmico de cliente.

API key de parceiro

A API de parceiros fica em https://api.riffas.com.br/api/external/v1 e usa X-Api-Key. As chaves são emitidas pela equipe do Riffas após análise — não há emissão automática.

Solicitar acesso

Escreva para contato@riffas.com.br com nome do serviço, responsável, finalidade, dados pretendidos e volume estimado. Os campos exigidos também estão em /auth.md.

Não existe API — pública ou autenticada — para movimentar valores. O pagamento é processado pelo gateway do próprio produtor e o dinheiro nunca passa pelo Riffas.

Descoberta para agentes

Qualquer página do site responde markdown quando o request pede Accept: text/markdown — o HTML continua o padrão para navegadores. A resposta traz Content-Type: text/markdown e x-markdown-tokens com a contagem aproximada.

curl "https://riffas.com.br/precos" -H "Accept: text/markdown"

Especificação OpenAPI

/docs/api/openapi.json

Catálogo de APIs (RFC 9727)

/.well-known/api-catalog

MCP Server Card

/.well-known/mcp/server-card.json

Índice de skills

/.well-known/agent-skills/index.json

Autenticação de agentes

/auth.md

Mapa do site para agentes

/llms.txt

Preferências de uso de conteúdo

/robots.txt

Dúvidas sobre a plataforma estão na central de ajuda.