{
  "openapi": "3.1.0",
  "info": {
    "title": "RCS Ultra Public REST API",
    "version": "1.0.0",
    "description": "API oficial do RCS Ultra para despacho de campanhas em massa e mensagens transacionais via protocolo Google Mensagens RCS em Android e iOS 18. Inclui suporte a webhooks, tokens dinâmicos de rastreamento e gestão de dispositivos conectados.",
    "contact": {
      "name": "Suporte Técnico RCS Ultra",
      "url": "https://rcsultra.online",
      "email": "contato@rcsultra.online"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://rcsultra.online/terms"
    }
  },
  "servers": [
    {
      "url": "https://rcsultra.online",
      "description": "Servidor de Produção Oficial"
    }
  ],
  "paths": {
    "/api/v1/auth/login": {
      "post": {
        "summary": "Autenticar usuário e obter token JWT",
        "description": "Recebe e-mail e senha do cliente e retorna o token de autenticação Bearer para consumo da API.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "format": "email",
                    "example": "usuario@empresa.com"
                  },
                  "password": {
                    "type": "string",
                    "format": "password",
                    "example": "SenhaSegura123"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Autenticação bem-sucedida",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "token": {
                      "type": "string",
                      "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
                    },
                    "user": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "integer",
                          "example": 142
                        },
                        "name": {
                          "type": "string",
                          "example": "Minha Empresa"
                        },
                        "email": {
                          "type": "string",
                          "example": "usuario@empresa.com"
                        },
                        "credits": {
                          "type": "integer",
                          "example": 5000
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Credenciais inválidas"
          }
        }
      }
    },
    "/api/devices": {
      "get": {
        "summary": "Listar aparelhos conectados para disparo",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Lista de aparelhos conectados",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "integer",
                        "example": 1
                      },
                      "name": {
                        "type": "string",
                        "example": "Samsung Galaxy S24 Ultra"
                      },
                      "phone": {
                        "type": "string",
                        "example": "5511999998888"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "connected",
                          "offline",
                          "pairing"
                        ],
                        "example": "connected"
                      },
                      "battery": {
                        "type": "integer",
                        "example": 94
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/devices/{id}/test-send": {
      "post": {
        "summary": "Enviar mensagem RCS individual imediata",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "message"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "example": "5511987654321"
                  },
                  "message": {
                    "type": "string",
                    "example": "Olá João! Seu pedido #1042 foi enviado com sucesso."
                  },
                  "media_url": {
                    "type": "string",
                    "format": "uri",
                    "example": "https://meusite.com/banner-promocao.jpg"
                  },
                  "buttons": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "text": {
                          "type": "string",
                          "example": "Rastrear Pedido"
                        },
                        "url": {
                          "type": "string",
                          "example": "https://meusite.com/rastreio/1042"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensagem enviada com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message_id": {
                      "type": "string",
                      "example": "msg_9f821a0c"
                    },
                    "protocol": {
                      "type": "string",
                      "example": "RCS"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/campaigns": {
      "post": {
        "summary": "Criar e agendar campanha de disparo em massa",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "message",
                  "contacts"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "example": "Campanha Black Friday 2026"
                  },
                  "message": {
                    "type": "string",
                    "example": "Cupom de 20% OFF liberado só hoje!"
                  },
                  "contacts": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "example": [
                      "5511999990001",
                      "5511999990002"
                    ]
                  },
                  "delay_seconds": {
                    "type": "integer",
                    "example": 8
                  },
                  "media_url": {
                    "type": "string",
                    "example": "https://rcsultra.online/uploads/promo.jpg"
                  },
                  "action_url": {
                    "type": "string",
                    "example": "https://minhaloja.com/promo"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Campanha criada com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "campaign_id": {
                      "type": "integer",
                      "example": 89
                    },
                    "total_contacts": {
                      "type": "integer",
                      "example": 2500
                    },
                    "status": {
                      "type": "string",
                      "example": "ready"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/campaigns/{id}/dispatch-cloud": {
      "post": {
        "summary": "Iniciar despacho da campanha em nuvem 24/7",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 89
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Despacho iniciado em background na nuvem",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "status": {
                      "type": "string",
                      "example": "running"
                    },
                    "message": {
                      "type": "string",
                      "example": "Campanha despachando na nuvem 24/7"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/campaigns/{id}/report": {
      "get": {
        "summary": "Obter relatório analítico e métricas da campanha",
        "security": [
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "example": 89
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Relatório consolidado de entrega e cliques",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "campaign_id": {
                      "type": "integer",
                      "example": 89
                    },
                    "sent": {
                      "type": "integer",
                      "example": 2490
                    },
                    "delivered": {
                      "type": "integer",
                      "example": 2415
                    },
                    "read": {
                      "type": "integer",
                      "example": 2230
                    },
                    "clicks": {
                      "type": "integer",
                      "example": 864
                    },
                    "failed": {
                      "type": "integer",
                      "example": 10
                    },
                    "open_rate_percent": {
                      "type": "number",
                      "example": 92.3
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Insira o token JWT retornado em /api/v1/auth/login"
      }
    }
  }
}