{
  "openapi": "3.0.3",
  "info": {
    "title": "Primux Omni — API de Integrações",
    "version": "1.0.0",
    "description": "Envie mensagens WhatsApp pelo Primux Omni. Toda mensagem enviada por esta API pausa a automação do atendimento para que o chatbot não responda no ticket criado ou utilizado."
  },
  "servers": [
    {
      "url": "https://seu-dominio.com",
      "description": "Substitua pelo endereço da sua instalação."
    }
  ],
  "tags": [
    {
      "name": "Mensagens",
      "description": "Envio de mensagens e consulta de atendimentos."
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/integracoes/mensagens": {
      "post": {
        "tags": ["Mensagens"],
        "summary": "Enviar mensagem",
        "description": "Envia uma mensagem pública para um contato. O contato pode ser informado por contato_id ou telefone. Se não houver atendimento aberto e criar_atendimento for true (padrão), um novo atendimento é criado. A automação do atendimento é sempre pausada.",
        "operationId": "enviarMensagem",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnvioMensagem"
              },
              "examples": {
                "telefone": {
                  "summary": "Contato novo por telefone",
                  "value": {
                    "telefone": "+55 (11) 99999-9999",
                    "nome_contato": "Maria Silva",
                    "mensagem": "Olá, Maria! Sua fatura já está disponível."
                  }
                },
                "contato": {
                  "summary": "Contato existente",
                  "value": {
                    "contato_id": "1d9a7e42-0000-0000-0000-000000000000",
                    "mensagem": "Seu pedido foi enviado.",
                    "metadados": {
                      "pedido_id": "PED-123"
                    }
                  }
                },
                "imagem": {
                  "summary": "Imagem com legenda",
                  "value": {
                    "telefone": "5511999999999",
                    "tipo_midia": "imagem",
                    "url_arquivo": "https://cdn.exemplo.com/fatura.png",
                    "mensagem": "Segue sua fatura."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mensagem enviada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RespostaEnvio"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Erro400"
          },
          "401": {
            "$ref": "#/components/responses/Erro401"
          },
          "403": {
            "$ref": "#/components/responses/Erro403"
          },
          "404": {
            "$ref": "#/components/responses/Erro404"
          },
          "409": {
            "$ref": "#/components/responses/Erro409"
          },
          "503": {
            "$ref": "#/components/responses/Erro503"
          }
        }
      }
    },
    "/api/v1/publico/mensagens": {
      "post": {
        "tags": ["Mensagens"],
        "summary": "Enviar mensagem (legado)",
        "description": "Contrato antigo mantido por compatibilidade. Aceita apenas contato_id e mensagem e exige um atendimento aberto. Prefira /api/v1/integracoes/mensagens.",
        "operationId": "enviarMensagemLegado",
        "deprecated": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["contato_id", "mensagem"],
                "properties": {
                  "contato_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "mensagem": {
                    "type": "string",
                    "maxLength": 8000
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Mensagem enviada.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Mensagem"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Erro400"
          },
          "401": {
            "$ref": "#/components/responses/Erro401"
          },
          "404": {
            "$ref": "#/components/responses/Erro404"
          },
          "503": {
            "$ref": "#/components/responses/Erro503"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "API key criada em Gestão → API Keys."
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A mesma API key no formato Authorization: Bearer px_..."
      }
    },
    "schemas": {
      "EnvioMensagem": {
        "type": "object",
        "description": "Informe contato_id ou telefone.",
        "properties": {
          "contato_id": {
            "type": "string",
            "format": "uuid",
            "description": "ID do contato no Omni."
          },
          "telefone": {
            "type": "string",
            "description": "Telefone com DDI e DDD. Aceita máscara; os dígitos são normalizados.",
            "example": "5511999999999"
          },
          "nome_contato": {
            "type": "string",
            "description": "Nome usado ao criar um contato novo.",
            "example": "Maria Silva"
          },
          "canal_id": {
            "type": "string",
            "format": "uuid",
            "description": "Canal conectado. Obrigatório quando há mais de um canal conectado."
          },
          "fila_id": {
            "type": "string",
            "format": "uuid",
            "description": "Fila do novo atendimento. Usa a fila padrão do canal quando omitida."
          },
          "usuario_id": {
            "type": "string",
            "format": "uuid",
            "description": "Responsável pelo novo atendimento."
          },
          "mensagem": {
            "type": "string",
            "maxLength": 8000,
            "description": "Texto ou legenda da mídia."
          },
          "tipo_midia": {
            "type": "string",
            "enum": ["texto", "imagem", "audio", "arquivo", "figurinha"],
            "default": "texto"
          },
          "url_arquivo": {
            "type": "string",
            "format": "uri",
            "description": "URL pública da mídia."
          },
          "metadados": {
            "type": "object",
            "additionalProperties": true,
            "description": "Dados auxiliares e opções específicas do canal."
          },
          "criar_atendimento": {
            "type": "boolean",
            "default": true,
            "description": "Com false, exige um atendimento aberto para o contato."
          }
        },
        "anyOf": [
          {
            "required": ["contato_id"]
          },
          {
            "required": ["telefone"]
          }
        ]
      },
      "Mensagem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "empresa_id": {
            "type": "string",
            "format": "uuid"
          },
          "atendimento_id": {
            "type": "string",
            "format": "uuid"
          },
          "remetente_tipo": {
            "type": "string",
            "example": "atendente"
          },
          "autor_nome": {
            "type": "string",
            "example": "API Omni"
          },
          "tipo_midia": {
            "type": "string",
            "example": "texto"
          },
          "conteudo": {
            "type": "string"
          },
          "url_arquivo": {
            "type": "string"
          },
          "id_externo": {
            "type": "string",
            "nullable": true
          },
          "metadados": {
            "type": "object",
            "additionalProperties": true
          },
          "enviado_em": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "RespostaEnvio": {
        "type": "object",
        "properties": {
          "mensagem_id": {
            "type": "string",
            "format": "uuid"
          },
          "atendimento_id": {
            "type": "string",
            "format": "uuid"
          },
          "contato_id": {
            "type": "string",
            "format": "uuid"
          },
          "canal_id": {
            "type": "string",
            "format": "uuid"
          },
          "protocolo": {
            "type": "string",
            "example": "OM-20261108-ABCD"
          },
          "status": {
            "type": "string",
            "example": "enviada"
          },
          "id_externo": {
            "type": "string"
          },
          "enviado_em": {
            "type": "string",
            "format": "date-time"
          },
          "criado": {
            "type": "boolean",
            "description": "Indica se um novo atendimento foi aberto."
          },
          "mensagem": {
            "$ref": "#/components/schemas/Mensagem"
          }
        }
      },
      "Erro": {
        "type": "object",
        "required": ["erro"],
        "properties": {
          "erro": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "Erro400": {
        "description": "Dados inválidos ou campo obrigatório ausente.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Erro401": {
        "description": "API key ausente, inválida ou revogada.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Erro403": {
        "description": "Operação não permitida.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Erro404": {
        "description": "Contato ou atendimento não encontrado.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Erro409": {
        "description": "Atendimento em estado incompatível.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      },
      "Erro503": {
        "description": "Canal desconectado ou indisponível.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Erro"
            }
          }
        }
      }
    }
  }
}
