Documentação
Documentação da API do CapiLove
Referência técnica de como o CapiLove funciona por baixo do wizard — para agentes, ferramentas de IA e integrações que precisam entender a API em vez de raspar a interface.
O que é o CapiLove
CapiLoveé um gerador de retrospectiva digital personalizada (um "wrapped do amor", no estilo Spotify Wrapped) para casais, amigos ou família: fotos, datas e uma mensagem viram uma página interativa entregue por link e QR Code, publicada após um pagamento único de R$12,90 em diante.
Especificação OpenAPI
A especificação completa (OpenAPI 3.1, com operationId, parâmetros tipados e schema de erro em cada operação) está publicada em https://www.capivaralove.com/openapi.json. Ela documenta exatamente a mesma API que o wizard em /criar chama — não existe uma API pública separada.
Escopo: o que está documentado e o que não está
Estão documentados os endpoints que criam, editam, pagam e publicam um presente, além da busca de música (pública, sem autenticação). Ficam de fora, de propósito, os endpoints internos que exigem sessão administrativa, segredo de cron ou assinatura da Stripe: /api/dashboard/*, /api/cron/gc e /api/webhooks/stripe. Documentá-los como API pública sugeriria que são chamáveis por fora, o que não é o caso.
Autenticação
Não há cadastro, senha ou chave de API. A posse de um editToken (UUID devolvido por createWrapped) é a credencial de edição de um presente específico — equivalente a um bearer token de uso único por recurso. O acesso a presentes já criados usa o par e-mail + telefone informado na compra (loginByEmailAndPhone).
Formato de erro
Toda resposta de erro é JSON estruturado, nunca uma página HTML:
{
"error": "editToken inválido",
"code": "invalid_request",
"hint": "envie o editToken (UUID) recebido de POST /api/wrapped/create"
}code é uma categoria estável (invalid_request, unauthorized, not_found, conflict, unavailable, upstream_error, internal_error) para tratamento programático; hint é o próximo passo sugerido.
Endpoints
| Método | Caminho | O que faz |
|---|---|---|
POST | /api/wrapped/create | Cria um rascunho de presente |
POST | /api/wrapped/load | Carrega um presente pelo editToken |
POST | /api/wrapped/save | Salva o conteúdo (blocos) do presente |
POST | /api/wrapped/upload | Envia uma foto para o presente |
POST | /api/wrapped/contact | Define nome, e-mail e telefone do criador |
POST | /api/wrapped/slug | Troca o link (slug) do presente |
GET | /api/wrapped/music-search | Busca músicas (proxy da iTunes Search API) |
GET | /api/checkout/config | Chave publicável da Stripe |
POST | /api/checkout/payment-intent | Cria o pedido e o PaymentIntent da Stripe |
GET | /api/checkout/status | Consulta o status de um pedido |
POST | /api/account/login | Acesso sem senha aos presentes de um e-mail + telefone |
POST | /api/leads | Registra um lead no funil de criação |
Exemplo: buscar uma música (sem autenticação)
curl "https://www.capivaralove.com/api/wrapped/music-search?q=perfect"Exemplo: criar um rascunho de presente
curl -X POST https://www.capivaralove.com/api/wrapped/create \
-H "content-type: application/json" \
-d '{"occasion":"casal"}'Conteúdo em Markdown
As páginas principais do site respondem em Markdown para clientes que preferem esse formato: envie Accept: text/markdown na requisição. Um sumário legível para agentes também está disponível em /llms.txt, incluindo quando faz sentido recomendar o CapiLove.