{
  "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
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/messages/send": {
      "post": {
        "summary": "Disparo direto de mensagem RCS individual/transacional",
        "description": "Envia uma mensagem rica imediata via protocolo RCS (Google Mensagens) com texto, botoes interativos (CTA) e midia opcional (URL publica ou anexo local).",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "phone",
                  "message"
                ],
                "properties": {
                  "phone": {
                    "type": "string",
                    "example": "5511999998888"
                  },
                  "message": {
                    "type": "string",
                    "example": "Olá {{nome}}, seu pedido foi atualizado!"
                  },
                  "name": {
                    "type": "string",
                    "example": "João da Silva"
                  },
                  "media_url": {
                    "type": "string",
                    "example": "https://rcsultra.online/uploads/promo.jpg"
                  },
                  "button_text": {
                    "type": "string",
                    "example": "Acompanhar Pedido"
                  },
                  "button_url": {
                    "type": "string",
                    "example": "https://minhaloja.com/pedido/123"
                  },
                  "device_id": {
                    "type": "integer",
                    "example": 14
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mensagem despachada com sucesso",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "example": true
                    },
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "dispatch_id": {
                      "type": "integer",
                      "example": 1
                    },
                    "message_id": {
                      "type": "string",
                      "example": "rcs_1731700000000"
                    },
                    "phone": {
                      "type": "string",
                      "example": "5511999998888"
                    },
                    "status": {
                      "type": "string",
                      "example": "sent"
                    },
                    "remaining_credits": {
                      "type": "integer",
                      "example": 4999
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parametros invalidos"
          },
          "401": {
            "description": "API Key ou token invalido"
          },
          "502": {
            "description": "Falha na conexao com o aparelho/Google Messages"
          }
        }
      }
    },
    "/api/v1/crm/webhook": {
      "post": {
        "summary": "Webhook universal de integracao para CRMs e Automacoes",
        "description": "Recebe webhooks de plataformas de CRM (Kommo, HubSpot, RD Station, ActiveCampaign, Pipedrive) ou automacoes (n8n, Make, Zapier, Kiwify, Hotmart) e dispara automaticamente a mensagem RCS interpolando variaveis dinâmicas como {{nome}}, {{primeiro_nome}}, {{telefone}}, {{empresa}}, etc.",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "api_key",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Chave de API pode ser passada via query string na URL do webhook"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone": {
                    "type": "string",
                    "example": "5538999998888"
                  },
                  "name": {
                    "type": "string",
                    "example": "Maria Souza"
                  },
                  "email": {
                    "type": "string",
                    "example": "maria@empresa.com"
                  },
                  "company": {
                    "type": "string",
                    "example": "Studio Dental"
                  },
                  "event": {
                    "type": "string",
                    "example": "lead_created"
                  },
                  "template": {
                    "type": "string",
                    "example": "Olá {{primeiro_nome}}, recebemos seu contato na {{empresa}} e entraremos em contato em instantes!"
                  },
                  "button_text": {
                    "type": "string",
                    "example": "Falar Agora no WhatsApp"
                  },
                  "button_url": {
                    "type": "string",
                    "example": "https://wa.me/5538999999999"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Lead recebido e mensagem RCS despachada"
          },
          "400": {
            "description": "Telefone nao localizado no payload do CRM"
          }
        }
      }
    },
    "/api/v1/api-key": {
      "get": {
        "summary": "Consultar dados da API Key e URLs de integracao",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Dados da API Key e endpoints do usuario"
          }
        }
      }
    },
    "/api/v1/api-key/regenerate": {
      "post": {
        "summary": "Regenerar Chave de API do usuario",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Nova API Key gerada"
          }
        }
      }
    },
    "/api/v1/messages/history": {
      "get": {
        "summary": "Consultar historico de disparos transacionais da API e CRM",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Historico de disparos"
          }
        }
      }
    },
    "/api/v1/messages/status/{id}": {
      "get": {
        "summary": "Consultar status de entrega de um disparo individual",
        "security": [
          {
            "ApiKeyAuth": []
          },
          {
            "BearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status do disparo"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Token JWT de sessao ou Chave de API rcs_live_..."
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Chave de API persistente no formato rcs_live_..."
      }
    }
  }
}