Skip to Content
API ReferenceVisão Geral

API Reference — Visão Geral

Introdução

A API do Opero Global é uma API REST que permite integrar sistemas externos com as funcionalidades da plataforma. Com ela você pode:

  • Criar e gerenciar reservas programaticamente
  • Consultar disponibilidade em tempo real
  • Automatizar processos financeiros
  • Integrar com channel managers e OTAs
  • Construir interfaces customizadas

Base URL

Produção: https://api.opero.global/api

Todas as URLs de endpoint são relativas à base URL acima.

Formato

  • Request: JSON (Content-Type: application/json)
  • Response: JSON
  • Encoding: UTF-8
  • Datas: ISO 8601 (2026-05-25T14:30:00Z)
  • Valores monetários: Campos terminados em Cents são inteiros em centavos (ex: R$ 199,90 = 19990); alguns recursos também trazem o valor decimal
  • IDs: UUID

Autenticação

Todas as requisições (exceto endpoints públicos) requerem autenticação via:

  1. Bearer Token (sessão) — Para aplicações frontend
  2. API Key — Para integrações servidor-a-servidor
Authorization: Bearer <token-da-sessao>

ou

X-API-Key: opk_abc123def456...

Detalhes completos em Autenticação.

Multi-tenancy

Quase todos os endpoints são organizados sob um tenant:

/api/tenants/:tenantId/reservations /api/tenants/:tenantId/financial/chart-of-accounts /api/tenants/:tenantId/guests

O tenantId identifica sua organização e precisa ser o mesmo tenant do usuário (ou da API Key) autenticado. Você só pode acessar dados do seu próprio tenant; um tenantId diferente retorna 403.

Endpoints públicos

Alguns endpoints não requerem autenticação (usados pelo portal de reservas):

GET /api/public/property/:propertyId/config GET /api/public/property/:propertyId/rooms GET /api/public/property/:propertyId/availability POST /api/public/reservations/hold POST /api/public/payments/create

Paginação

Não há um formato de paginação único. Alguns endpoints de listagem aceitam page e limit — por exemplo, reservas (padrão page=1, limit=20):

GET /api/tenants/:tenantId/reservations?page=1&limit=20

Resposta: a maioria das listagens retorna um array JSON simples, sem envelope data/meta e sem total de registros.

Filtros

Muitos endpoints suportam filtros via query params:

GET /api/tenants/:tenantId/reservations?status=CONFIRMED&startDate=2026-06-01&endDate=2026-06-30

Respostas de erro

Erros seguem um formato consistente, com statusCode, message e timestamp. Erros de validação trazem a lista errors:

{ "statusCode": 400, "message": "Validation failed", "errors": [ { "path": "checkIn", "message": "Check-in date must be in the future" } ], "timestamp": "2026-05-25T14:30:00.000Z" }

Códigos HTTP comuns

CódigoSignificado
200Sucesso
201Recurso criado
400Requisição inválida (validação falhou)
401Não autenticado (token ausente/expirado)
402Funcionalidade não contratada pelo tenant
403Sem permissão (CASL negou acesso)
404Recurso não encontrado
409Conflito (ex: reserva duplicada)
422Entidade não processável
429Rate limit excedido
500Erro interno do servidor

Rate Limiting

Não há limite global de requisições na API REST, nem por API Key nem por sessão, e as respostas não trazem headers X-RateLimit-*.

Os endpoints de autenticação em /api/auth/* (em produção) têm limite por IP: 100 requisições a cada 10 segundos e 3 tentativas a cada 10 segundos em login, cadastro e troca de senha ou email. Ao exceder, a resposta é 429 com o header X-Retry-After (segundos).

Módulos da API

MóduloDescrição
AuthAutenticação e sessões
PropertiesPropriedades e configurações
UnitsUnidades (quartos/camas)
GuestsHóspedes e verificação
ReservationsReservas e lifecycle
FinancialPlano de contas, lançamentos
Cash ManagementCaixa, banco, PIX
Accounts PayableFornecedores e pagáveis
Accounts ReceivableClientes e recebíveis
InventoryEstoque, receitas, consumo
PaymentGateways e processamento
IssuesReclamações e suporte
OCPComunicação (email/WhatsApp)
ReportsRelatórios financeiros
AdminGestão de tenants (superuser)

Playground interativo

Acesse o Playground para testar endpoints diretamente no navegador pelo Swagger UI, com documentação inline e exemplos em cURL.

Last updated on