Documentação da API
Conecte o GiaFlow aos seus sistemas: crie manuais, envie capturas da extensão, gerencie equipe e faturamento programaticamente.
Autenticação
Existem dois tipos de acesso:
| Tipo | Como usar |
|---|---|
| Sessão | Cookies do login (Google). Usado pelo painel. |
| API Key | Header x-api-key: SUA_CHAVE — chave da equipe, disponível em Configurações. Usado pela extensão e integrações. |
Guias
GET /api/guides
Lista os guias da equipe (mais recentes primeiro).
POST /api/guides
Cria um guia manual com passos:
{
"title": "Como cadastrar um cliente",
"description": "Passo a passo do cadastro",
"steps": [
{ "order": 1, "title": "Acesse o sistema", "description": "Abra app.empresa.com" }
]
}GET /api/guides/:id
Retorna o guia completo com os passos ordenados.
PUT /api/guides/:id
Atualiza título, descrição, status ou steps (substitui os passos).
DELETE /api/guides/:id
Exclui o guia e seus passos.
Extensão / Captura
POST /api/extension/upload
Envia passos capturados pela extensão. Salva screenshots e, opcionalmente, gera o guia com IA.
curl -X POST https://giaflow.com.br/api/extension/upload \
-H "Content-Type: application/json" \
-H "x-api-key: SUA_CHAVE" \
-d '{
"title": "Como exportar um relatório",
"generate": true,
"steps": [
{
"order": 1,
"actionType": "click",
"elementText": "Relatórios",
"selector": "#relatorios",
"url": "https://app.empresa.com",
"screenshot": "data:image/png;base64,...."
}
]
}'| Campo | Tipo | Descrição |
|---|---|---|
| order | int | Ordem do passo (1-based) |
| actionType | string | click, type, select, navigate, scroll, upload |
| elementText | string | Texto/rótulo do elemento |
| selector | string | Seletor CSS aproximado |
| url | string | URL da página no momento da captura |
| screenshot | string | DataURL PNG/JPEG da tela visível |
IA
POST /api/ai/generate
Com { steps: [...] } retorna o guia gerado. Com { guideId: "..." } regenera e salva no guia existente.
Faturamento
GET /api/billing
Retorna subscription, invoices, role e team.
POST /api/billing/checkout
Inicia o checkout. Redirecione o usuário para a URL retornada.
{ "plan": "pro", "interval": "month", "provider": "stripe" }plan: pro | business · interval: month | year · provider: stripe (cartão) | mercadopago (Pix/boleto)
POST /api/billing/invoices
Faturamento manual (admin): cria a fatura, gera link Pix e envia o e-mail via ByteSend.
{ "email": "cliente@empresa.com", "description": "Consultoria", "amountCents": 19900, "withPix": true, "sendEmail": true }POST /api/billing/portal
Abre o portal do Stripe para gerenciar/cancelar a assinatura.
Equipe
| Método | Endpoint | Descrição |
|---|---|---|
| GET | /api/team/members | Lista membros, convites pendentes e me |
| POST | /api/team/members | Envia convite { email, role } |
| PATCH | /api/team/members | Altera função { userId, role } |
| DELETE | /api/team/members | Remove membro { userId } |
| PATCH | /api/team | Atualiza equipe { name, logoUrl, primaryColor, billingEmail, regenApiKey } |
| GET | /api/team/join?token=... | Aceita convite (após login Google) |
Integrações
POST /api/integrations/notion/publish
Cria uma página no banco do Notion com os passos e screenshots.
{ "guideId": "cuid_do_guia" }POST /api/email/send
Envia e-mails transacionais (admin). Templates: welcome, trialStarted, invoicePaid, manualInvoice, invite, paymentFailed, guideReady.
{ "to": "cliente@email.com", "subject": "Sua nota fiscal", "template": "manualInvoice", "data": { "name": "João", "number": "INV-2026-0001", "amount": "R$ 199,00" } }Webhooks
| Endpoint | Evento |
|---|---|
| POST /api/webhooks/stripe | checkout.session.completed, invoice.paid, invoice.payment_failed |
| POST /api/webhooks/mercadopago | payment (approved) — assinaturas e Pix manual |
Erros
Erros retornam { "error": "mensagem em português" } com status: