O inventário exato de endpoints, tipos de evento e escopos é compartilhado com integradores contra o runtime que eles vão chamar — ele cresce com o produto, então não congelamos um número aqui.
REST versionada em /api/public/pms/v1
A especificação é gerada das rotas que o runtime realmente serve, e um gate de paridade derruba o build quando rota e documentação discordam.
- OpenAPI
- Publicada pelo próprio runtime, não mantida à mão em paralelo.
- Versionamento
- A versão faz parte do caminho. Mudança que quebra cria versão nova; a anterior continua respondendo.
- Recursos
- Propriedades, reservas, hóspedes, fólios, pagamentos, POS, governança, manutenção, dado financeiro e imposto.
- Formatos
- JSON na entrada e na saída. Valores são inteiros em unidades menores, com a moeda declarada.
OAuth 2.0 client credentials
A credencial é emitida dentro do produto, por quem já enxerga o dado que ela vai ler. Não existe cadastro self-service público.
- Grant
- client_credentials. O token é opaco e expira em uma hora.
- Segredo
- Mostrado uma vez, guardado como hash e irrecuperável por desenho.
- Rotação
- Gere um segredo novo e o anterior segue válido por 24 horas, para o parceiro trocar sem downtime.
- Revogação
- Suspenda ou revogue a credencial e todo token emitido a partir dela para de funcionar.
Duas perguntas, dois mecanismos
“Este client pode ler reserva?” é escopo. “Pode ler reserva DESTE hotel?” é concessão. Confundir as duas é como um parceiro acaba enxergando a rede inteira.
- Escopos
- Por recurso e por operação, separados entre leitura e escrita. Escopo desconhecido é negado, nunca ignorado.
- Concessão por propriedade
- Explícita por hotel. Nenhuma concessão significa nenhum hotel — nunca “todos”.
- Tenant
- Vem do token. Não existe parâmetro de tenant na API para alguém errar.
- Negativas
- Motivos estáveis e distinguíveis: escopo negado, propriedade negada, propriedade obrigatória.
Leitura incremental que não perde linha
Um cursor só de timestamp quebra no instante em que dois fatos dividem o mesmo milissegundo. O nosso carrega também o identificador, então o corte dentro de um mesmo instante continua exato.
- updatedSince
- Peça o que mudou desde a sua última leitura bem-sucedida.
- Cursor composto
- Ordenado por instante e identificador, então o corte dentro de um instante não perde nem duplica nada.
- Cursor ilegível
- Responde erro, nunca recomeça em silêncio pela primeira página.
- Erros estáveis
- Cursor, timestamp, data operacional e identificador inválidos têm cada um o seu código público. Erro de banco nunca atravessa a fronteira.
Entrega assinada, com os estados de falha visíveis
Fatos operacionais são empurrados conforme acontecem. O que importa do lado de quem recebe não é o caminho feliz — é saber exatamente o que foi entregue e do que o sistema desistiu.
- Assinatura
- HMAC-SHA256 sobre o timestamp e o corpo cru, enviado como t=<unix>,v1=<hmac>, com tolerância de 300 segundos. O material exato está na especificação.
- Proteção contra reenvio
- Uma assinatura capturada em trânsito não pode ser reenviada depois como se fosse nova.
- Reentrega
- Reentrega automática com backoff, reentrega manual sob demanda e um estado de desistência que você enxerga.
- Segurança do destino
- O alvo é validado a cada tentativa, inclusive depois da resolução de DNS, para o endpoint não ser apontado à infraestrutura interna.
- Log de entrega
- Cada tentativa, código de resposta e desfecho, por endpoint.
Repita com segurança, e saiba a sua cota
Integração que não pode repetir é integração que duplica. As escritas são idempotentes e a cota é compartilhada entre réplicas.
- Idempotência
- Envie uma chave na escrita e a repetição devolve o resultado original. A mesma chave com corpo diferente é recusada, não aceita em silêncio.
- Rate limit
- Por credencial, contado em armazenamento compartilhado para as réplicas não concederem a cota inteira cada uma. Os cabeçalhos trazem limite, restante e reset.
- Modo degradado
- Se a contagem compartilhada cair, o limite degrada para um local mais fraco — e a resposta diz isso em um cabeçalho, em vez de fingir.
- Erros
- Um código público estável e uma mensagem humana. Sem identificador interno, sem stack trace.
O que a API se recusa a fazer
Algumas garantias se expressam melhor como recusas — não dá para desconfigurá-las.
- Sem dado de cartão
- Número de cartão e código de segurança são recusados na fronteira. A API nunca vira um lugar onde eles poderiam ser guardados.
- Sem leitura cruzada
- Requisição fora das propriedades concedidas é negada com motivo próprio, não filtrada para uma lista vazia.
- Sem vazar interno
- Erros de banco e de infraestrutura são traduzidos antes de chegar ao cliente.
- Trilha de auditoria
- Ciclo de vida da credencial e atividade da API são registrados contra uma taxonomia validada.
Como começar
Quatro passos, todos dentro do produto. Nada aqui é self-service no site público.
- Crie uma credencialNo PMS, em Integrações e API. O segredo aparece uma vez só.
- Conceda escopos e propriedadesSó os recursos e os hotéis de que essa integração precisa.
- Obtenha um tokenTroque a credencial por um token de acesso de uma hora.
- Leia a especificaçãoO documento OpenAPI descreve cada endpoint, payload e erro que você pode receber.
Limites honestos
- Não há portal público de desenvolvedor nem cadastro de sandbox — a credencial é emitida dentro do produto.
- A entrega de evento é webhook HTTP; não existe stream por WebSocket.
- Não há marketplace de conectores de parceiros para baixar nem conectores certificados.
- A maturidade atual mira piloto controlado, não implantação global.
Construindo uma integração?
Conte o que precisa ler ou escrever. A gente compartilha a especificação e o escopo de credencial que serve.