{ "openapi": "3.1.0", "info": { "title": "Syncro API", "version": "1.0.0", "summary": "Public REST API for the Syncro commercial-automation CRM.", "description": "Programmatic access to the Syncro CRM: create and update leads, move deals through the pipeline, manage tasks, send WhatsApp messages, configure automations and chatbots, and subscribe to webhooks. Authenticate with an API key in the `X-API-Key` header. List endpoints return `{ \"data\": [...], \"meta\": {...} }`; single-resource endpoints return `{ \"success\": true, ... }`. Errors always carry a top-level `message`. Rate limit: 60 requests per minute per API key; a `429` includes `Retry-After`. Each API key carries scopes (see `x-scopes`); an operation states the one it needs in `x-required-scope`, and a missing scope returns `403` with `required_permission`. The API is versioned in the URL path (`/api/v1`); breaking changes ship as a new version and deprecations are announced with `Deprecation` and `Sunset` response headers — policy at https://docs.syncro.chat/en/versioning. Full guides and an MCP server are documented at https://docs.syncro.chat.", "termsOfService": "https://syncro.chat/termos-de-uso", "contact": { "name": "Syncro", "url": "https://syncro.chat" }, "license": { "name": "Proprietary", "url": "https://syncro.chat/termos-de-uso" } }, "servers": [ { "url": "https://app.syncro.chat/api/v1", "description": "Production" } ], "externalDocs": { "description": "Syncro API documentation", "url": "https://docs.syncro.chat" }, "tags": [ { "name": "Leads", "description": "Endpoints to create, fetch, update and move leads (deals) through the pipeline, plus tags, sequences and per-lead WhatsApp sending." }, { "name": "Pipelines & stages", "description": "Discover the pipeline and stage IDs used when creating and moving leads (plus the lost reasons) and create, update, delete or install ready-made pipelines. Read = pipelines:read · write = pipelines:write." }, { "name": "Custom fields", "description": "Lists the account custom field definitions. Use the **names** (name) returned here as keys of the custom_fields object when creating/updating leads." }, { "name": "Nurture sequences", "description": "List your account nurture sequences." }, { "name": "Tasks", "description": "Task CRUD. A task can be linked to a lead or standalone." }, { "name": "WhatsApp", "description": "List connected WhatsApp numbers and approved official templates. Sending messages is done through the Leads endpoints." }, { "name": "Account", "description": "Read your account data and the list of users." }, { "name": "Webhooks", "description": "Subscribe to events and receive real-time notifications at your URL, with every delivery signed via HMAC." }, { "name": "Automations", "description": "Create, read, change and activate automations programmatically. An automation runs **actions** (apply a tag, move a stage, send a WhatsApp message, create a task, call a webhook…) when a **trigger** happens (lead created, message received, stage changed, date, recurrence…). Reading requires the automations:read permission; writing requires automations:write." }, { "name": "Chatbots (flows)", "description": "Read, create, update and activate chatbot flows for WhatsApp, Instagram and website chat. A flow is a graph of nodes (message, question with options, condition, business hours, action, delay, end…). Reading requires chatbots:read; writing requires chatbots:write." } ], "security": [ { "ApiKeyAuth": [] } ], "x-scopes": { "automations:read": "Read automations.", "automations:write": "Create, update and delete automations.", "chatbots:read": "Read chatbot flows.", "chatbots:write": "Create, update and delete chatbot flows.", "custom_fields:read": "Read custom fields.", "leads:read": "Read leads.", "leads:write": "Create, update and delete leads.", "pipelines:read": "Read pipelines and stages.", "pipelines:write": "Create, update and delete pipelines and stages.", "sequences:read": "Read nurture sequences.", "sequences:write": "Create, update and delete nurture sequences.", "tasks:read": "Read tasks.", "tasks:write": "Create, update and delete tasks.", "users:read": "Read account and users.", "webhooks:read": "Read webhook subscriptions.", "webhooks:write": "Create, update and delete webhook subscriptions.", "whatsapp:read": "Read WhatsApp instances, messages and templates.", "whatsapp:write": "Create, update and delete WhatsApp instances, messages and templates." }, "x-rate-limit": { "limit": 60, "window_seconds": 60, "scope": "api_key", "response_status": 429, "retry_header": "Retry-After", "documentation": "https://docs.syncro.chat/en/errors" }, "x-deprecation-policy": { "versioning": "url-path", "current_version": "v1", "headers": [ "Deprecation", "Sunset" ], "documentation": "https://docs.syncro.chat/en/versioning" }, "paths": { "/leads": { "get": { "operationId": "getLeads", "summary": "List leads", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "phone": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "value": { "type": "integer" }, "source": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "pipeline_id": { "type": "integer" }, "stage_id": { "type": "integer" }, "stage": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "pipeline": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "created_at": { "type": "string" }, "custom_fields": { "type": "object", "properties": {} }, "assigned_to": { "type": "integer" }, "owner": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" } } } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "example": { "success": true, "data": [ { "id": 123, "name": "João Silva", "phone": "+5511999887766", "email": "joao@exemplo.com", "company": "ACME", "value": 5000, "source": "site", "tags": [ "vip" ], "pipeline_id": 1, "stage_id": 5, "stage": { "id": 5, "name": "Proposta" }, "pipeline": { "id": 1, "name": "Vendas" }, "created_at": "2026-06-30T10:00:00Z", "custom_fields": {}, "assigned_to": 12, "owner": { "id": 12, "name": "Ana", "email": "ana@empresa.com" } } ], "meta": { "total": 250, "per_page": 2, "current_page": 1, "last_page": 125, "has_more": true } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the account leads, paginated, with filters. Requires the `leads:read` scope.", "x-required-scope": "leads:read", "parameters": [ { "name": "pipeline_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filters by pipeline", "example": 1 }, { "name": "stage_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filters by stage" }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filters by the assignee ID" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters by source" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters by status" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Tags (names); returns leads with **any** of them" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name, email or phone" }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Only leads changed from this date on (ideal for sync)" }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Created from" }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Created until" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page (default 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page (default 50, max 200)", "example": 2 }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Extra relations separated by comma (see below)", "example": "owner" } ] }, "post": { "operationId": "postLeads", "summary": "Create lead", "tags": [ "Leads" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "pipeline_id": { "type": "integer" }, "stage_id": { "type": "integer" }, "stage": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "pipeline": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "created_at": { "type": "string" }, "custom_fields": { "type": "object", "properties": { "tamanho_empresa": { "type": "string" } } } } } } }, "example": { "success": true, "lead": { "id": 123, "name": "João Silva", "pipeline_id": 1, "stage_id": 5, "stage": { "id": 5, "name": "Proposta" }, "pipeline": { "id": 1, "name": "Vendas" }, "created_at": "2026-06-30T10:00:00Z", "custom_fields": { "tamanho_empresa": "100+" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Creates a new lead. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Lead name" }, "pipeline_id": { "type": "integer", "description": "Target pipeline" }, "stage_id": { "type": "integer", "description": "Target stage" }, "phone": { "type": "string", "description": "Phone (E.164 recommended)" }, "email": { "type": "string", "description": "Email" }, "value": { "type": "number", "description": "Deal value" }, "source": { "type": "string", "description": "Source" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags" }, "notes": { "type": "string", "description": "Notes" }, "utm_source / utm_medium / utm_campaign / utm_term / utm_content": { "type": "string", "description": "UTMs" }, "assigned_to": { "type": "integer", "description": "Assignee user ID (from the same account)" }, "custom_fields": { "type": "object", "description": "Map field_name: value (see [Custom fields](/en/custom-fields))" } }, "required": [ "name", "pipeline_id", "stage_id" ] }, "example": { "name": "João Silva", "phone": "+5511999887766", "email": "joao@exemplo.com", "value": 5000, "source": "site", "tags": [ "vip" ], "pipeline_id": 1, "stage_id": 5, "assigned_to": 12, "custom_fields": { "tamanho_empresa": "100+" } } } } } } }, "/leads/upsert": { "post": { "operationId": "postLeadsUpsert", "summary": "Create or update lead (upsert)", "tags": [ "Leads" ], "responses": { "201": { "description": "201 if created, 200 if updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "created": { "type": "boolean" }, "lead": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "stage_id": { "type": "integer" } } } } }, "example": { "success": true, "created": true, "lead": { "id": 123, "name": "João Silva", "stage_id": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Creates a new lead **or** updates an existing one, matching by email and/or phone. Ideal for synchronization. Accepts the same fields as POST /leads, plus the field below. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "match_by": { "type": "string", "description": "email, phone or email_or_phone (default email_or_phone)" } } }, "example": { "name": "João Silva", "email": "joao@exemplo.com", "pipeline_id": 1, "stage_id": 5, "match_by": "email" } } } } } }, "/leads/{id}": { "get": { "operationId": "getLeadsById", "summary": "Fetch lead by ID", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "stage_id": { "type": "integer" } } } } }, "example": { "success": true, "lead": { "id": 123, "name": "João Silva", "stage_id": 5 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns a lead. Accepts ?include= to load relations. Requires the `leads:read` scope.", "x-required-scope": "leads:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ] }, "delete": { "operationId": "deleteLeadsById", "summary": "Delete lead", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Removes the lead. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ] } }, "/leads/{id}/stage": { "put": { "operationId": "putLeadsByIdStage", "summary": "Move lead to another stage", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" } } }, "example": { "success": true, "lead_id": 123 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Moves the lead to another stage (and pipeline). Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "type": "integer", "description": "New stage" }, "pipeline_id": { "type": "integer", "description": "Stage pipeline" } }, "required": [ "stage_id", "pipeline_id" ] }, "example": { "stage_id": 7, "pipeline_id": 1 } } } } } }, "/leads/{id}/won": { "put": { "operationId": "putLeadsByIdWon", "summary": "Mark as won", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" } } }, "example": { "success": true, "lead_id": 123 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Moves the lead to a **won** stage and records the sale. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "type": "integer", "description": "Won stage (must have is_won = true)" }, "value": { "type": "number", "description": "Sale value (if omitted, uses the lead value)" } }, "required": [ "stage_id" ] }, "example": { "stage_id": 10, "value": 7500 } } } } } }, "/leads/{id}/lost": { "put": { "operationId": "putLeadsByIdLost", "summary": "Mark as lost", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" } } }, "example": { "success": true, "lead_id": 123 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Moves the lead to a **lost** stage and records the reason. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "stage_id": { "type": "integer", "description": "Lost stage (must have is_lost = true)" }, "reason_id": { "type": "integer", "description": "Lost reason ID (see lost_reasons in [Pipelines](/en/pipelines))" } }, "required": [ "stage_id" ] }, "example": { "stage_id": 11, "reason_id": 3 } } } } } }, "/leads/{id}/tags": { "post": { "operationId": "postLeadsByIdTags", "summary": "Add tags", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "success": true, "lead_id": 123, "tags": [ "vip", "enterprise" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Adds tags to the lead (keeps the existing ones). Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" }, "description": "Tag names (min. 1)" } }, "required": [ "tags" ] }, "example": { "tags": [ "vip", "enterprise" ] } } } } } }, "/leads/{id}/tags/{name}": { "delete": { "operationId": "deleteLeadsByIdTagsByName", "summary": "Remove a tag", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" }, "tags": { "type": "array", "items": { "type": "string" } } } }, "example": { "success": true, "lead_id": 123, "tags": [ "enterprise" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Removes a tag by name. Requires the `leads:write` scope.", "x-required-scope": "leads:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" }, { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The name.", "example": "vip" } ] } }, "/leads/{id}/enroll-sequence": { "post": { "operationId": "postLeadsByIdEnrollSequence", "summary": "Enroll in nurture sequence", "tags": [ "Leads" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "lead_sequence_id": { "type": "integer" }, "status": { "type": "string" }, "next_step_at": { "type": "string" } } }, "example": { "success": true, "lead_id": 123, "sequence_id": 1, "lead_sequence_id": 45, "status": "active", "next_step_at": "2026-07-01T10:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Enrolls the lead in an active sequence. See the list of sequences in [Sequences](/en/sequences). Requires the `sequences:write` scope.", "x-required-scope": "sequences:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sequence_id": { "type": "integer", "description": "Sequence ID (must be active)" } }, "required": [ "sequence_id" ] }, "example": { "sequence_id": 1 } } } } } }, "/leads/{id}/enroll-sequence/{sequence}": { "delete": { "operationId": "deleteLeadsByIdEnrollSequenceBySequence", "summary": "Remove from sequence", "tags": [ "Leads" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "lead_id": { "type": "integer" }, "sequence_id": { "type": "integer" }, "status": { "type": "string" } } }, "example": { "success": true, "lead_id": 123, "sequence_id": 1, "status": "exited_manual" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Removes the lead from a sequence. Requires the `sequences:write` scope.", "x-required-scope": "sequences:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" }, { "name": "sequence", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The sequence.", "example": "1" } ] } }, "/leads/{id}/send-whatsapp": { "post": { "operationId": "postLeadsByIdSendWhatsapp", "summary": "Send WhatsApp (text or image)", "tags": [ "Leads" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversation_id": { "type": "integer" }, "message_id": { "type": "integer" }, "provider_msg_id": { "type": "string" } } }, "example": { "success": true, "conversation_id": 99, "message_id": 456, "provider_msg_id": "wamid.xyz123" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Sends a text or image message to the lead phone. See connected numbers in [WhatsApp](/en/whatsapp). Requires the `whatsapp:write` scope.", "x-required-scope": "whatsapp:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "text or image" }, "body": { "type": "string", "description": "Message text (required if there is no media_url) (conditional)" }, "media_url": { "type": "string", "description": "Image URL (required when type=image) (conditional)" }, "caption": { "type": "string", "description": "Image caption" }, "instance_id": { "type": "integer", "description": "Number to use (if omitted, uses the main one)" } }, "required": [ "type" ] }, "example": { "type": "text", "body": "Olá! Tudo bem?", "instance_id": 1 } } } } } }, "/leads/{id}/send-whatsapp-template": { "post": { "operationId": "postLeadsByIdSendWhatsappTemplate", "summary": "Send template (HSM)", "tags": [ "Leads" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "conversation_id": { "type": "integer" }, "message_id": { "type": "integer" }, "provider_msg_id": { "type": "string" }, "template_name": { "type": "string" } } }, "example": { "success": true, "conversation_id": 99, "message_id": 457, "provider_msg_id": "wamid.xyz456", "template_name": "lembrete_proposta" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Sends an approved official template (required outside the 24h window on the Official API). See templates in [WhatsApp](/en/whatsapp). Requires the `whatsapp:write` scope.", "x-required-scope": "whatsapp:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_id": { "type": "integer", "description": "Template ID (must be APPROVED)" }, "variables": { "type": "array", "items": { "type": "string" }, "description": "Body variables, in order" }, "header_media_url": { "type": "string", "description": "Header media, when the template requires it" }, "instance_id": { "type": "integer", "description": "Number to use" } }, "required": [ "template_id" ] }, "example": { "template_id": 1, "variables": [ "João", "Proposta", "30/07" ], "instance_id": 2 } } } } } }, "/pipelines": { "get": { "operationId": "getPipelines", "summary": "List pipelines and stages", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "pipelines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": "string" }, "is_won": { "type": "boolean" }, "is_lost": { "type": "boolean" } } } } } } }, "lost_reasons": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } }, "example": { "success": true, "pipelines": [ { "id": 1, "name": "Vendas", "stages": [ { "id": 5, "name": "Prospecção", "color": "#FF6B6B", "is_won": false, "is_lost": false }, { "id": 6, "name": "Proposta", "color": "#4ECDC4", "is_won": false, "is_lost": false }, { "id": 10, "name": "Ganho", "color": "#95E1D3", "is_won": true, "is_lost": false }, { "id": 11, "name": "Perdido", "color": "#9CA3AF", "is_won": false, "is_lost": true } ] } ], "lost_reasons": [ { "id": 1, "name": "Preço alto" }, { "id": 3, "name": "Escolheu concorrente" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns all account pipelines with their stages (in order) and the list of lost reasons. Requires the `pipelines:read` scope.", "x-required-scope": "pipelines:read" }, "post": { "operationId": "postPipelines", "summary": "Create pipeline", "tags": [ "Pipelines & stages" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "warnings": { "type": "array", "items": {} }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "is_default": { "type": "boolean" }, "stage_count": { "type": "integer" }, "lead_count": { "type": "integer" }, "spec": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "auto_create_from_whatsapp": { "type": "boolean" }, "auto_create_from_instagram": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "is_won": { "type": "boolean" }, "is_lost": { "type": "boolean" }, "required_tasks": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "task_type": { "type": "string" }, "priority": { "type": "string" } } } } } } } } } } } } }, "example": { "success": true, "warnings": [], "data": { "id": 7, "is_default": false, "stage_count": 3, "lead_count": 0, "spec": { "name": "Funil de Vendas", "color": "#007DFF", "auto_create_from_whatsapp": false, "auto_create_from_instagram": false, "stages": [ { "name": "Novo", "is_won": false, "is_lost": false, "required_tasks": [ { "subject": "Ligar", "task_type": "call", "priority": "high" } ] }, { "name": "Ganho", "is_won": true, "is_lost": false, "required_tasks": [] }, { "name": "Perdido", "is_won": false, "is_lost": true, "required_tasks": [] } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `pipelines:write` scope.", "x-required-scope": "pipelines:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Pipeline name. If it already exists, returns 422 name_conflict" }, "stages": { "type": "array", "items": { "type": "string" }, "description": "Pipeline stages, in order" }, "stages[].name": { "type": "string", "description": "Stage name (the key PUT uses to match stages)" }, "stages[].is_won": { "type": "boolean", "description": "Marks the won stage" }, "stages[].is_lost": { "type": "boolean", "description": "Marks the lost stage" }, "stages[].required_tasks": { "type": "array", "items": { "type": "string" }, "description": "Required tasks of the stage: { subject, task_type, priority } (matched by subject on PUT)" }, "color": { "type": "string", "description": "Pipeline color (hex)" }, "auto_create_from_whatsapp": { "type": "boolean", "description": "Automatically captures WhatsApp leads. Defaults to false via API" }, "auto_create_from_instagram": { "type": "boolean", "description": "Automatically captures Instagram leads. Defaults to false via API" }, "validate_only": { "type": "boolean", "description": "Dry-run: validates and returns errors/warnings without writing anything" } }, "required": [ "name", "stages", "stages[].name" ] }, "example": { "name": "Funil de Vendas", "stages": [ { "name": "Novo", "required_tasks": [ { "subject": "Ligar", "task_type": "call", "priority": "high" } ] }, { "name": "Ganho", "is_won": true }, { "name": "Perdido", "is_lost": true } ] } } } } } }, "/pipelines/{id}": { "get": { "operationId": "getPipelinesById", "summary": "Fetch a pipeline", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "is_default": { "type": "boolean" }, "stage_count": { "type": "integer" }, "lead_count": { "type": "integer" }, "spec": { "type": "object", "properties": { "name": { "type": "string" }, "color": { "type": "string" }, "auto_create_from_whatsapp": { "type": "boolean" }, "auto_create_from_instagram": { "type": "boolean" }, "stages": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "is_won": { "type": "boolean" }, "is_lost": { "type": "boolean" }, "required_tasks": { "type": "array", "items": { "type": "object", "properties": { "subject": { "type": "string" }, "task_type": { "type": "string" }, "priority": { "type": "string" } } } } } } } } } } } } }, "example": { "success": true, "data": { "id": 1, "is_default": true, "stage_count": 3, "lead_count": 128, "spec": { "name": "Funil de Vendas", "color": "#007DFF", "auto_create_from_whatsapp": false, "auto_create_from_instagram": false, "stages": [ { "name": "Novo", "is_won": false, "is_lost": false, "required_tasks": [ { "subject": "Ligar", "task_type": "call", "priority": "high" } ] }, { "name": "Ganho", "is_won": true, "is_lost": false, "required_tasks": [] }, { "name": "Perdido", "is_won": false, "is_lost": true, "required_tasks": [] } ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the pipeline status plus the re-importable spec (the same object accepted in POST/PUT). Requires the `pipelines:read` scope.", "x-required-scope": "pipelines:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "1" } ] }, "put": { "operationId": "putPipelinesById", "summary": "Update pipeline", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Replaces the whole spec — send the complete object (do a GET first). Requires the `pipelines:write` scope.", "x-required-scope": "pipelines:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "7" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "name": "Funil de Vendas", "stages": [ { "name": "Novo", "required_tasks": [ { "subject": "Ligar", "task_type": "call", "priority": "high" } ] }, { "name": "Proposta" }, { "name": "Ganho", "is_won": true }, { "name": "Perdido", "is_lost": true } ] } } } } }, "delete": { "operationId": "deletePipelinesById", "summary": "Delete pipeline", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `pipelines:write` scope.", "x-required-scope": "pipelines:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "7" } ] } }, "/pipelines/capabilities": { "get": { "operationId": "getPipelinesCapabilities", "summary": "Discover what is valid", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the accepted fields, the enums (task_type, priority), the limits and the update rules — always in sync with the server. Check it before assembling a pipeline. Requires the `pipelines:read` scope.", "x-required-scope": "pipelines:read" } }, "/pipelines/templates": { "get": { "operationId": "getPipelinesTemplates", "summary": "List ready-made templates", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the official pipeline templates, organized by niche. Requires the `pipelines:read` scope.", "x-required-scope": "pipelines:read" } }, "/pipelines/templates/{slug}/install": { "post": { "operationId": "postPipelinesTemplatesBySlugInstall", "summary": "Install a template", "tags": [ "Pipelines & stages" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Installs a template into the account. Idempotent by name — installing twice does not duplicate the pipeline. Requires the `pipelines:write` scope.", "x-required-scope": "pipelines:write", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The slug.", "example": "funil-de-vendas" } ] } }, "/custom-fields": { "get": { "operationId": "getCustomFields", "summary": "List custom fields", "tags": [ "Custom fields" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "label": { "type": "string" }, "field_type": { "type": "string" }, "options": { "type": "array", "items": { "type": "string" } }, "is_required": { "type": "boolean" }, "is_active": { "type": "boolean" }, "show_on_card": { "type": "boolean" }, "sort_order": { "type": "integer" } } } } } }, "example": { "success": true, "data": [ { "id": 1, "name": "tamanho_empresa", "label": "Tamanho da empresa", "field_type": "select", "options": [ "1-10", "11-50", "51-200", "200+" ], "is_required": false, "is_active": true, "show_on_card": true, "sort_order": 1 }, { "id": 2, "name": "setor", "label": "Setor", "field_type": "text", "options": [], "is_required": true, "is_active": true, "show_on_card": false, "sort_order": 2 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `custom_fields:read` scope.", "x-required-scope": "custom_fields:read", "parameters": [ { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "If true, returns only active fields", "example": "true" } ] } }, "/nurture-sequences": { "get": { "operationId": "getNurtureSequences", "summary": "List sequences", "tags": [ "Nurture sequences" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" }, "channel": { "type": "string" }, "is_active": { "type": "boolean" }, "steps_count": { "type": "integer" }, "stats_enrolled": { "type": "integer" } } } } } }, "example": { "success": true, "data": [ { "id": 1, "name": "Boas-vindas", "description": "Onboarding da primeira semana", "channel": "email", "is_active": true, "steps_count": 5, "stats_enrolled": 234 } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the account nurture sequences. Requires the `sequences:read` scope.", "x-required-scope": "sequences:read", "parameters": [ { "name": "active_only", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "If true, returns only active sequences", "example": "true" } ] } }, "/tasks": { "get": { "operationId": "getTasks", "summary": "List tasks", "tags": [ "Tasks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "due_date": { "type": "string" }, "lead_id": { "type": "integer" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "example": { "success": true, "data": [ { "id": 45, "subject": "Enviar proposta", "type": "email", "status": "pending", "priority": "high", "due_date": "2026-07-01", "lead_id": 123 } ], "meta": { "total": 1, "per_page": 50, "current_page": 1, "last_page": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Paginated. Requires the `tasks:read` scope.", "x-required-scope": "tasks:read", "parameters": [ { "name": "lead_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tasks of a lead", "example": 123 }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Tasks of an assignee" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "pending or completed", "example": "pending" }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Type (see above)" }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string" }, "description": "low, medium, high" }, { "name": "due_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Due date from" }, { "name": "due_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Due date until" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page (default 1)" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page (default 50, max 200)" } ] }, "post": { "operationId": "postTasks", "summary": "Create task", "tags": [ "Tasks" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "success": true, "task": { "id": 45, "subject": "Enviar proposta", "status": "pending" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `tasks:write` scope.", "x-required-scope": "tasks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string", "description": "Subject" }, "type": { "type": "string", "description": "call, email, task, visit, whatsapp, meeting" }, "due_date": { "type": "string", "format": "date", "description": "Due date (YYYY-MM-DD)" }, "description": { "type": "string", "description": "Description" }, "priority": { "type": "string", "description": "low, medium, high" }, "due_time": { "type": "string", "description": "Time (HH:MM)" }, "lead_id": { "type": "integer", "description": "Linked lead" }, "assigned_to": { "type": "integer", "description": "Assignee" }, "notes": { "type": "string", "description": "Notes" } }, "required": [ "subject", "type", "due_date" ] }, "example": { "subject": "Enviar proposta", "type": "email", "due_date": "2026-07-01", "due_time": "09:00", "priority": "high", "lead_id": 123, "assigned_to": 12 } } } } } }, "/tasks/{id}": { "get": { "operationId": "getTasksById", "summary": "Fetch task", "tags": [ "Tasks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "integer" }, "subject": { "type": "string" }, "status": { "type": "string" } } } } }, "example": { "success": true, "task": { "id": 45, "subject": "Enviar proposta", "status": "pending" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `tasks:read` scope.", "x-required-scope": "tasks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "45" } ] }, "put": { "operationId": "putTasksById", "summary": "Update task", "tags": [ "Tasks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "completed_at": { "type": "string" } } } } }, "example": { "success": true, "task": { "id": 45, "status": "completed", "completed_at": "2026-06-30T11:30:00Z" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "All fields are optional (partial update). Setting status to completed fills completed_at automatically. Requires the `tasks:write` scope.", "x-required-scope": "tasks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "45" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "status": "completed" } } } } }, "delete": { "operationId": "deleteTasksById", "summary": "Delete task", "tags": [ "Tasks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `tasks:write` scope.", "x-required-scope": "tasks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "45" } ] } }, "/tasks/{id}/toggle": { "patch": { "operationId": "patchTasksByIdToggle", "summary": "Complete / reopen task", "tags": [ "Tasks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "task": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" } } } } }, "example": { "success": true, "task": { "id": 45, "status": "completed" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Toggles the status between pending and completed. Requires the `tasks:write` scope.", "x-required-scope": "tasks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "45" } ] } }, "/whatsapp/instances": { "get": { "operationId": "getWhatsappInstances", "summary": "List connected numbers", "tags": [ "WhatsApp" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "provider": { "type": "string" }, "display_name": { "type": "string" }, "phone_number": { "type": "string" }, "is_primary": { "type": "boolean" }, "status": { "type": "string" }, "supports_templates": { "type": "boolean" }, "supports_buttons": { "type": "boolean" }, "has_window_restriction": { "type": "boolean" } } } } } }, "example": { "success": true, "data": [ { "id": 1, "provider": "waha", "display_name": "Número principal", "phone_number": "+5511999887766", "is_primary": true, "status": "connected", "supports_templates": false, "supports_buttons": false, "has_window_restriction": false }, { "id": 2, "provider": "cloud_api", "display_name": "API Oficial", "phone_number": "+5521987654321", "is_primary": false, "status": "connected", "supports_templates": true, "supports_buttons": true, "has_window_restriction": true } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the connected WhatsApp numbers. No parameters. Requires the `whatsapp:read` scope.", "x-required-scope": "whatsapp:read", "parameters": [ { "name": "provider", "in": "query", "required": false, "schema": { "type": "string" }, "description": "waha (unofficial) or cloud_api (official Meta API)" }, { "name": "supports_templates", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true if it accepts HSM templates (official API only)" }, { "name": "has_window_restriction", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "true if it respects the 24h window (official API only)" }, { "name": "id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Use as instance_id when sending messages" } ] } }, "/whatsapp/templates": { "get": { "operationId": "getWhatsappTemplates", "summary": "List templates (HSM)", "tags": [ "WhatsApp" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "language": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string" }, "whatsapp_instance_id": { "type": "integer" }, "variables": { "type": "array", "items": { "type": "string" } }, "components": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "text": { "type": "string" } } } }, "quality_rating": { "type": "string" } } } } } }, "example": { "success": true, "data": [ { "id": 1, "name": "lembrete_proposta", "language": "pt_BR", "category": "UTILITY", "status": "APPROVED", "whatsapp_instance_id": 2, "variables": [ "nome", "titulo", "data" ], "components": [ { "type": "BODY", "text": "Olá {{1}}, sua {{2}} está agendada para {{3}}." } ], "quality_rating": "GREEN" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the account official (HSM) templates. Requires the `whatsapp:read` scope.", "x-required-scope": "whatsapp:read", "parameters": [ { "name": "instance_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Filters by number" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "APPROVED, PENDING, REJECTED, PAUSED, DISABLED", "example": "APPROVED" }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Template language (e.g.: pt_BR)" } ] } }, "/account": { "get": { "operationId": "getAccount", "summary": "Account data", "tags": [ "Account" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "account": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "plan": { "type": "string" } } } } }, "example": { "success": true, "account": { "id": 1, "name": "Minha Empresa", "plan": "scale" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the basic data of the account that owns the API Key. Requires the `users:read` scope.", "x-required-scope": "users:read" } }, "/users": { "get": { "operationId": "getUsers", "summary": "List users", "tags": [ "Account" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string" } } } } } }, "example": { "success": true, "data": [ { "id": 12, "name": "Ana", "email": "ana@empresa.com", "role": "admin" }, { "id": 13, "name": "Bruno", "email": "bruno@empresa.com", "role": "manager" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the account users. The role field can be admin, manager or viewer. Requires the `users:read` scope.", "x-required-scope": "users:read" } }, "/webhooks": { "get": { "operationId": "getWebhooks", "summary": "List subscriptions", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "target_url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer" }, "last_success_at": { "type": "string" }, "last_failure_at": {}, "created_at": { "type": "string" } } } }, "supported_events": { "type": "array", "items": { "type": "string" } } } }, "example": { "success": true, "data": [ { "id": 1, "target_url": "https://seu-sistema.com/webhooks/syncro", "events": [ "lead.created", "lead.updated" ], "source": "api", "is_active": true, "failure_count": 0, "last_success_at": "2026-06-30T10:05:00Z", "last_failure_at": null, "created_at": "2026-06-15T14:30:00Z" } ], "supported_events": [ "lead.created", "lead.updated", "lead.stage_changed", "..." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the account webhook subscriptions. Requires the `webhooks:read` scope.", "x-required-scope": "webhooks:read" }, "post": { "operationId": "postWebhooks", "summary": "Create subscription", "tags": [ "Webhooks" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "secret": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } }, "example": { "success": true, "id": 1, "secret": "f3a9c2...e1", "events": [ "lead.created", "lead.won", "task.completed" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Creates a subscription pointing to your URL and chooses which events to receive. Requires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "URL that will receive the POST requests" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Events to subscribe to (see list)" }, "source": { "type": "string", "description": "api (default) or n8n" }, "secret": { "type": "string", "description": "HMAC secret. If omitted, Syncro **generates one** and returns it" } }, "required": [ "target_url", "events" ] }, "example": { "target_url": "https://seu-sistema.com/webhooks/syncro", "events": [ "lead.created", "lead.won", "task.completed" ] } } } } } }, "/webhooks/{id}": { "get": { "operationId": "getWebhooksById", "summary": "Subscription detail", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "target_url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "is_active": { "type": "boolean" }, "failure_count": { "type": "integer" }, "last_success_at": { "type": "string" }, "last_failure_at": {}, "last_failure_reason": {} } }, "example": { "success": true, "id": 1, "target_url": "https://seu-sistema.com/webhooks/syncro", "events": [ "lead.created", "lead.updated" ], "source": "api", "is_active": true, "failure_count": 0, "last_success_at": "2026-06-30T10:05:00Z", "last_failure_at": null, "last_failure_reason": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the data of a specific subscription. Requires the `webhooks:read` scope.", "x-required-scope": "webhooks:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "1" } ] }, "put": { "operationId": "putWebhooksById", "summary": "Update subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "events": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" } } }, "example": { "success": true, "id": 1, "events": [ "lead.created" ], "is_active": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Update the URL, the events or activate/deactivate. Reactivating (is_active: true) resets the failure counter. Requires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "1" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "target_url": { "type": "string", "description": "New URL" }, "events": { "type": "array", "items": { "type": "string" }, "description": "New list of events" }, "is_active": { "type": "boolean", "description": "Activates/deactivates" } } }, "example": { "events": [ "lead.created" ], "is_active": true } } } } }, "delete": { "operationId": "deleteWebhooksById", "summary": "Delete subscription", "tags": [ "Webhooks" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Removes a webhook subscription. Requires the `webhooks:write` scope.", "x-required-scope": "webhooks:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "1" } ] } }, "/automations": { "get": { "operationId": "getAutomations", "summary": "List automations", "tags": [ "Automations" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "trigger_type": { "type": "string" }, "is_active": { "type": "boolean" }, "run_count": { "type": "integer" }, "last_run_at": { "type": "string" }, "updated_at": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "example": { "success": true, "data": [ { "id": 42, "name": "Etiquetar novos leads", "trigger_type": "lead_created", "is_active": true, "run_count": 128, "last_run_at": "2026-07-19T14:03:11-03:00", "updated_at": "2026-07-18T09:20:00-03:00" } ], "meta": { "total": 1, "per_page": 30, "current_page": 1, "last_page": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Paginated. Filters via query string. Requires the `automations:read` scope.", "x-required-scope": "automations:read", "parameters": [ { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only active or only inactive ones", "example": "true" }, { "name": "trigger_type", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filters by trigger (see GET /automations/capabilities)" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page (default 30, max 100)" } ] }, "post": { "operationId": "postAutomations", "summary": "Create an automation", "tags": [ "Automations" ], "responses": { "201": { "description": "Response 201", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "warnings": { "type": "array", "items": {} }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "run_count": { "type": "integer" }, "last_run_at": {}, "updated_at": { "type": "string" }, "spec": { "type": "object", "properties": {} } } } } }, "example": { "success": true, "warnings": [], "data": { "id": 57, "is_active": false, "run_count": 0, "last_run_at": null, "updated_at": "2026-07-20T10:00:00-03:00", "spec": {} } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "**Flat** format (recommended). The automation starts **inactive**. Requires the `automations:write` scope.", "x-required-scope": "automations:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Automation name (unique)" }, "trigger_type": { "type": "string", "description": "Trigger that fires the automation (e.g. lead_created)" }, "actions": { "type": "array", "items": { "type": "string" }, "description": "Actions to run, shaped as { \"type\": \"...\", \"config\": { ... } }" }, "trigger_config": { "type": "object", "description": "Trigger configuration (accepted keys in GET /automations/capabilities)" }, "conditions": { "type": "array", "items": { "type": "string" }, "description": "Conditions shaped as { \"field\": \"...\", \"operator\": \"...\", \"value\": \"...\" }" }, "validate_only": { "type": "boolean", "description": "*Dry-run*: validates and returns errors/warnings without saving anything" } }, "required": [ "name", "trigger_type", "actions" ] }, "example": { "name": "Etiquetar novos leads", "trigger_type": "lead_created", "trigger_config": {}, "conditions": [], "actions": [ { "type": "add_tag_lead", "config": { "tags": [ "Novo" ] } } ] } } } } } }, "/automations/{id}": { "get": { "operationId": "getAutomationsById", "summary": "Fetch one automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "run_count": { "type": "integer" }, "last_run_at": { "type": "string" }, "updated_at": { "type": "string" }, "spec": { "type": "object", "properties": { "name": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_config": { "type": "object", "properties": {} }, "conditions": { "type": "array", "items": {} }, "actions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "config": { "type": "object", "properties": { "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "nodes": { "type": "array", "items": {} }, "edges": { "type": "array", "items": {} } } } } } } }, "example": { "success": true, "data": { "id": 42, "is_active": true, "run_count": 128, "last_run_at": "2026-07-19T14:03:11-03:00", "updated_at": "2026-07-18T09:20:00-03:00", "spec": { "name": "Etiquetar novos leads", "trigger_type": "lead_created", "trigger_config": {}, "conditions": [], "actions": [ { "type": "add_tag_lead", "config": { "tags": [ "Novo" ] } } ], "nodes": [], "edges": [] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the status + the re-importable spec (flat + graph). Requires the `automations:read` scope.", "x-required-scope": "automations:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "42" } ] }, "put": { "operationId": "putAutomationsById", "summary": "Update an automation", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Replaces the whole spec (send the complete object; do a GET first). It **does not change** is_active (activation happens only through the toggle). Requires the `automations:write` scope.", "x-required-scope": "automations:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "42" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "name": "Etiquetar novos leads", "trigger_type": "lead_created", "trigger_config": {}, "conditions": [], "actions": [ { "type": "add_tag_lead", "config": { "tags": [ "Novo" ] } } ] } } } } }, "delete": { "operationId": "deleteAutomationsById", "summary": "Delete", "tags": [ "Automations" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `automations:write` scope.", "x-required-scope": "automations:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "57" } ] } }, "/automations/{id}/toggle": { "patch": { "operationId": "patchAutomationsByIdToggle", "summary": "Activate / deactivate", "tags": [ "Automations" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "id": { "type": "integer" }, "is_active": { "type": "boolean" } } }, "example": { "success": true, "id": 57, "is_active": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Optional body { \"is_active\": true } (omitted = flips the current state). Requires the `automations:write` scope.", "x-required-scope": "automations:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "57" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": {} }, "example": { "is_active": true } } } } } }, "/automations/capabilities": { "get": { "operationId": "getAutomationsCapabilities", "summary": "Discover what is valid", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns, in a machine-readable form, **all** accepted triggers, actions and config keys (the same source the validator uses — the docs never go stale). Always check this endpoint before assembling an automation. Requires the `automations:read` scope.", "x-required-scope": "automations:read" } }, "/automations/templates": { "get": { "operationId": "getAutomationsTemplates", "summary": "List ready-made templates", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Lists the official templates. Requires the `automations:read` scope.", "x-required-scope": "automations:read" } }, "/automations/templates/{slug}/install": { "post": { "operationId": "postAutomationsTemplatesBySlugInstall", "summary": "Install a template", "tags": [ "Automations" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Installs an official template (idempotent by name; installed **inactive**). Requires the `automations:write` scope.", "x-required-scope": "automations:write", "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The slug.", "example": "etiquetar-novos-leads" } ] } }, "/chatbots": { "get": { "operationId": "getChatbots", "summary": "List flows", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string" }, "is_active": { "type": "boolean" }, "is_catch_all": { "type": "boolean" }, "trigger_type": { "type": "string" }, "trigger_keywords": { "type": "array", "items": { "type": "string" } }, "whatsapp_instance_id": {}, "completions_count": { "type": "integer" }, "updated_at": { "type": "string" } } } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } } }, "example": { "success": true, "data": [ { "id": 12, "name": "Boas-vindas", "channel": "whatsapp", "is_active": true, "is_catch_all": false, "trigger_type": "keyword", "trigger_keywords": [ "oi", "menu" ], "whatsapp_instance_id": null, "completions_count": 340, "updated_at": "2026-07-19T18:00:00-03:00" } ], "meta": { "total": 1, "per_page": 30, "current_page": 1, "last_page": 1, "has_more": false } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Paginated. Accepts filters by channel, status and name search. Requires the `chatbots:read` scope.", "x-required-scope": "chatbots:read", "parameters": [ { "name": "channel", "in": "query", "required": false, "schema": { "type": "string" }, "description": "whatsapp, instagram or website", "example": "whatsapp" }, { "name": "is_active", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Only active or inactive flows", "example": "true" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Page" }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Items per page" } ] }, "post": { "operationId": "postChatbots", "summary": "Create a flow", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "The flow is created **inactive**. Use PATCH /chatbots/{id}/toggle to activate it afterwards. Requires the `chatbots:write` scope.", "x-required-scope": "chatbots:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "type": "object", "description": "Versioned envelope { syncro_chatbot_flow, schema_version, channel, flow, graph }" }, "whatsapp_instance_id": { "type": "integer", "description": "WhatsApp instance linked to the flow" }, "is_catch_all": { "type": "boolean", "description": "Fallback flow for the channel" }, "validate_only": { "type": "boolean", "description": "*Dry-run*: validates and returns errors/warnings without saving" } }, "required": [ "envelope" ] }, "example": { "envelope": { "syncro_chatbot_flow": true, "schema_version": 1, "channel": "whatsapp", "flow": { "name": "Boas-vindas", "channel": "whatsapp", "trigger_type": "keyword", "trigger_keywords": [ "oi", "menu" ] }, "graph": { "nodes": [ { "id": "n1", "type": "message", "position": { "x": 300, "y": 200 }, "data": { "text": "Olá! Como posso ajudar?" } }, { "id": "n2", "type": "end", "position": { "x": 600, "y": 200 }, "data": {} } ], "edges": [ { "id": "e1", "source": "n1", "sourceHandle": "default", "target": "n2" } ] } } } } } } } }, "/chatbots/{id}": { "get": { "operationId": "getChatbotsById", "summary": "Fetch a flow", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_catch_all": { "type": "boolean" }, "whatsapp_instance_id": {}, "completions_count": { "type": "integer" }, "updated_at": { "type": "string" }, "envelope": { "type": "object", "properties": { "syncro_chatbot_flow": { "type": "boolean" }, "schema_version": { "type": "integer" }, "channel": { "type": "string" }, "flow": { "type": "object", "properties": { "name": { "type": "string" }, "channel": { "type": "string" }, "trigger_type": { "type": "string" }, "trigger_keywords": { "type": "array", "items": { "type": "string" } } } }, "graph": { "type": "object", "properties": { "nodes": { "type": "array", "items": {} }, "edges": { "type": "array", "items": {} } } } } } } } } }, "example": { "success": true, "data": { "id": 12, "is_active": true, "is_catch_all": false, "whatsapp_instance_id": null, "completions_count": 340, "updated_at": "2026-07-19T18:00:00-03:00", "envelope": { "syncro_chatbot_flow": true, "schema_version": 1, "channel": "whatsapp", "flow": { "name": "Boas-vindas", "channel": "whatsapp", "trigger_type": "keyword", "trigger_keywords": [ "oi", "menu" ] }, "graph": { "nodes": [], "edges": [] } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns the flow status plus the re-importable envelope. Requires the `chatbots:read` scope.", "x-required-scope": "chatbots:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "12" } ] }, "put": { "operationId": "putChatbotsById", "summary": "Update a flow", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Replaces the whole graph. Do a GET first and send the complete envelope. Requires the `chatbots:write` scope.", "x-required-scope": "chatbots:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "12" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "envelope": { "type": "object", "description": "Complete envelope — replaces all nodes and edges" }, "validate_only": { "type": "boolean", "description": "*Dry-run*: validates and returns errors/warnings without saving" } }, "required": [ "envelope" ] }, "example": { "envelope": { "syncro_chatbot_flow": true, "schema_version": 1, "channel": "whatsapp", "flow": { "name": "Boas-vindas", "channel": "whatsapp", "trigger_type": "keyword", "trigger_keywords": [ "oi", "menu" ] }, "graph": { "nodes": [ { "id": "n1", "type": "message", "position": { "x": 300, "y": 200 }, "data": { "text": "Olá! Como posso ajudar?" } }, { "id": "n2", "type": "end", "position": { "x": 600, "y": 200 }, "data": {} } ], "edges": [ { "id": "e1", "source": "n1", "sourceHandle": "default", "target": "n2" } ] } } } } } } }, "delete": { "operationId": "deleteChatbotsById", "summary": "Delete flow", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Response 200", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } } }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Requires the `chatbots:write` scope.", "x-required-scope": "chatbots:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "12" } ] } }, "/chatbots/{id}/toggle": { "patch": { "operationId": "patchChatbotsByIdToggle", "summary": "Activate / deactivate flow", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Send { \"is_active\": true }. If is_active is omitted, the current state is toggled. Activating makes the bot start replying to real conversations. Requires the `chatbots:write` scope.", "x-required-scope": "chatbots:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The id.", "example": "12" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "is_active": { "type": "boolean", "description": "Desired state; omitted toggles the current state" } } }, "example": { "is_active": true } } } } } }, "/chatbots/capabilities": { "get": { "operationId": "getChatbotsCapabilities", "summary": "Discover what is valid", "tags": [ "Chatbots (flows)" ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "502": { "$ref": "#/components/responses/UpstreamError" }, "default": { "$ref": "#/components/responses/UnexpectedError" } }, "description": "Returns node types per channel, action subtypes, handle rules, limits and a sample envelope — it is the single source of truth for the validator. Check it before building a flow. Requires the `chatbots:read` scope.", "x-required-scope": "chatbots:read" } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key in the format `crm_...`, generated under Settings → API Keys." } }, "schemas": { "Error": { "type": "object", "description": "Error payload returned for non-2xx responses. `message` is always present; the remaining fields appear according to the failure.", "properties": { "message": { "type": "string", "description": "Human-readable explanation of the failure." }, "success": { "type": "boolean", "description": "Present and `false` on business-rule failures." }, "errors": { "type": "object", "description": "On 422 validation, a map of field name to the list of messages for that field.", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "required_permission": { "type": "string", "description": "On 403, the API-key scope that was missing (e.g. `leads:write`)." }, "feature": { "type": "string", "description": "On 403, the plan feature the account is missing (e.g. `chatbot`)." }, "retry_after": { "type": "integer", "description": "On 429, seconds to wait before retrying." }, "blocked": { "type": "boolean", "description": "On 422, true when mandatory stage tasks block the move." }, "pending_tasks": { "type": "array", "items": { "type": "object" }, "description": "On 422 with blocked=true, the tasks that must be completed first." }, "limit_reached": { "type": "boolean", "description": "On 422, true when the plan limit was hit." }, "skip_reason": { "type": "string", "description": "On 422 for WhatsApp sends, why the message was skipped (e.g. `window_closed`)." } }, "required": [ "message" ] }, "PaginationMeta": { "type": "object", "properties": { "total": { "type": "integer" }, "per_page": { "type": "integer" }, "current_page": { "type": "integer" }, "last_page": { "type": "integer" }, "has_more": { "type": "boolean" } } } }, "responses": { "Unauthorized": { "description": "API key missing, invalid or expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "API Key inválida." } } } }, "Forbidden": { "description": "Inactive account, or API key without permission for this operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "API Key sem permissão para esta operação.", "required_permission": "leads:write" } } } }, "NotFound": { "description": "The requested resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Registro não encontrado." } } } }, "ValidationError": { "description": "Validation failure or business rule (invalid fields, blocked stage, plan limit, WhatsApp window).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Complete as tarefas obrigatórias antes de mover o lead.", "blocked": true, "pending_tasks": [ { "id": 45, "subject": "Ligar para o cliente", "type": "call" } ] } } } }, "RateLimited": { "description": "Per-minute request limit for this API key exceeded (60 requests/minute).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Rate limit excedido para esta API Key.", "retry_after": 35 } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } } }, "UpstreamError": { "description": "External provider failure (e.g. WhatsApp delivery).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "success": false, "message": "Falha ao enviar: provedor indisponível." } } } }, "UnexpectedError": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Erro inesperado." } } } } } } }