Visão geral da API

A API do Vendee é REST sobre HTTP, com corpo JSON em request e response.

Base URL e endpoints

Cada recurso é uma função na infraestrutura Supabase do seu projeto. A URL base tem o formato:

https://<seu-projeto>.supabase.co/functions/v1

Nesta documentação ela aparece como {BASE_URL}. Os endpoints disponíveis:

Recursos com :id (ex.: um negócio específico) usam o id no path: {BASE_URL}/api-v1-deals/<uuid>. Ações ficam no segmento seguinte: {BASE_URL}/api-v1-deals/<uuid>/win.

Versionamento

A versão atual é a v1 (refletida no nome das funções, api-v1-*). Mudanças que quebram contrato sobem a versão major. Acréscimos compatíveis (novos campos opcionais na resposta) podem entrar sem nova versão — escreva clientes tolerantes a campos extras.

Formato de dados

• Content-Type: application/json em request e response.
• Campos: snake_case em inglês (first_name, expected_close_date).
• Enums: valores em português (status: "ganho", "perdido", "aberto").
• Datas/horários: timestamps são ISO 8601 em UTC com sufixo Z (2026-06-27T12:00:00.000Z). Campos de data pura (ex.: expected_close_date) usam YYYY-MM-DD.
• Dinheiro: números (value, recurring_value), sem símbolo de moeda.

Paginação (endpoints de lista)

Os GET de lista (deals, contacts, companies) usam paginação por cursor e devolvem o envelope:

{
  "data": [ /* registros */ ],
  "meta": { "next_cursor": "f1e2...", "has_more": true }
}

• limit — quantos registros por página. Padrão 50, máximo 200 (valores acima são reduzidos a 200).
• cursor — para a próxima página, passe o meta.next_cursor da resposta anterior em ?cursor=.... Quando has_more for false, next_cursor vem null.
• since — filtro por data de criação (ISO 8601): retorna só registros com created_at >= since.

Exemplo de varredura:

# primeira página
curl "{BASE_URL}/api-v1-deals?limit=100" -H "X-API-Key: vnd_..."
# próxima página
curl "{BASE_URL}/api-v1-deals?limit=100&cursor=f1e2..." -H "X-API-Key: vnd_..."

GET /pipelines não pagina — retorna todos os pipelines ativos do workspace de uma vez.

Limites e boas práticas

• Idempotência. No POST /leads, envie um external_id para que reenvios (timeout de rede, retry automático) não criem registros duplicados — a mesma chave devolve o registro original com "idempotent": true.
• Volume. Hoje a API não impõe um limite de requisições por chave. Em cenários de alto volume, espace as requisições no cliente e evite loops sem intervalo — atente que uma única chamada a /leads pode criar até três registros (empresa, contato e negócio). Limites por chave (com resposta 429) podem ser introduzidos no futuro; escreva clientes que respeitem um eventual cabeçalho Retry-After.
• Tamanho do corpo. custom_fields aceita no máximo 50 chaves e 10 KB por requisição.
• Menor privilégio. Dê à chave apenas os escopos necessários (veja Chaves e escopos) — assim o raio de impacto de um eventual vazamento fica restrito ao que aqueles escopos permitem.

Nesta seção