{
  "openapi": "3.1.0",
  "info": {
    "title": "Combot API",
    "version": "1.0.0",
    "description": "O Combot e a CONEXAO da empresa com o WhatsApp: entrega e recebe mensagens. Fluxo: seu sistema chama a API -> o Combot entrega no WhatsApp do cliente; o cliente responde -> o Combot repassa ao seu sistema por webhook. Se voce JA TEM um sistema (ERP / provedor de internet / CRM), o Combot e so o transporte e quem decide a resposta e o SEU sistema (a IA do Combot fica desligada). Se voce NAO TEM sistema, use a IA treinavel do Combot, que responde sozinha.",
    "contact": {
      "url": "https://combot.com.br/docs"
    }
  },
  "servers": [
    {
      "url": "https://combot.com.br/api/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/messages": {
      "post": {
        "summary": "Enviar mensagem de WhatsApp",
        "operationId": "sendMessage",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "description": "Telefone em formato internacional só com dígitos, ex.: 5511999998888"
                  },
                  "conversationId": {
                    "type": "string",
                    "description": "Alternativa a 'to': responde uma conversa existente"
                  },
                  "text": {
                    "type": "string",
                    "description": "Texto da mensagem"
                  },
                  "footer": {
                    "type": "string",
                    "description": "Rodape opcional, exibido abaixo da mensagem com botoes"
                  },
                  "buttons": {
                    "type": "array",
                    "maxItems": 3,
                    "description": "Opcional: botoes nativos de COPIAR (ex.: PIX, boleto). O Combot tambem envia cada codigo numa mensagem propria dentro de um bloco de codigo, porque um codigo solto (o PIX contem br.gov.bcb.pix) vira LINK no WhatsApp e o cliente acaba copiando so um pedaco.",
                    "items": {
                      "type": "object",
                      "required": [
                        "displayText",
                        "copyCode"
                      ],
                      "properties": {
                        "displayText": {
                          "type": "string",
                          "maxLength": 25,
                          "description": "Texto do botao, ex.: Copiar codigo Pix"
                        },
                        "copyCode": {
                          "type": "string",
                          "description": "Conteudo copiado ao tocar no botao (PIX copia-e-cola ou linha digitavel do boleto)"
                        }
                      }
                    }
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "document",
                      "image"
                    ],
                    "description": "Envio de MIDIA: \"document\" (PDF do boleto — vira cartao com nome do arquivo e botao de baixar) ou \"image\" (QR Code do PIX). Com type + url, o campo text nao e obrigatorio."
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "URL PUBLICA do arquivo/imagem (o Combot baixa para enviar). Obrigatorio quando type e informado."
                  },
                  "filename": {
                    "type": "string",
                    "description": "Nome exibido do arquivo (ex.: Fatura.pdf). So para type=document."
                  },
                  "caption": {
                    "type": "string",
                    "description": "Legenda exibida junto do arquivo/imagem (ex.: \"Total: R$ 119,90\")."
                  }
                },
                "required": [
                  "text"
                ]
              },
              "examples": {
                "porTelefone": {
                  "value": {
                    "to": "5511999998888",
                    "text": "Olá! Recebemos seu pedido."
                  }
                },
                "porConversa": {
                  "value": {
                    "conversationId": "clx123",
                    "text": "Seu protocolo é #4821."
                  }
                },
                "comBotoesCopiar": {
                  "summary": "Cobranca com botoes de copiar (PIX e boleto)",
                  "value": {
                    "to": "5511999998888",
                    "text": "*PIX copia-e-cola* - R$ 119,90",
                    "footer": "Fast Telekom",
                    "buttons": [
                      {
                        "displayText": "Copiar codigo Pix",
                        "copyCode": "00020126..."
                      },
                      {
                        "displayText": "Copiar codigo do boleto",
                        "copyCode": "34191.79001..."
                      }
                    ]
                  }
                },
                "pdfDoBoleto": {
                  "summary": "PDF do boleto (cartao com o arquivo)",
                  "value": {
                    "to": "5511999998888",
                    "type": "document",
                    "url": "https://exemplo.com/boleto.pdf",
                    "filename": "Fatura.pdf",
                    "caption": "Total: R$ 119,90"
                  }
                },
                "qrCodePix": {
                  "summary": "QR Code do PIX (imagem)",
                  "value": {
                    "to": "5511999998888",
                    "type": "image",
                    "url": "https://exemplo.com/qrcode-pix.png",
                    "caption": "Aponte a camera do banco e pague"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensagem enfileirada/enviada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "simulated": {
                      "type": "boolean"
                    },
                    "messageId": {
                      "type": "string"
                    },
                    "conversationId": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token ausente ou inválido"
          },
          "403": {
            "description": "Plano sem acesso à API"
          },
          "409": {
            "description": "Nenhum canal de WhatsApp conectado"
          },
          "429": {
            "description": "Limite de requisições excedido"
          }
        }
      }
    },
    "/ai/reply": {
      "post": {
        "summary": "Gerar resposta da IA",
        "operationId": "aiReply",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string"
                  }
                },
                "required": [
                  "message"
                ]
              },
              "examples": {
                "pergunta": {
                  "value": {
                    "message": "vocês entregam em Curitiba?"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Resposta gerada",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "reply": {
                      "type": "string"
                    },
                    "handoff": {
                      "type": "boolean",
                      "description": "true = sugere transferir para humano"
                    },
                    "tokensIn": {
                      "type": "integer"
                    },
                    "tokensOut": {
                      "type": "integer"
                    },
                    "simulated": {
                      "type": "boolean",
                      "description": "true quando nenhuma chamada real ao provedor de IA foi feita"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Token ausente ou inválido"
          },
          "403": {
            "description": "Plano sem acesso à API"
          },
          "429": {
            "description": "Limite de requisições excedido"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key da empresa (Integrações). Ex.: cb_live_..."
      }
    }
  }
}