ReserveGo – Partner Reservations API

ReserveGo – Partner Reservations API
A ReserveGo Partner Reservations API é uma solução REST aberta e robusta, projetada especificamente para permitir que parceiros e integradores consultem e gerenciem reservas de forma segura e eficiente. Esta API representa a ponte tecnológica entre seu sistema e a plataforma ReserveGo, oferecendo integração transparente e confiável. 
Nossa API foi desenvolvida seguindo os mais rigorosos padrões REST, garantindo previsibilidade, facilidade de implementação e manutenibilidade a longo prazo. Com endpoints semânticos e respostas estruturadas em JSON, a integração com seus sistemas existentes se torna simples e direta.
Esta documentação técnica fornece todas as informações necessárias para implementar e manter sua integração com sucesso. Você encontrará especificações detalhadas de endpoints, exemplos práticos de requisições e respostas, além de orientações sobre autenticação, tratamento de erros e regras de negócio essenciais.
🔐 Autenticação e Base URL
Autenticação via Header
Todas as requisições à API ReserveGo DEVEM incluir o header de autenticação partnerAppId. Este token único identifica sua empresa e unidade, garantindo que apenas parceiros autorizados possam acessar os dados de reservas.
O token funciona como uma credencial de acesso que vincula cada requisição à sua organização específica. Ele deve ser incluído em todas as chamadas HTTP, independentemente do endpoint ou método utilizado.
partnerAppId: SEU_TOKEN_DE_INTEGRAÇÃO
Para solicitar seu token de integração, entre em contato com a equipe técnica da ReserveGo. Cada token é único e deve ser mantido em segurança, nunca sendo exposto em código cliente ou repositórios públicos.
Possíveis Erros de Autenticação
Base URL
Todas as requisições devem ser direcionadas para:
https://api.reservego.com.br/app/auth/v3
📌 Endpoints Disponíveis
GET /reservas
Endpoint principal para listagem e consulta de reservas com suporte a múltiplos filtros opcionais
DELETE /reservas/cancelar/{id}
Endpoint para cancelamento lógico de reservas específicas pelo ID
⚠️ Observação Crítica sobre o Modelo de Negócio
É fundamental entender que todas as reservas no sistema ReserveGo já nascem confirmadas. Isso significa que não existe e não deve existir um endpoint de confirmação (PUT ou PATCH) na API.
O modelo de negócio da plataforma pressupõe que toda reserva criada está automaticamente confirmada e ativa. O parceiro integrado possui apenas duas ações possíveis: consultar reservas existentes ou cancelar reservas quando necessário.
Esta decisão de design simplifica drasticamente o fluxo de integração e reduz a complexidade operacional, eliminando estados intermediários desnecessários no ciclo de vida de uma reserva.
🟢 GET – Consultar Reservas
O endpoint GET /reservas é o ponto central de consulta da API, oferecendo grande flexibilidade através de parâmetros de query opcionais. Este endpoint retorna todas as reservas vinculadas à empresa e unidade autenticadas via token, permitindo filtros específicos para localizar exatamente as informações necessárias.
Endpoint Base
GET /reservas
Retorna todas as reservas da unidade autenticada sem aplicar filtros
Flexibilidade Total
Os parâmetros de query podem ser combinados livremente, permitindo consultas extremamente específicas ou amplas conforme a necessidade da integração
🔎 Query Parameters Disponíveis
Todos os parâmetros são opcionais e podem ser utilizados individualmente ou em combinação:
💡 Estratégias de Consulta
Consulta por Período
Combine data_inicio e data_fim para obter todas as reservas de um intervalo específico, ideal para relatórios e análises
Consulta por Cliente
Use o parâmetro telefone para localizar todas as reservas de um cliente específico, facilitando o atendimento
Consulta Específica
Utilize o ID quando você já conhece a reserva exata que precisa consultar, otimizando a performance
📥 Exemplos Práticos de Requisição GET
Apresentamos abaixo uma série de exemplos reais demonstrando as diversas possibilidades de consulta oferecidas pelo endpoint GET /reservas. Cada exemplo ilustra um caso de uso específico, desde consultas amplas até buscas extremamente direcionadas.
01
Consulta Geral
Retorna todas as reservas da unidade autenticada
02
Consulta por Período
Filtra reservas em um intervalo de datas específico
03
Consulta por Cliente
Localiza reservas usando o telefone do cliente
04
Consulta por ID
Busca uma reserva específica pelo identificador
05
Consulta Combinada
Utiliza múltiplos filtros simultaneamente
Exemplo 1: Listagem Completa
GET /reservas
Retorna todas as reservas disponíveis para a empresa e unidade autenticadas, sem aplicar qualquer filtro.
Exemplo 2: Filtro por Período Específico
GET /reservas?data_inicio=2025-12-20&data_fim=2025-12-20
Retorna todas as reservas agendadas exatamente para o dia 20 de dezembro de 2025. Útil para visualizar a agenda de um dia específico.
Exemplo 3: Busca por Telefone do Cliente
GET /reservas?telefone=21969399622
Localiza todas as reservas associadas ao número de telefone informado, independente da data. Ideal para consultas no atendimento ao cliente.
Exemplo 4: Consulta de Reserva Específica
GET /reservas?id=11972
Retorna apenas a reserva com ID 11972. Este tipo de consulta é a mais performática quando você já possui o identificador da reserva.
Exemplo 5: Combinação de Filtros
GET /reservas?id=11972&telefone=21969399622
Demonstra a capacidade de combinar múltiplos parâmetros. Neste caso, busca a reserva 11972 que também esteja associada ao telefone especificado, adicionando uma camada extra de validação.
📤 Estrutura da Resposta GET
Quando uma requisição GET é bem-sucedida (status 200), a API retorna um objeto JSON estruturado contendo informações agregadas sobre as reservas e um array detalhado com cada reserva individual. A estrutura foi projetada para fornecer tanto visões macro (estatísticas gerais) quanto micro (detalhes de cada reserva) em uma única resposta.
Campos de Nível Superior
Identificação
empresa, unidade: Identificam a origem das reservas retornadas
Período
data_inicio, data_fim: Definem o intervalo de datas consultado
Estatísticas
Diversos campos total_* fornecem agregações úteis
Array de Reservas
reservas: Contém objetos detalhados de cada reserva
Exemplo Completo de Resposta (200 OK)
{
  "empresa": "RESERVEGO",
  "unidade": "UNIDADE BARRA",
  "data_inicio": "2025-12-20",
  "data_fim": "2025-12-20",
  "total_reservas": 1,
  "total_clientes": 1,
  "total_reservas_por_pessoas": 1,
  "total_pessoas_compareceram": 0,
  "total_checkin_geral": 0,
  "total_nao_compareceram": 0,
  "total_cancelados": 1,
  "total_pessoas_fila": 0,
  "reservas": [
    {
      "id": 11972,
      "cod_checkin": "88625",
      "identificacao_cliente": 6679,
      "cliente": "Ricardo Cavalini",
      "telefone": "(21) 96939-9622",
      "email": "oricardocavalini@gmail.com",
      "data_nascimento": "1995-09-04",
      "data_reserva": "2025-12-20",
      "horario_reserva": "19:00",
      "qtd_pessoas": 1,
      "em_espera": "Não",
      "confirmado": "Não",
      "interacao_cliente": "Não",
      "cancelado": "Sim",
      "cancelamento_origem": "Cancelado por colaborador",
      "compareceu": "Não",
      "nao_compareceu": "Não",
      "pessoas_compareceram": 0,
      "observacao": "",
      "realizado_por": "Ricardo Cavalini",
      "cancelado_por": "API Partner",
      "data_registro": "2025-12-20 01:48:39",
      "ultima_alteracao": "2025-12-20 02:34:20"
    }
  ]
}
Campos do Objeto Reserva
Identificação
id: Identificador único da reserva
cod_checkin: Código de check-in
identificacao_cliente: ID do cliente
Dados do Cliente
cliente: Nome completo
telefone: Telefone formatado
email: E-mail de contato
data_nascimento: Data de nascimento
Dados da Reserva
data_reserva: Data agendada
horario_reserva: Horário agendado
qtd_pessoas: Quantidade de pessoas
Status da Reserva
em_espera: Se está em lista de espera
confirmado: Status de confirmação (sempre "Sim")
interacao_cliente: Se o cliente cliquei em manter a reserva 
cancelado: Se foi cancelada
cancelamento_origem: Origem do cancelamento
Check-in e Comparecimento
compareceu: Se o cliente compareceu
nao_compareceu: Se houve falta
pessoas_compareceram: Quantidade que compareceu
Metadados
observacao: Observações adicionais
realizado_por: Quem criou a reserva
cancelado_por: Quem cancelou (se aplicável)
data_registro: Timestamp de criação
ultima_alteracao: Último update
🔴 DELETE – Cancelar Reserva
O endpoint DELETE /reservas/cancelar/{id} permite o cancelamento lógico (soft delete) de reservas existentes. É importante compreender que este não é um cancelamento físico: a reserva permanece registrada no banco de dados para fins de histórico, auditoria e análise, mas seu status é alterado para cancelado, tornando-a inativa para fins operacionais.
Endpoint
DELETE /reservas/cancelar/{id}
Path Parameter
id (int): Identificador único da reserva a ser cancelada
Comportamento
Soft delete: mantém histórico completo da reserva
📥 Exemplo de Requisição
DELETE https://api.reservego.com.br/app/auth/v3/reservas/cancelar/11972

