{"openapi":"3.0.3","info":{"title":"Nexus Atendimento API","version":"1.1.0","description":"API REST para integrações externas e área do cliente.\n\n## Autenticação API v1\nCrie a chave em **Integrações → Chaves de API**.\nEnvie `Authorization: Bearer nxz_...` ou header `X-API-Key: nxz_...`.\n\n## Webhooks outbound\nConfigure em **Integrações → Webhooks**. O Nexus envia POST JSON com assinatura opcional `X-Nexus-Signature: sha256=...` (HMAC do body com o secret).\n\n## Portal do cliente\nRotas em `/api/public/portal/*` — OTP WhatsApp e faturas. Não usam API key; usam token de sessão do portal.","contact":{"name":"Vollio / Nexus","url":"https://molt.lojanexus.com.br"}},"servers":[{"url":"https://molt.lojanexus.com.br/api/v1","description":"API v1 (API key)"},{"url":"https://molt.lojanexus.com.br/api/public","description":"Rotas públicas (portal)"}],"tags":[{"name":"Conversas","description":"Inbox / WhatsApp (API key)"},{"name":"Clientes","description":"CRM (API key)"},{"name":"Portal","description":"Área do cliente (público + sessão OTP)"},{"name":"Webhooks","description":"Eventos enviados pelo Nexus para a sua URL"},{"name":"Meta","description":"Documentação OpenAPI"}],"security":[{"ApiKeyAuth":[]},{"ApiKeyHeader":[]}],"paths":{"/openapi.json":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Meta"],"summary":"Especificação OpenAPI (JSON)","security":[],"responses":{"200":{"description":"Documento OpenAPI 3.0.3","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/docs":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Meta"],"summary":"Swagger UI","security":[],"responses":{"200":{"description":"HTML Swagger UI"}}}},"/conversations":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Conversas"],"summary":"Listar conversas","operationId":"listConversations","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Máximo de registros (default 50, máx. 200)"},{"name":"status","in":"query","schema":{"type":"string","enum":["bot_ativo","em_atendimento","aguardando_humano","encerrado"]},"description":"Filtro opcional por status"}],"responses":{"200":{"description":"Lista de conversas","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"example":[{"id":42,"phone":"5511999999999","name":"Maria Silva","status":"em_atendimento","operator_id":null,"channel_id":1,"created_at":"2026-09-01T12:00:00.000Z","updated_at":"2026-09-04T10:00:00.000Z"}]}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/conversations/{phone}/messages":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Conversas"],"summary":"Listar mensagens de uma conversa","operationId":"listMessages","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string","example":"5511999999999"},"description":"Telefone só dígitos (com DDI)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}}],"responses":{"200":{"description":"Mensagens (mais recentes primeiro)","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Conversa não encontrada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Conversa não encontrada"}}}},"500":{"$ref":"#/components/responses/ServerError"}}},"post":{"tags":["Conversas"],"summary":"Enviar mensagem de texto no WhatsApp","operationId":"sendMessage","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string","example":"5511999999999"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageRequest"},"examples":{"text":{"summary":"Texto simples","value":{"text":"Olá! Recebemos sua mensagem."}},"alias":{"summary":"Campo message (alias)","value":{"message":"Olá!"}}}}}},"responses":{"201":{"description":"Mensagem enviada e gravada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"},"example":{"ok":true,"message_id":9001,"conversation_id":42,"phone":"5511999999999"}}}},"400":{"description":"Parâmetros inválidos","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"phone e text são obrigatórios"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"},"502":{"description":"Falha no provedor WhatsApp","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Falha ao enviar no WhatsApp"}}}}}}},"/clients":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Clientes"],"summary":"Listar clientes","operationId":"listClients","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":100}},{"name":"phone","in":"query","schema":{"type":"string","example":"1199999"},"description":"Filtro parcial por telefone (LIKE)"}],"responses":{"200":{"description":"Lista de clientes","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Client"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}},"/clients/{id}":{"servers":[{"url":"https://molt.lojanexus.com.br/api/v1"}],"get":{"tags":["Clientes"],"summary":"Detalhe do cliente","operationId":"getClient","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","example":15}}],"responses":{"200":{"description":"Cliente","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Não encontrado","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Cliente não encontrado"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/portal/config":{"servers":[{"url":"https://molt.lojanexus.com.br/api/public"}],"get":{"tags":["Portal"],"summary":"Config pública da área do cliente","operationId":"portalConfig","security":[],"parameters":[{"name":"c","in":"query","schema":{"type":"integer"},"description":"company_id"},{"name":"slug","in":"query","schema":{"type":"string"},"description":"slug da empresa"}],"responses":{"200":{"description":"Configuração","content":{"application/json":{"schema":{"type":"object"}}}},"403":{"description":"Portal desativado"},"404":{"description":"Empresa não encontrada"}}}},"/portal/request-otp":{"servers":[{"url":"https://molt.lojanexus.com.br/api/public"}],"post":{"tags":["Portal"],"summary":"Solicitar OTP no WhatsApp","operationId":"portalRequestOtp","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","example":"5511999999999"},"company_id":{"type":"integer"},"slug":{"type":"string"}}}}}},"responses":{"200":{"description":"OTP enviado","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"message":{"type":"string"},"expires_in_seconds":{"type":"integer"}}}}}},"400":{"description":"Telefone inválido ou não cadastrado"},"404":{"description":"Empresa não encontrada"}}}},"/portal/verify-otp":{"servers":[{"url":"https://molt.lojanexus.com.br/api/public"}],"post":{"tags":["Portal"],"summary":"Validar OTP e obter token de sessão","operationId":"portalVerifyOtp","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["phone","code"],"properties":{"phone":{"type":"string"},"code":{"type":"string","example":"123456"},"company_id":{"type":"integer"},"slug":{"type":"string"}}}}}},"responses":{"200":{"description":"Sessão criada","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"token":{"type":"string","description":"Bearer para /portal/me"}}}}}},"400":{"description":"Código inválido"}}}},"/portal/me":{"servers":[{"url":"https://molt.lojanexus.com.br/api/public"}],"get":{"tags":["Portal"],"summary":"Dashboard do cliente (faturas, dados)","operationId":"portalMe","security":[{"PortalBearer":[]}],"responses":{"200":{"description":"Dashboard do cliente"},"401":{"description":"Sessão expirada"}}}},"/portal/invoices/{id}/payment-link":{"servers":[{"url":"https://molt.lojanexus.com.br/api/public"}],"post":{"tags":["Portal"],"summary":"Gerar/obter link de pagamento da fatura","operationId":"portalPaymentLink","security":[{"PortalBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Link gerado"},"400":{"description":"Fatura inválida"},"401":{"description":"Sessão expirada"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"nxz_","description":"Authorization: Bearer nxz_..."},"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternativa ao Bearer"},"PortalBearer":{"type":"http","scheme":"bearer","description":"Token retornado por POST /portal/verify-otp"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}},"required":["error"]},"Conversation":{"type":"object","properties":{"id":{"type":"integer"},"phone":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"operator_id":{"type":"integer","nullable":true},"channel_id":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"integer"},"role":{"type":"string","description":"user | bot | human | system","example":"user"},"content":{"type":"string"},"media_type":{"type":"string","nullable":true},"operator_id":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"SendMessageRequest":{"type":"object","properties":{"text":{"type":"string","description":"Texto a enviar"},"message":{"type":"string","description":"Alias de text"}}},"SendMessageResponse":{"type":"object","properties":{"ok":{"type":"boolean"},"message_id":{"type":"integer"},"conversation_id":{"type":"integer"},"phone":{"type":"string"}}},"Client":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"status":{"type":"string","nullable":true},"plan_id":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ClientDetail":{"allOf":[{"$ref":"#/components/schemas/Client"},{"type":"object","properties":{"notes":{"type":"string","nullable":true}}}]},"WebhookEnvelope":{"type":"object","description":"Body POST enviado aos endpoints configurados","required":["event","timestamp","company_id","data"],"properties":{"event":{"type":"string","enum":["message.in","payment.confirmed","transfer.human"]},"timestamp":{"type":"string","format":"date-time"},"company_id":{"type":"integer"},"data":{"type":"object"}}},"WebhookMessageIn":{"type":"object","properties":{"phone":{"type":"string"},"message_id":{"type":"string"},"type":{"type":"string","example":"text"},"text":{"type":"string"},"conversation_id":{"type":"string"},"channel":{"type":"string","example":"whatsapp"},"client_id":{"type":"string","nullable":true}}},"WebhookPaymentConfirmed":{"type":"object","properties":{"invoice_id":{"type":"integer"},"invoice_number":{"type":"string","nullable":true},"client_id":{"type":"integer"},"client_name":{"type":"string","nullable":true},"amount":{"type":"number"},"payment_date":{"type":"string"},"payment_id":{"type":"integer"}}},"WebhookTransferHuman":{"type":"object","properties":{"phone":{"type":"string"},"source":{"type":"string","example":"transferir_para_humano"},"reason":{"type":"string"},"conversation_id":{"type":"integer"}}}},"responses":{"Unauthorized":{"description":"API key inválida, ausente ou revogada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing":{"value":{"error":"API key inválida ou ausente"}},"revoked":{"value":{"error":"API key inválida ou revogada"}}}}}},"ServerError":{"description":"Erro interno","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"x-webhook-events":["message.in","payment.confirmed","transfer.human"],"x-webhooks":{"description":"Configure a URL em Integrações. Header X-Nexus-Signature: sha256=<hmac-sha256-hex do body> quando secret estiver definido.","events":{"message.in":{"summary":"Mensagem inbound (WhatsApp / e-mail)","payload":{"$ref":"#/components/schemas/WebhookMessageIn"},"example":{"event":"message.in","timestamp":"2026-09-04T12:00:00.000Z","company_id":1,"data":{"phone":"5511999999999","message_id":"123","type":"text","text":"Oi","conversation_id":"42"}}},"payment.confirmed":{"summary":"Pagamento confirmado / baixa de fatura","payload":{"$ref":"#/components/schemas/WebhookPaymentConfirmed"},"example":{"event":"payment.confirmed","timestamp":"2026-09-04T12:05:00.000Z","company_id":1,"data":{"invoice_id":88,"client_id":15,"amount":49.9,"payment_date":"2026-09-04","payment_id":501}}},"transfer.human":{"summary":"Transferência para atendimento humano","payload":{"$ref":"#/components/schemas/WebhookTransferHuman"},"example":{"event":"transfer.human","timestamp":"2026-09-04T12:10:00.000Z","company_id":1,"data":{"phone":"5511999999999","source":"transferir_para_humano","reason":"Cliente pediu atendente","conversation_id":42}}}}}}