Endpoints disponíveis

A API REST v1 do Syncro expõe 7 grupos de endpoints: leads, tasks, custom fields, pipelines, sequências, WhatsApp e webhooks. Todos sob /api/v1/*. Esse artigo cataloga cada endpoint com método, payload, response e filtros.

Pré-requisitos

• API Key gerada. Veja Gerar API Key.
• Header X-API-Key em todas as requisições.
• Base URL: https://app.syncro.chat/api/v1.

Convenções gerais

Headers obrigatórios

X-API-Key: crm_a1b2c3...
Content-Type: application/json
Accept: application/json

Formato de resposta

Todos os endpoints retornam JSON com estrutura padrão:

Sucesso:

{
 "success": true,
 "data": {... }
}

Listagem com paginação:

{
 "success": true,
 "data": [...],
 "meta": {
 "total": 150,
 "per_page": 50,
 "current_page": 1,
 "last_page": 3,
 "has_more": true
 }
}

Erro:

{
 "success": false,
 "error": "Mensagem descritiva",
 "code": "validation_error"
}

Status codes

Código	Significado
200	OK
201	Criado
400	Bad Request (payload mal formado)
401	API Key inválida/ausente
403	Sem permissão (scope insuficiente)
404	Recurso não encontrado
422	Erro de validação (campos faltando)
429	Rate limit (60 req/min)
500	Erro interno

Paginação

Todos os endpoints index aceitam:

• page (default 1).
• per_page (default 50, max 200).

Endpoints

Leads

GET /leads — Listar leads

Filtros:

Param	Tipo	Descrição
pipeline_id	int	Filtra pipeline
stage_id	int	Filtra etapa
assigned_to	int	User responsável
source	string	Origem (manual, whatsapp, etc)
status	string	active, archived, merged
tags	array	OR de tags
q	string	Busca em nome/e-mail/telefone
created_from	ISO date	Criados após
created_to	ISO date	Criados antes
updated_since	ISO date	Atualizados após (polling)

curl "https://app.syncro.chat/api/v1/leads?pipeline_id=1&per_page=20" \
 -H "X-API-Key: crm_..."

GET /leads/{id} — Detalhe

curl "https://app.syncro.chat/api/v1/leads/1234" \
 -H "X-API-Key: crm_..."

POST /leads — Criar lead

Veja Criar lead via API pra exemplos.

POST /leads/upsert — Criar ou atualizar

Match por email, phone ou email_or_phone.

{
 "name": "Maria Silva",
 "email": "[email protected]",
 "phone": "+5511999999999",
 "match_by": "email_or_phone"
}

Response: created: true (novo) ou false (atualizado).

PUT /leads/{id}/stage — Mover de etapa

{
 "stage_id": 7,
 "pipeline_id": 1
}

⚠️ Bloqueia se etapa atual tem tasks obrigatórias incompletas.

PUT /leads/{id}/won — Marcar ganho

{
 "stage_id": 15,
 "value": 10000
}

Cria registro em sales. Etapa precisa ter is_won=true.

PUT /leads/{id}/lost — Marcar perdido

{
 "stage_id": 20,
 "reason_id": 2
}

Cria registro em lost_sales. Etapa precisa ter is_lost=true.

DELETE /leads/{id} — Deletar

POST /leads/{id}/tags — Adicionar tags

{
 "tags": ["nova_tag", "vip"]
}

DELETE /leads/{id}/tags/{name} — Remover tag

curl -X DELETE "https://app.syncro.chat/api/v1/leads/1234/tags/lead-frio" \
 -H "X-API-Key: crm_..."

Tasks

GET /tasks — Listar

Filtros:

• lead_id
• assigned_to
• status (pending, completed)
• type (call, email, task, visit, whatsapp, meeting)
• priority (low, medium, high)
• due_from, due_to

GET /tasks/{id} — Detalhe

POST /tasks — Criar

{
 "subject": "Ligar para cliente",
 "description": "Follow-up sobre proposta",
 "type": "call",
 "priority": "high",
 "due_date": "2026-05-15",
 "due_time": "14:30",
 "lead_id": 1234,
 "assigned_to": 3
}

PUT /tasks/{id} — Atualizar (partial)

{
 "status": "completed"
}

Auto-popula completed_at = now quando muda pra completed.

PATCH /tasks/{id}/toggle — Alternar status

Pending ↔ Completed.

DELETE /tasks/{id} — Deletar

Custom Fields

GET /custom-fields — Listar definições

Filtros:

• active_only (boolean, default true).

{
 "success": true,
 "data": [
 {
 "id": 1,
 "name": "setor_atuacao",
 "label": "Setor de atuação",
 "field_type": "text",
 "is_required": false,
 "is_active": true,
 "options": null
 },
 {
 "id": 2,
 "name": "porte_empresa",
 "label": "Porte",
 "field_type": "select",
 "options": [
 { "value": "pequena", "label": "Pequena" },
 { "value": "media", "label": "Média" }
 ]
 }
 ]
}

Use pra descobrir quais custom fields você pode preencher em POST /leads.

Pipelines

GET /pipelines — Listar pipelines + stages + lost reasons

{
 "success": true,
 "pipelines": [
 {
 "id": 1,
 "name": "Vendas",
 "is_default": true,
 "stages": [
 { "id": 5, "name": "Lead novo", "is_won": false, "is_lost": false, "color": "#3B82F6" },
 { "id": 6, "name": "Qualificado", "is_won": false, "is_lost": false },
 { "id": 7, "name": "Negociação", "is_won": false, "is_lost": false },
 { "id": 8, "name": "Ganho", "is_won": true, "is_lost": false },
 { "id": 9, "name": "Perdido", "is_won": false, "is_lost": true }
 ]
 }
 ],
 "lost_reasons": [
 { "id": 1, "name": "Sem orçamento" },
 { "id": 2, "name": "Concorrente" }
 ]
}

Nurture Sequences

GET /nurture-sequences — Listar ativas

{
 "success": true,
 "data": [
 {
 "id": 1,
 "name": "Onboarding",
 "channel": "whatsapp",
 "is_active": true,
 "steps_count": 5
 }
 ]
}

POST /leads/{id}/enroll-sequence — Inscrever

{
 "sequence_id": 1
}

Idempotente (se já inscrito ativo, retorna 409 com enrollment_id existente).

DELETE /leads/{id}/enroll-sequence/{sequence_id} — Remover

WhatsApp

GET /whatsapp/instances — Listar instâncias

{
 "success": true,
 "data": [
 {
 "id": 1,
 "provider": "cloud_api",
 "display_name": "Vendas",
 "phone_number": "+5511999999999",
 "status": "connected",
 "is_primary": true,
 "supports_templates": true,
 "supports_buttons": true,
 "has_window_restriction": true
 }
 ]
}

GET /whatsapp/templates — Listar templates HSM

Filtros:

• instance_id
• status (default APPROVED).
• language (default todos).

POST /leads/{id}/send-whatsapp — Enviar mensagem

{
 "type": "text",
 "body": "Olá, tudo bem?",
 "instance_id": 1
}

Tipos:

• type=text: requer body.
• type=image: requer media_url + caption opcional.

⚠️ Cloud API com janela 24h fechada: retorna 422 com skip_reason: window_closed.

POST /leads/{id}/send-whatsapp-template — Enviar template

{
 "template_id": 1,
 "variables": ["João", "15/04/2026", "14:30"],
 "header_media_url": "https://...",
 "instance_id": 1
}

Veja Enviar template.

Webhooks

GET /webhooks — Listar subscriptions

{
 "success": true,
 "data": [
 {
 "id": 1,
 "target_url": "https://n8n.example.com/webhook/leads",
 "events": ["lead.created", "lead.updated"],
 "source": "n8n",
 "is_active": true,
 "failure_count": 0,
 "last_success_at": "2026-04-30T14:30:00Z",
 "last_failure_at": null
 }
 ]
}

POST /webhooks — Criar

{
 "target_url": "https://meusistema.com/webhook",
 "events": ["lead.created", "lead.won"],
 "source": "api",
 "secret": "opcional_meu_secret"
}

Response retorna secret (gerado automaticamente se não fornecido) — salve agora, não aparece mais.

Veja Webhooks de saída.

PUT /webhooks/{id} — Atualizar

{
 "is_active": false
}

DELETE /webhooks/{id} — Remover

Rate limit detalhado

• 60 requisições/minuto por API Key.
• Header de resposta: X-RateLimit-Remaining: N.
• Quando ultrapassa: 429 + Retry-After: 60.

# Pegando rate limit info
curl -i "https://app.syncro.chat/api/v1/leads" \
 -H "X-API-Key: crm_..." | grep -i "rate"

# Resposta inclui:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 45

Polling vs Webhooks

Pra dados que mudam frequentemente:

Polling (puxar dados periodicamente)

# A cada 5 min, busca leads atualizados
curl "https://app.syncro.chat/api/v1/leads?updated_since=2026-04-30T14:30:00Z" \
 -H "X-API-Key: crm_..."

❌ Inefficient — fica chamando mesmo sem dado novo.

Webhooks (Syncro notifica)

Configure subscription com eventos lead.created, lead.updated. Sistema envia POST pro seu endpoint quando algo muda.

✅ Eficiente — só recebe quando há mudança.

Veja Webhooks de saída.

Erros comuns

"Validation error: pipeline_id is required"

Campo obrigatório faltando. Confira payload contra documentação.

"Lead not found (404)"

ID não existe no seu tenant. API filtra automaticamente — IDs de outros tenants retornam 404.

"Conflict: Lead already enrolled"

POST /leads/{id}/enroll-sequence com lead já inscrito retorna 409. Trate no client.

"422 — Stage transition blocked: mandatory tasks pending"

Etapa atual tem tasks obrigatórias incompletas. Liste tasks com GET /tasks?lead_id=X&status=pending antes de mover.

Versionamento

API atual: v1. Mudanças breaking serão em v2 (futuro). Mantenha header Accept: application/json — versão é parte da URL.

Próximos passos

• Pra criar lead, veja Criar lead via API.
• Pra receber eventos, veja Webhooks de saída.

Artigos relacionados

• Gerar API Key
• Criar lead via API
• Webhooks de saída
• Assinatura HMAC
• n8n Community Node