Headers:
partnerAppId: SEU_TOKEN_DE_INTEGRAÇÃO
📤 Resposta de Sucesso (200 OK)
{
  "status": "ok",
  "mensagem": "Reserva cancelada com sucesso"
}
⚠️ Códigos de Erro da API

🔵 PATCH – Atualizar Interação do Cliente
Este endpoint é utilizado para atualizar o campo interacao_cliente para SIM, indicando que o cliente interagiu com a confirmação da reserva. Essa ação é fundamental para rastrear o engajamento do cliente.
Endpoint
PATCH /auth/v3/reservas/atualizar?id={id}
Query Parameter
id (integer, required): ID da reserva a ser atualizada
Comportamento
Valida existência da reserva e pertencimento à empresa/unidade autenticada, atualiza interacao_cliente para SIM.
📥 Exemplo de Requisição
PATCH https://api.reservego.com.br/app/auth/v3/reservas/atualizar?id=11972

Headers:
partnerAppId: SEU_TOKEN_DE_INTEGRAÇÃO
📤 Resposta de Sucesso (200 OK)
{
  "status": "ok",
  "mensagem": "Interação do cliente atualizada com sucesso"
}
⚠️ Códigos de Erro da API
🧠 Regras de Negócio Essenciais
✅ Rastreamento de Interação
Registra quando o cliente interage com a confirmação, fornecendo insights sobre o engajamento.
🔄 Atualização Automática
Atualiza o timestamp de última alteração (ultima_alteracao) automaticamente a cada interação.
📊 Auditoria
Mantém um histórico completo de interações para análise e auditoria de engajamento do cliente.
🔐 Segurança
Acesso restrito à empresa/unidade autenticada, garantindo a integridade dos dados da reserva.
📞 Suporte Técnico
Para solicitar seu partnerAppId, esclarecer dúvidas técnicas sobre implementação ou relatar problemas, entre em contato com a equipe técnica da ReserveGo. Nossa equipe está pronta para auxiliar na sua integração.
✅ Conclusão Técnica
1
Endpoint Dedicado
Foco na ação específica de interação
100%
Consistência
Garantia de dados precisos de engajamento
∞
Análise
Base sólida para insights do cliente
100%
Performance
Respostas rápidas para sua aplicação
Made with