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/apiTodas 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
Centssã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:
- Bearer Token (sessão) — Para aplicações frontend
- 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/guestsO 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/createPaginaçã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=20Resposta: 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-30Respostas 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ódigo | Significado |
|---|---|
| 200 | Sucesso |
| 201 | Recurso criado |
| 400 | Requisição inválida (validação falhou) |
| 401 | Não autenticado (token ausente/expirado) |
| 402 | Funcionalidade não contratada pelo tenant |
| 403 | Sem permissão (CASL negou acesso) |
| 404 | Recurso não encontrado |
| 409 | Conflito (ex: reserva duplicada) |
| 422 | Entidade não processável |
| 429 | Rate limit excedido |
| 500 | Erro 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ódulo | Descrição |
|---|---|
| Auth | Autenticação e sessões |
| Properties | Propriedades e configurações |
| Units | Unidades (quartos/camas) |
| Guests | Hóspedes e verificação |
| Reservations | Reservas e lifecycle |
| Financial | Plano de contas, lançamentos |
| Cash Management | Caixa, banco, PIX |
| Accounts Payable | Fornecedores e pagáveis |
| Accounts Receivable | Clientes e recebíveis |
| Inventory | Estoque, receitas, consumo |
| Payment | Gateways e processamento |
| Issues | Reclamações e suporte |
| OCP | Comunicação (email/WhatsApp) |
| Reports | Relatórios financeiros |
| Admin | Gestã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.