{ "openapi": "3.1.0", "info": { "title": "ChatForce 2.0 — API Pública", "version": "v1", "summary": "API REST do ChatForce 2.0 (CRM de televendas e atendimento omnichannel).", "description": "API pública versionada (`v1`) para integrar contatos, conversas, mensagens, pedidos, oportunidades, tickets e campanhas.\n\n**Autenticação:** Bearer Token (`{token_id}.{secret}`) + assinatura `HMAC-SHA256` sobre `\"{timestamp}.{corpo_bruto}\"`. Envie `X-ChatForce-Timestamp` (Unix, janela de 5 minutos) e `X-ChatForce-Signature` (hex). Em GET/HEAD o corpo é vazio, então a assinatura é `HMAC(\"{timestamp}.\")`.\n\n**Escopo:** tokens de usuário são limitados às contas acessíveis; tokens de agente (`cfa_`) não acessam recursos de conta.\n\n**Idempotência:** envie `Idempotency-Key` em escritas. Replay devolve a resposta original com `Idempotency-Replayed: true`; corpo diferente com a mesma chave devolve `409`.", "contact": { "name": "Onsiite TecnologIA", "email": "chatforce@onsiite.com.br", "url": "https://2.0.chatforce.com.br" }, "license": { "name": "Proprietário" } }, "servers": [ { "url": "https://2.0.chatforce.com.br/api/v1", "description": "Produção" } ], "tags": [ { "name": "Saúde", "description": "Disponibilidade do serviço (público)." }, { "name": "Identidade", "description": "Dados e escopo do token." }, { "name": "Mensagens", "description": "Ingest de mensagens na Caixa de API." }, { "name": "Contatos", "description": "Cadastro de clientes/contatos." }, { "name": "Conversas", "description": "Conversas e mensagens." }, { "name": "Caixas", "description": "Caixas de entrada e canais." }, { "name": "Tags", "description": "Etiquetas." }, { "name": "Pipelines", "description": "Funis e etapas." }, { "name": "Pedidos", "description": "Pedidos comerciais." }, { "name": "Oportunidades", "description": "Oportunidades de negócio." }, { "name": "Tickets", "description": "Tickets de atendimento." }, { "name": "Campanhas", "description": "Campanhas em massa." }, { "name": "Webhooks", "description": "Entradas de provedores e integrações (autenticação própria)." } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "{token_id}.{secret}", "description": "Informe o token completo `{token_id}.{secret}` (ex.: `cfu_xxxxxxxx.seu_segredo`). O navegador de testes calcula automaticamente `X-ChatForce-Timestamp` e `X-ChatForce-Signature` a partir do segredo." } }, "parameters": { "page": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Página da coleção." }, "perPage": { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Itens por página (máximo 100)." }, "updatedSince": { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Registros atualizados a partir desta data (ISO 8601)." }, "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Chave de idempotência (recomendada em escritas)." }, "contactPath": { "name": "contact", "in": "path", "required": true, "schema": { "type": "integer" } }, "conversationPath": { "name": "conversation", "in": "path", "required": true, "schema": { "type": "integer" } }, "orderPath": { "name": "order", "in": "path", "required": true, "schema": { "type": "integer" } }, "opportunityPath": { "name": "opportunity", "in": "path", "required": true, "schema": { "type": "integer" } }, "ticketPath": { "name": "ticket", "in": "path", "required": true, "schema": { "type": "integer" } }, "inboxPath": { "name": "inbox", "in": "path", "required": true, "schema": { "type": "integer" } }, "pipelinePath": { "name": "pipeline", "in": "path", "required": true, "schema": { "type": "integer" } }, "campaignPath": { "name": "campaign", "in": "path", "required": true, "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message" ] }, "PaginationLinks": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } } }, "PaginationMeta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } }, "Contact": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "client_code": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "is_blocked": { "type": "boolean" }, "marketing_opt_out": { "type": "boolean" }, "consent_at": { "type": [ "string", "null" ], "format": "date-time" }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ContactInput": { "type": "object", "required": [ "name", "phone" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "phone": { "type": "string", "maxLength": 50 }, "email": { "type": [ "string", "null" ], "format": "email" }, "document": { "type": [ "string", "null" ] }, "client_code": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "avatar_url": { "type": [ "string", "null" ] } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "external_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "new", "bot", "in_progress", "pending_ai", "closed" ] }, "priority": { "type": "string" }, "inbox": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string" } } }, "contact": { "$ref": "#/components/schemas/Contact" }, "assigned_user": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "team_id": { "type": [ "integer", "null" ] }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] }, "last_message_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Attachment": { "type": "object", "properties": { "uuid": { "type": "string" }, "original_filename": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" } } }, "Message": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "direction": { "type": "string", "enum": [ "inbound", "outbound", "internal" ] }, "type": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "sender": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Inbox": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "channel": { "type": "string", "enum": [ "api", "webchat", "whatsapp", "email", "telegram", "instagram", "messenger", "voice", "internal" ] }, "is_active": { "type": "boolean" }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] }, "team_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Tag": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "color": { "type": [ "string", "null" ] }, "visibility": { "type": [ "string", "null" ] }, "blocks_contact": { "type": "boolean" }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] } } }, "Stage": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "position": { "type": "integer" }, "color": { "type": [ "string", "null" ] }, "sla_hours": { "type": [ "integer", "null" ] }, "max_stay_hours": { "type": [ "integer", "null" ] }, "is_won": { "type": "boolean" }, "is_lost": { "type": "boolean" } } }, "Pipeline": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "visibility": { "type": [ "string", "null" ] }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] }, "stages": { "type": "array", "items": { "$ref": "#/components/schemas/Stage" } } } }, "OrderItem": { "type": "object", "properties": { "description": { "type": "string" }, "quantity": { "type": "string" }, "unit_price": { "type": "string" }, "discount": { "type": [ "string", "null" ] }, "total": { "type": "string" } } }, "Order": { "type": "object", "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "confirmed", "shipped", "invoiced", "paid", "cancelled" ] }, "approval_status": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "total": { "type": "string" }, "currency": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "contact": { "$ref": "#/components/schemas/Contact" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Opportunity": { "type": "object", "properties": { "id": { "type": "integer" }, "external_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "won", "lost" ] }, "value": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "expected_close_at": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] }, "contact": { "$ref": "#/components/schemas/Contact" }, "pipeline": { "$ref": "#/components/schemas/Pipeline" }, "stage": { "$ref": "#/components/schemas/Stage" }, "assigned_user": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TicketReply": { "type": "object", "properties": { "id": { "type": "integer" }, "body": { "type": "string" }, "user": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "attachments": { "type": "array", "items": { "$ref": "#/components/schemas/Attachment" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Ticket": { "type": "object", "properties": { "id": { "type": "integer" }, "protocol": { "type": "string" }, "subject": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" }, "contact": { "$ref": "#/components/schemas/Contact" }, "conversation_id": { "type": [ "integer", "null" ] }, "order_id": { "type": [ "integer", "null" ] }, "team_id": { "type": [ "integer", "null" ] }, "assigned_user": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "replies": { "type": "array", "items": { "$ref": "#/components/schemas/TicketReply" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Campaign": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "name": { "type": "string" }, "channel": { "type": "string" }, "status": { "type": "string" }, "type": { "type": "string" }, "total_recipients": { "type": "integer" }, "account_id": { "type": [ "integer", "null" ] }, "sector_id": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "InboundMessageResult": { "type": "object", "properties": { "event_id": { "type": "string" }, "replayed": { "type": "boolean" }, "conversation": { "type": "object", "properties": { "id": { "type": "integer" }, "external_id": { "type": [ "string", "null" ] }, "status": { "type": "string" } } }, "message": { "type": "object", "properties": { "id": { "type": "integer" }, "uuid": { "type": "string" }, "external_id": { "type": "string" }, "direction": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } } }, "Me": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "user", "agent" ] }, "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "role": { "type": [ "string", "null" ] }, "is_super_admin": { "type": [ "boolean", "null" ] }, "account_scope": { "type": [ "array", "null" ], "items": { "type": "integer" } }, "accounts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } } } } } }, "responses": { "Unauthorized": { "description": "Token, timestamp ou assinatura inválidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Assinatura inválida." } } } }, "Forbidden": { "description": "Token de agente em recurso de conta, ou ação não permitida.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Este recurso exige um token de usuário (Administrador ou Monitor)." } } } }, "NotFound": { "description": "Recurso inexistente ou fora do escopo de conta.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflito de idempotência ou estado incompatível.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Idempotency-Key já utilizada com um conteúdo diferente." } } } }, "ValidationError": { "description": "Falha de validação do contrato.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "O campo phone é obrigatório.", "errors": { "phone": [ "O campo phone é obrigatório." ] } } } } }, "TooManyRequests": { "description": "Limite de requisições excedido (120 req/min por ator)." } } }, "paths": { "/health": { "get": { "tags": [ "Saúde" ], "summary": "Verifica a saúde do serviço", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "Serviço saudável.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "service": { "type": "string" }, "api_version": { "type": "string" }, "time": { "type": "string", "format": "date-time" }, "checks": { "type": "object", "properties": { "database": { "type": "boolean" }, "cache": { "type": "boolean" } } } } } } } }, "503": { "description": "Serviço degradado." } } } }, "/me": { "get": { "tags": [ "Identidade" ], "summary": "Dados e escopo do token", "operationId": "getMe", "responses": { "200": { "description": "Ator autenticado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Me" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/messages/{inbox}": { "post": { "tags": [ "Mensagens" ], "summary": "Recebe uma mensagem externa na Caixa de API", "operationId": "storeInboundMessage", "parameters": [ { "name": "inbox", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Path público da caixa de API." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Chave única do evento." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event_id", "contact", "message" ], "properties": { "event_id": { "type": "string", "maxLength": 191 }, "contact": { "type": "object", "required": [ "external_id", "name" ], "properties": { "external_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } } }, "conversation": { "type": "object", "properties": { "external_id": { "type": [ "string", "null" ] } } }, "message": { "type": "object", "required": [ "external_id", "type", "body" ], "properties": { "external_id": { "type": "string" }, "type": { "type": "string", "enum": [ "text" ] }, "body": { "type": "string", "maxLength": 10000 } } } } }, "example": { "event_id": "evt-1001", "contact": { "external_id": "crm-42", "name": "Cliente", "phone": "+5511999999999" }, "message": { "external_id": "msg-500", "type": "text", "body": "Olá" } } } } }, "responses": { "201": { "description": "Evento novo processado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InboundMessageResult" } } } } } }, "200": { "description": "Replay idempotente (`replayed=true`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/InboundMessageResult" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contacts": { "get": { "tags": [ "Contatos" ], "summary": "Lista contatos", "operationId": "listContacts", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "email", "in": "query", "schema": { "type": "string" } }, { "name": "phone", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/updatedSince" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "links": { "$ref": "#/components/schemas/PaginationLinks" }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Contatos" ], "summary": "Cria um contato", "operationId": "createContact", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" }, "example": { "name": "Ana Souza", "phone": "+5511999999999", "email": "ana@example.com" } } } }, "responses": { "201": { "description": "Contato criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/contacts/{contact}": { "get": { "tags": [ "Contatos" ], "summary": "Consulta um contato", "operationId": "getContact", "parameters": [ { "$ref": "#/components/parameters/contactPath" } ], "responses": { "200": { "description": "Contato.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Contatos" ], "summary": "Atualiza um contato", "operationId": "updateContact", "parameters": [ { "$ref": "#/components/parameters/contactPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Contato atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/inboxes": { "get": { "tags": [ "Caixas" ], "summary": "Lista caixas de entrada", "operationId": "listInboxes", "parameters": [ { "name": "channel", "in": "query", "schema": { "type": "string" } }, { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Inbox" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/inboxes/{inbox}": { "get": { "tags": [ "Caixas" ], "summary": "Consulta uma caixa", "operationId": "getInbox", "parameters": [ { "$ref": "#/components/parameters/inboxPath" } ], "responses": { "200": { "description": "Caixa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Inbox" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tags": { "get": { "tags": [ "Tags" ], "summary": "Lista etiquetas", "operationId": "listTags", "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Tag" } } } } } } } } } }, "/pipelines": { "get": { "tags": [ "Pipelines" ], "summary": "Lista funis", "operationId": "listPipelines", "parameters": [ { "name": "is_active", "in": "query", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Pipeline" } } } } } } } } } }, "/pipelines/{pipeline}": { "get": { "tags": [ "Pipelines" ], "summary": "Consulta um funil com etapas", "operationId": "getPipeline", "parameters": [ { "$ref": "#/components/parameters/pipelinePath" } ], "responses": { "200": { "description": "Funil.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Pipeline" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/conversations": { "get": { "tags": [ "Conversas" ], "summary": "Lista conversas", "operationId": "listConversations", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "new", "bot", "in_progress", "pending_ai", "closed" ] } }, { "name": "inbox_id", "in": "query", "schema": { "type": "integer" } }, { "name": "contact_id", "in": "query", "schema": { "type": "integer" } }, { "name": "team_id", "in": "query", "schema": { "type": "integer" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/updatedSince" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/conversations/{conversation}": { "get": { "tags": [ "Conversas" ], "summary": "Consulta uma conversa", "operationId": "getConversation", "parameters": [ { "$ref": "#/components/parameters/conversationPath" } ], "responses": { "200": { "description": "Conversa.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Conversas" ], "summary": "Atualiza responsável, equipe ou status", "operationId": "updateConversation", "parameters": [ { "$ref": "#/components/parameters/conversationPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assigned_user_id": { "type": [ "integer", "null" ] }, "team_id": { "type": [ "integer", "null" ] }, "status": { "type": "string", "enum": [ "in_progress", "closed" ] }, "resolution_reason_id": { "type": [ "integer", "null" ] }, "resolution_notes": { "type": [ "string", "null" ] } } }, "example": { "assigned_user_id": 7 } } } }, "responses": { "200": { "description": "Conversa atualizada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Conversation" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/conversations/{conversation}/messages": { "get": { "tags": [ "Conversas" ], "summary": "Lista mensagens da conversa", "operationId": "listConversationMessages", "parameters": [ { "$ref": "#/components/parameters/conversationPath" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "tags": [ "Conversas" ], "summary": "Envia uma mensagem", "operationId": "sendConversationMessage", "parameters": [ { "$ref": "#/components/parameters/conversationPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 10000 }, "destination": { "type": "string", "enum": [ "customer", "team" ], "default": "customer" }, "reply_to_id": { "type": [ "integer", "null" ] } } }, "example": { "body": "Olá, como posso ajudar?", "destination": "customer" } } } }, "responses": { "201": { "description": "Mensagem criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/orders": { "get": { "tags": [ "Pedidos" ], "summary": "Lista pedidos", "operationId": "listOrders", "parameters": [ { "name": "contact_id", "in": "query", "schema": { "type": "integer" } }, { "name": "external_number", "in": "query", "schema": { "type": "string" } }, { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "approval_status", "in": "query", "schema": { "type": "string" } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "tags": [ "Pedidos" ], "summary": "Cria um pedido", "operationId": "createOrder", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact_id", "number" ], "properties": { "contact_id": { "type": "integer" }, "conversation_id": { "type": [ "integer", "null" ] }, "opportunity_id": { "type": [ "integer", "null" ] }, "number": { "type": "string" }, "external_number": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "confirmed", "shipped", "invoiced", "paid", "cancelled" ] }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "discount": { "type": [ "number", "null" ] } } } }, "proposal_id": { "type": [ "integer", "null" ], "description": "Proposta de origem (opcional)." } } }, "example": { "contact_id": 12, "number": "ORD-1001", "status": "confirmed", "items": [ { "description": "Plano Pro", "quantity": 2, "unit_price": 100 } ] } } } }, "responses": { "201": { "description": "Pedido criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/orders/{order}": { "get": { "tags": [ "Pedidos" ], "summary": "Consulta um pedido", "operationId": "getOrder", "parameters": [ { "$ref": "#/components/parameters/orderPath" } ], "responses": { "200": { "description": "Pedido.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Pedidos" ], "summary": "Atualiza um pedido", "operationId": "updateOrder", "parameters": [ { "$ref": "#/components/parameters/orderPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "integer" }, "external_number": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Pedido atualizado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Order" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/opportunities": { "get": { "tags": [ "Oportunidades" ], "summary": "Lista oportunidades", "operationId": "listOpportunities", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "open", "won", "lost" ] } }, { "name": "contact_id", "in": "query", "schema": { "type": "integer" } }, { "name": "pipeline_id", "in": "query", "schema": { "type": "integer" } }, { "name": "external_id", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/updatedSince" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "tags": [ "Oportunidades" ], "summary": "Cria ou atualiza uma oportunidade por external_id", "operationId": "upsertOpportunity", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "pipeline_id", "stage_id" ], "properties": { "external_id": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "contact_phone": { "type": [ "string", "null" ] }, "contact_name": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "pipeline_id": { "type": "integer" }, "stage_id": { "type": "integer" }, "assigned_user_id": { "type": [ "integer", "null" ] }, "value": { "type": [ "number", "null" ] }, "currency": { "type": "string" }, "expected_close_at": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] } } }, "example": { "external_id": "opp-001", "contact_id": 12, "title": "Oportunidade API", "pipeline_id": 1, "stage_id": 1, "value": 1500 } } } }, "responses": { "201": { "description": "Criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Opportunity" } } } } } }, "200": { "description": "Atualizada (upsert).", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Opportunity" } } } } } }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/opportunities/{opportunity}": { "get": { "tags": [ "Oportunidades" ], "summary": "Consulta uma oportunidade", "operationId": "getOpportunity", "parameters": [ { "$ref": "#/components/parameters/opportunityPath" } ], "responses": { "200": { "description": "Oportunidade.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Opportunity" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Oportunidades" ], "summary": "Atualiza uma oportunidade", "operationId": "updateOpportunity", "parameters": [ { "$ref": "#/components/parameters/opportunityPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "pipeline_id": { "type": "integer" }, "stage_id": { "type": "integer" }, "assigned_user_id": { "type": [ "integer", "null" ] }, "value": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "expected_close_at": { "type": [ "string", "null" ], "format": "date" }, "notes": { "type": [ "string", "null" ] } } }, "example": { "stage_id": 2, "value": 999.9 } } } }, "responses": { "200": { "description": "Oportunidade atualizada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Opportunity" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tickets": { "get": { "tags": [ "Tickets" ], "summary": "Lista tickets", "operationId": "listTickets", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "priority", "in": "query", "schema": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] } }, { "name": "contact_id", "in": "query", "schema": { "type": "integer" } }, { "name": "assigned_user_id", "in": "query", "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/updatedSince" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } }, "post": { "tags": [ "Tickets" ], "summary": "Abre um ticket", "operationId": "createTicket", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "subject", "priority" ], "properties": { "subject": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "priority": { "type": "string", "enum": [ "low", "normal", "high", "urgent" ] }, "due_at": { "type": [ "string", "null" ], "format": "date-time" }, "contact_id": { "type": [ "integer", "null" ] }, "conversation_id": { "type": [ "integer", "null" ] }, "order_id": { "type": [ "integer", "null" ] }, "team_id": { "type": [ "integer", "null" ] }, "assigned_user_id": { "type": [ "integer", "null" ] } } }, "example": { "subject": "Problema no pedido", "priority": "high", "contact_id": 12 } } } }, "responses": { "201": { "description": "Ticket criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/tickets/{ticket}": { "get": { "tags": [ "Tickets" ], "summary": "Consulta um ticket", "operationId": "getTicket", "parameters": [ { "$ref": "#/components/parameters/ticketPath" } ], "responses": { "200": { "description": "Ticket.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Ticket" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/tickets/{ticket}/replies": { "post": { "tags": [ "Tickets" ], "summary": "Responde um ticket", "operationId": "replyTicket", "parameters": [ { "$ref": "#/components/parameters/ticketPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "body" ], "properties": { "body": { "type": "string", "maxLength": 5000 } } }, "example": { "body": "Estamos verificando o ocorrido." } } } }, "responses": { "201": { "description": "Resposta criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/TicketReply" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/campaigns": { "get": { "tags": [ "Campanhas" ], "summary": "Lista campanhas", "operationId": "listCampaigns", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "type", "in": "query", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/perPage" } ], "responses": { "200": { "description": "Coleção paginada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } }, "meta": { "$ref": "#/components/schemas/PaginationMeta" } } } } } } } } }, "/campaigns/{campaign}": { "get": { "tags": [ "Campanhas" ], "summary": "Consulta uma campanha", "operationId": "getCampaign", "parameters": [ { "$ref": "#/components/parameters/campaignPath" } ], "responses": { "200": { "description": "Campanha com estatística.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Campaign" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/campaigns/{campaign}/events": { "post": { "tags": [ "Campanhas" ], "summary": "Registra um evento de campanha", "operationId": "storeCampaignEvent", "parameters": [ { "$ref": "#/components/parameters/campaignPath" }, { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "sent", "delivered", "read", "replied", "click", "conversion", "opt_out", "error" ] }, "campaign_recipient_id": { "type": [ "integer", "null" ] }, "contact_id": { "type": [ "integer", "null" ] }, "payload": { "type": [ "object", "null" ] } } }, "example": { "type": "conversion", "contact_id": 456, "payload": { "source": "gtm-server-side", "value": 199.9 } } } } }, "responses": { "200": { "description": "Evento registrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" } } } }, "/webhooks/meta": { "get": { "tags": [ "Webhooks" ], "summary": "Verificação do webhook Meta", "operationId": "verifyMetaWebhook", "security": [], "parameters": [ { "name": "hub.mode", "in": "query", "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Desafio ecoado." }, "403": { "description": "Token inválido." } } }, "post": { "tags": [ "Webhooks" ], "summary": "Callback única Meta (WhatsApp/Instagram/Messenger)", "operationId": "handleMetaWebhook", "security": [], "parameters": [ { "name": "X-Hub-Signature-256", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recebido." }, "403": { "description": "Assinatura inválida." } } } }, "/webhooks/inbox/{token}": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook universal da Caixa de API (Evolution API)", "description": "Recebe o payload nativo da Evolution (messages.upsert / messages.update). Autenticação pelo token da caixa na URL; sem Bearer/HMAC.", "operationId": "handleInboxWebhook", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Token de webhook da caixa." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "string", "example": "messages.upsert" }, "instance": { "type": "string" }, "data": { "type": "object" } } } } } }, "responses": { "200": { "description": "Recebido." }, "404": { "description": "Caixa inexistente ou inativa." } } } }, "/webhooks/stripe": { "post": { "tags": [ "Webhooks" ], "summary": "Webhook Stripe", "operationId": "handleStripeWebhook", "security": [], "parameters": [ { "name": "Stripe-Signature", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recebido." }, "400": { "description": "Assinatura inválida." } } } }, "/webhooks/campaign-segments/{token}": { "post": { "tags": [ "Webhooks" ], "summary": "Popula um segmento de campanha (token na URL)", "operationId": "ingestCampaignSegment", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "document": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "tag_ids": { "type": "array", "items": { "type": "integer" } }, "contacts": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "Processado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "list": { "type": "string" }, "added": { "type": "integer" }, "updated": { "type": "integer" }, "skipped": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/webhooks/campaigns/{token}": { "post": { "tags": [ "Webhooks" ], "summary": "Dispara uma campanha por webhook (token na URL)", "operationId": "triggerCampaign", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Disparada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "campaign": { "type": "string" }, "status": { "type": "string" }, "recipients": { "type": "integer" } } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/orders/sync": { "post": { "tags": [ "Pedidos" ], "summary": "Sincroniza um pedido por número externo (idempotente)", "description": "Cria o pedido se o external_number não existir no escopo do token; caso exista, atualiza o pedido, substitui os itens e recalcula o total. Retorna 201 na criação e 200 na atualização.", "operationId": "syncOrder", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_number", "contact_id" ], "properties": { "external_number": { "type": "string", "description": "Identificador do pedido no sistema de origem (chave de sincronização)." }, "contact_id": { "type": "integer" }, "conversation_id": { "type": [ "integer", "null" ] }, "opportunity_id": { "type": [ "integer", "null" ] }, "proposal_id": { "type": [ "integer", "null" ] }, "number": { "type": [ "string", "null" ], "description": "Número interno; gerado automaticamente na criação se omitido." }, "currency": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ], "enum": [ "draft", "confirmed", "shipped", "invoiced", "paid", "cancelled", null ] }, "notes": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "required": [ "description", "quantity", "unit_price" ], "properties": { "description": { "type": "string" }, "quantity": { "type": "number" }, "unit_price": { "type": "number" }, "discount": { "type": [ "number", "null" ] } } } } } } } } }, "responses": { "200": { "description": "Pedido atualizado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "201": { "description": "Pedido criado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Order" } } } }, "422": { "description": "Contrato inválido." } } } } } }