🔌 API Externa de Implantação

Implante, migre e mantenha uma clínica inteira no Rabi por sistema externo ou por agente de IA — com a mesma lógica e as mesmas validações das telas.

✅ Novo — set/2026 Em produção desde 23–24/09/2026 Correções do QA externo 100% em produção — 25/09/2026 ✅ Novo — 26/09/2026: Swagger com 269 operações ✅ Novo — 30/09/2026: token rbt_ da clínica é o caminho recomendado ✅ Novo — 13/10/2026: Swagger com 270 operações, PUT parcial e tokens rbt_ editáveis

1. O que é

A API Externa do Rabi Sistemas é uma API REST (OpenAPI 3.0, versão 1.0.0) para que sistemas externos e agentes de IA gerenciem os cadastros e a operação de uma clínica usando uma chave de API. Ela passa pelas mesmas regras de validação das telas: o que a tela recusa, a API também recusa — com um código de erro que diz o motivo.

Documentação interativa oficial (Swagger): https://api.rabisistemas.com.br/external-docs/. Esta área do manual é a versão comentada e em português-de-implantador desse Swagger: tudo o que está aqui foi extraído dele (193 caminhos, 270 operações, 25 grupos — Swagger atualizado em 13/10/2026; até 30/09 eram 192 caminhos e 269 operações) e organizado na ordem em que você vai usar.

1.1 Para que serve

UsoExemploOnde começar
Implantar uma clínica inteiraEmpresa, depósitos, locais, operadoras, taxas, produtos, serviços, colaboradores, convênios com todas as abas e tabelas de preço — sem digitar tela por tela.Implantação pela API
Migrar de outro sistemaPacientes em lote (com convênio/carteirinha e anexos), histórico de atendimentos e prontuário.Migração de histórico
Manter cadastrosReajuste de tabela de convênio, novos serviços, novos profissionais e seus logins, grades de horário.Referência — Cadastros
Integrar a operaçãoBuscar horário e agendar, orçamento, pré-faturamento, recebimento e glosa, movimentação financeira, estoque, NFS-e.Referência — Operação
Agente de IA implantadorUma IA lê a planilha da clínica e executa a implantação na ordem certa, conferindo pelo Farol.Roteiro para IA

1.2 Para quem é esta área

Implantadores e parceiros de implantação, desenvolvedores de sistemas que integram com o Rabi e agentes de IA que implantam ou migram clínicas. A linguagem é técnica, com exemplos em curl e JSON.

1.3 Novidades da API

✅ 13/10/2026 — Swagger atualizado (193 caminhos / 270 operações / 155 schemas, 7 alterados). ✅ Novo — 13/10/2026

✅ 30/09/2026 — token da clínica (rbt_) passa a ser o caminho recomendado. ✅ Novo — 30/09/2026

✅ 28/09/2026 (17:43) — correção geral de campos opcionais e de gravações erradas, em produção. ✅ Novo — 29/09/2026

⚠️ Conferência retroativa recomendada

Quem gravou pela API antes de 28/09/2026 às 17:43 (Brasília) deve conferir uma vez: pacientes enviados em lote (/pacientes/bulk podia responder criado sem gravar — confira por GET /pacientes); lote de preços da tabela interna (/tabelas-preco/produtos/bulk — valores gravados sem conversão); movimentações alteradas por PUT sem duplicatas (parcelas apagadas); fornecedores alterados por PUT sem ativo (reativados); UF de operadora, empresa e colaborador enviados sem UF (gravada a primeira UF); saídas e transferências de estoque sem lote (baixa em lote qualquer). Detalhes em Erros e boas práticas.

✅ 26/09/2026 — Swagger republicado (192 caminhos / 269 operações / 25 grupos / 155 schemas). ✅ Novo — 26/09/2026

✅ 25/09/2026 — rodadas 2 e 3 do QA externo em produção + Swagger atualizado. Tudo o que estava em homologação entrou em produção em 25/09/2026 (00:01): nenhuma rota ou correção da API externa ficou "só em homologação". (Os tokens rbt_ da #624, que em 26/09 estavam em homologação, entraram em produção em 28/09/2026 — ver 3.1.)

✅ 24/09/2026 — rodada 1 do QA externo em produção: GET /estoque paginado e filtrável por produto (produtoId) e depósito (localizacaoId); /estoque/lotes-produtos/{idProduto}/{idLocalizacao} respeita os parâmetros do caminho; GET /faturamento/divergencias não responde mais erro 500; envelope das listagens normalizado na maioria das rotas; GET /atendimentos/historico exige pacienteId; schemas de faturamento e parâmetros completados no Swagger.

Preços pela API — regra vigente: valorInternoConvenio sozinho não fecha pacote; para preço fechado envie pacote: true no serviço e zerarValor: true nos itens inclusos (abas do convênio). A coluna Valor do serviço com 4 linhas está ✅ em produção desde 24/09: somarItens aparece no Swagger (cadastro do serviço — leitura em GET /servicos/{id}; na escrita o campo se chama somarItems); efetivo.totalConvenio (o total Σ) existe na API do sistema (usada pela tela) — na API externa não aparece no Swagger. Para conferir o total pela API externa, use receita_total_servico da linha raiz (nivel = 0) em GET /convenios/{id}/farol/itens/{servicoRaizId}.

2. URLs base

AmbienteURL base (prefixe todas as rotas com ela)Quando usar
Produçãohttps://api.rabisistemas.com.br/api/v1/integrationsImplantação real da clínica.
Homologação (rotulado "Desenvolvimento" no Swagger)https://api.hmg.rabisistemas.dev/api/v1/integrationsEnsaiar o roteiro, testar o seu sistema/IA antes de tocar na produção.

Exemplo: a rota /empresas em produção é https://api.rabisistemas.com.br/api/v1/integrations/empresas.

3. Autenticação

Toda requisição exige o header:

Authorization: Bearer rbt_SEU_TOKEN

Recomendado (desde 30/09/2026): o token rbt_ gerado pela própria clínica (tipo "Implantação e manutenção", em produção desde 28/09/2026) — ver 3.1. Alternativa: a chave rbk_ emitida pelo time Rabi, no mesmo cabeçalho (Authorization: Bearer rbk_…) — continua valendo para quem já tem.

PontoComo funciona
Onde nasce a chaveRecomendado: token rbt_ gerado pela própria clínica em Configurações › Parâmetros › Integrações (tipo "Implantação e manutenção"; permissões e validade escolhidas na geração — 3.1). Alternativa: chave rbk_ gerada pelo time Rabi no portal comercial, por clínica (na geração são definidos a clínica, as permissões e a validade).
Clínica (tenant)Implícita: a chave só acessa os dados da clínica para a qual foi gerada. Não se informa tenant nas requisições.
PermissõesCada rota exige uma permissão específica (ex.: convenio:create). Sem ela → 403, com a permissão que falta em escopoFaltante e, em error, onde liberá-la. Veja a tabela completa.
ValidadeDepois de expirar — ou se for revogada — a chave passa a responder 401.
Monitorar a validadeToda resposta autenticada com sucesso traz o cabeçalho X-ApiKey-Expires-At (UTC, ISO 8601, ex.: 2026-12-31T23:59:59.000Z) com a expiração da chave usada — rbk_ ou rbt_ (o rbt_ passou a enviá-lo em 02/10/2026); chave sem validade não envia o cabeçalho. Monitore e renove antes dessa data, sem esperar o 401: rbt_ pela clínica (Integrações › Renovar); rbk_ pedindo à Rabi.
RenovaçãoToken rbt_ (recomendado; em produção desde 28/09/2026, issue #624): a própria clínica renova e revoga em Configurações › Parâmetros › Integrações — Renovar gera valor novo, invalida o anterior e permite revisar permissões e validade; as permissões também podem ser editadas sem trocar o token (3.1). Chave rbk_: não existe renovação automática nem autoatendimento — a chave nova é emitida pelo time Rabi, pelo mesmo canal usado para gerar a chave atual.
Exibição únicaO token completo aparece uma única vez, na criação (ou na renovação). Perdeu? Renove (rbt_) ou peça outra chave (rbk_).
RevogaçãoDepois de revogada, a chave rbk_ pode continuar aceita por até 60 segundos. O token rbt_ é conferido a cada chamada: a revogação vale na hora.
Chave rejeitada × falha de validaçãoQualquer chave rejeitada (ausente, errada, expirada, revogada) responde 401. 503 = falha real de rede/tempo ao validar a chave — tente de novo em instantes, com espera progressiva.

3.1 Tokens de integração da clínica (rbt_) — caminho recomendado ✅ em produção desde 28/09/2026 ✅ Novo — 30/09/2026: recomendado

🔑 Tokens gerados pela própria clínica — #624, com a habilitação da TalkMe (#597)

Em Configurações › Parâmetros › Integrações, a própria clínica gera, vê, renova e revoga tokens rbt_…: o valor aparece uma única vez (na geração ou na renovação); validade de 30, 90 ou 365 dias, ou sem validade; tudo auditado; limite de requisições (429 quando excedido). Dois tipos:

  • Implantação e manutenção — acesso à API externa /api/v1/integrations/*, só com as permissões escolhidas na geração (o mesmo catálogo da chave rbk_ — tabela). Vai no mesmo cabeçalho: Authorization: Bearer rbt_…. Sem a permissão da rota → 403 com escopoFaltante. ✅ Novo — 02/10/2026 Editar permissões (#653): no token de implantação ativo, a matriz vem pré-marcada; não salva vazia; o valor do token não muda e a alteração vale na chamada seguinte (token legado com acesso total mostra aviso; token revogado ou expirado → 409). Renovar abre o mesmo diálogo para revisar permissões e validade (sem alteração, o token novo herda as permissões) e invalida o valor anterior. O log registra quem alterou, quando e as permissões antes e depois.
  • TalkMe (IA) — acesso à API TalkMe da clínica. A clínica habilita a integração TalkMe na mesma tela (#597); sem habilitação, a TalkMe recebe 403 (não lê dados de outra clínica nem trocando cabeçalho). Um tipo não serve no lugar do outro (403). ✅ Novo — 30/09/2026 Correções no servidor da integração TalkMe (30/09): a IA passa a checar a duração do serviço ao marcar (antes podia sobrepor agendamentos); só oferece especialidades por convênio quando há grade que aceite o convênio; filtra os horários dos profissionais pelo serviço pedido; serviço inativo é recusado na consulta e no agendamento. O token TalkMe não tem "Editar permissões" (400) e renova como antes. ✅ Em produção desde 09/10/2026 — #633: consulta única de disponibilidade para a IA (profissional da especialidade, que faz o procedimento, com agenda liberada para o convênio — sem mostrar horários); a clínica deve manter em dia Atende convênio no profissional, serviços e convênios na grade, Utiliza/Atende no convênio e o convênio ativo na unidade (veja). ✅ Novo — 14/10/2026 — #664: a consulta da IA deixa de oferecer serviço que o Farol bloqueia ou que só libera com aprovação (vermelho, roxo e amarelo com aprovação de nível 2). 🟠 Roadmap #660: a IA abrir autorização e orçamento — hoje ela não abre.

rbt_ × rbk_ — decisão do Diretor (30/09/2026): o caminho recomendado para implantar e manter a clínica pela API (inclusive pelo kit de Implantação com IA) é o token rbt_ do tipo "Implantação e manutenção", que a própria clínica controla — gera, renova e revoga sem depender do time Rabi (a validade é a definida na geração e aparece no cabeçalho X-ApiKey-Expires-At; as permissões podem ser editadas depois; a revogação vale na hora). A chave rbk_ emitida pelo time Rabi no portal comercial continua valendo para quem já tem e é a alternativa (renovação pelo time Rabi; validade no cabeçalho X-ApiKey-Expires-At).

Como gerar o rbt_ de implantação: (1) Configurações › Parâmetros › Integrações › novo token do tipo "Implantação e manutenção"; (2) marque só as permissões da implantação (use o kit de permissões — deixe delete de fora até precisar); (3) escolha a validade (30, 90, 365 dias ou sem validade — prefira a que cobre a implantação); (4) copie o valor — ele aparece uma única vez — direto para o cofre de senhas ou a variável de ambiente/segredo do sistema que vai chamar a API; (5) faltou uma permissão no meio do caminho? O 403 diz qual em escopoFaltante — use Editar permissões no mesmo token (não precisa gerar outro); (6) terminou a implantação, revogue o token na mesma tela.

🔐 Cuidados com o token (valem para rbt_ e rbk_)
  • O token completo aparece uma única vez, na criação — guarde em local seguro (cofre de senhas ou variável de ambiente).
  • Nunca cole o token em documento, chamado, e-mail, manual ou conversa com IA que fique salva.
  • Token de uma clínica não acessa dados de outra.
  • Suspeita de vazamento? Revogue o token e gere outro.

Teste rápido do token (lista as empresas da clínica):

curl -s -D - https://api.rabisistemas.com.br/api/v1/integrations/empresas \
  -H "Authorization: Bearer rbt_SEU_TOKEN" | grep -i -e "^HTTP" -e "x-apikey-expires-at"

Resposta 200 = token válido e com empresa:read. O cabeçalho X-ApiKey-Expires-At mostra até quando a chave vale (rbk_ ou rbt_; chave sem validade não o envia). O token rbt_ é gerado no ambiente da clínica — use a URL do mesmo ambiente em que ele foi gerado. 401 = chave ausente, errada, expirada ou revogada. 403 = chave válida, mas sem essa permissão (veja escopoFaltante). 503 = falha de rede/tempo ao validar — tente de novo.

🔐 Cuidados com a chave e o token
  • Trate a chave como senha: guarde em cofre/variável de ambiente, nunca em código versionado, planilha compartilhada ou prompt salvo de IA.
  • Peça só as permissões que a tarefa precisa (ex.: uma chave de implantação não precisa de nfse:delete).
  • Terminou a implantação? Revogue: o token rbt_ em Configurações › Parâmetros › Integrações (vale na hora); a chave rbk_, pelo time Rabi no portal comercial (lembre dos até 60 s de tolerância).
  • Integração contínua? Registre o X-ApiKey-Expires-At e crie um alerta com antecedência (ex.: 15 dias): com rbt_, a clínica usa Renovar na tela de Integrações (o valor anterior deixa de valer — troque-o no sistema integrado); com rbk_, peça a chave nova ao time Rabi.
  • Valem também os do quadro da seção 3.1 (aparece uma vez; nunca colar em documento, chamado, e-mail, manual ou conversa com IA salva; token de uma clínica não acessa outra; vazamento → revogar e gerar outro).
  • Em vários exemplos deste manual o token aparece como rbk_SEU_TOKEN: com o rbt_ (recomendado) o uso é idêntico — troque pelo seu token.

4. Tabela completa de permissões

São 88 permissões, no formato recurso:ação (read, create, update, delete). Cada recurso tem o seu próprio catálogo, independente dos outros: empresa:* não dá acesso a convenio nem a local. A tabela abaixo foi montada rota a rota a partir do Swagger — clique numa rota para ver os detalhes.

Observações do Swagger: não existe fornecedor:delete (a exclusão interna de fornecedor é física, por isso não foi exposta); estoque só tem leitura e criação de movimentos; cancelar agendamento usa agendamento:delete; auxiliar é só leitura; financeiro:create/financeiro:update e orcamento:create podem disparar emissão automática de NFS-e.

PermissãoNºRotas liberadas
empresa:read2GET /empresas
GET /empresas/{id}
empresa:create1POST /empresas
empresa:update1PUT /empresas/{id}
empresa:delete1DELETE /empresas/{id}
deposito:read2GET /depositos
GET /depositos/{id}
deposito:create2POST /depositos
POST /depositos/bulk
deposito:update1PUT /depositos/{id}
deposito:delete1DELETE /depositos/{id}
local:read2GET /locais
GET /locais/{id}
local:create1POST /locais
local:update1PUT /locais/{id}
local:delete1DELETE /locais/{id}
auxiliar:read14GET /auxiliares/tipos-produto
GET /auxiliares/tipos-codigo
GET /auxiliares/tabelas-ans87
GET /auxiliares/regimes-atendimento
GET /auxiliares/tipos-servico
GET /auxiliares/tipos-guia
GET /auxiliares/tipos-taxa
GET /auxiliares/unidades-medida
GET /auxiliares/principios-ativos
GET /auxiliares/sexos
GET /auxiliares/estados-civis
GET /auxiliares/conselhos-profissionais
GET /auxiliares/unidades-federativas
GET /auxiliares/tipos-atendimento
operadora:read2GET /operadoras
GET /operadoras/{id}
operadora:create2POST /operadoras
POST /operadoras/bulk
operadora:update1PUT /operadoras/{id}
operadora:delete1DELETE /operadoras/{id}
fornecedor:read2GET /fornecedores
GET /fornecedores/{id}
fornecedor:create2POST /fornecedores
POST /fornecedores/bulk
fornecedor:update1PUT /fornecedores/{id}
fabricante:read2GET /fabricantes
GET /fabricantes/{id}
fabricante:create2POST /fabricantes
POST /fabricantes/bulk
fabricante:update1PUT /fabricantes/{id}
fabricante:delete1DELETE /fabricantes/{id}
taxa:read2GET /taxas
GET /taxas/{id}
taxa:create2POST /taxas
POST /taxas/bulk
taxa:update1PUT /taxas/{id}
taxa:delete1DELETE /taxas/{id}
produto:read2GET /produtos
GET /produtos/{id}
produto:create2POST /produtos
POST /produtos/bulk
produto:update1PUT /produtos/{id}
produto:delete1DELETE /produtos/{id}
equipamento:read2GET /equipamentos
GET /equipamentos/{id}
equipamento:create2POST /equipamentos
POST /equipamentos/bulk
equipamento:update1PUT /equipamentos/{id}
equipamento:delete1DELETE /equipamentos/{id}
servico:read2GET /servicos
GET /servicos/{id}
servico:create2POST /servicos
POST /servicos/bulk
servico:update1PUT /servicos/{id}
servico:delete1DELETE /servicos/{id}
colaborador:read2GET /colaboradores
GET /colaboradores/{id}
colaborador:create2POST /colaboradores
POST /colaboradores/bulk
colaborador:update2PUT /colaboradores/{id}
POST /colaboradores/{id}/usuario
colaborador:delete1DELETE /colaboradores/{id}
gradeColaborador:read3GET /grades-colaborador
GET /grades-colaborador/filter
GET /grades-colaborador/{id}
gradeColaborador:create1POST /grades-colaborador
gradeColaborador:update1PUT /grades-colaborador/{id}
gradeColaborador:delete2DELETE /grades-colaborador/{id}
DELETE /grades-colaborador/unique/{id}
gradeEquipamento:read2GET /grades-equipamento
GET /grades-equipamento/{id}
gradeEquipamento:create1POST /grades-equipamento
gradeEquipamento:update1PUT /grades-equipamento/{id}
gradeEquipamento:delete1DELETE /grades-equipamento/{id}
convenio:read12GET /convenios
GET /convenios/{id}/colaboradores
GET /convenios/{id}/taxas
GET /convenios/{id}/servicos
GET /convenios/{id}/produtos
GET /convenios/{id}/especialidades
GET /convenios/{id}/planos
GET /convenios/{id}/farol/produtos
GET /convenios/{id}/farol/servicos
GET /convenios/{id}/farol/itens
GET /convenios/{id}/farol/itens/{servicoRaizId}
GET /convenios/{id}
convenio:create2POST /convenios
POST /convenios/bulk
convenio:update7PUT /convenios/{id}/colaboradores
PUT /convenios/{id}/taxas
PUT /convenios/{id}/servicos
PUT /convenios/{id}/produtos
PUT /convenios/{id}/especialidades
PUT /convenios/{id}/planos
PUT /convenios/{id}
convenio:delete1DELETE /convenios/{id}
tabelaPreco:read4GET /tabelas-preco
GET /tabelas-preco/{id}
GET /tabelas-preco/precificacao
GET /tabelas-preco/produtos
tabelaPreco:create1POST /tabelas-preco
tabelaPreco:update3PUT /tabelas-preco/{id}
POST /tabelas-preco/produtos
POST /tabelas-preco/produtos/bulk
paciente:read4GET /pacientes
GET /pacientes/{id}
GET /pacientes/{id}/convenios
GET /pacientes/{id}/anexos
paciente:create2POST /pacientes
POST /pacientes/bulk
paciente:update4PUT /pacientes/{id}
POST /pacientes/{id}/convenios
PUT /pacientes/{id}/convenios/{vinculoId}
POST /pacientes/{id}/anexos
paciente:delete1DELETE /pacientes/{id}
agendamento:read6GET /agendamentos/datas/disponiveis
POST /agendamentos/horarios/disponiveis
GET /agendamentos/locais/disponiveis
GET /agendamentos/motivo-cancelamento
GET /agendamentos
GET /agendamentos/{id}
agendamento:create1POST /agendamentos
agendamento:delete1PATCH /agendamentos/{id}/cancelar
orcamento:read6GET /orcamentos
GET /orcamentos/status
GET /orcamentos/consideracoes
GET /orcamentos/{id}/{isAgendamento}
GET /orcamentos/anexo/listar/{orcamentoId}
GET /orcamentos/anexo/listar-necessarios/{pacienteId}
orcamento:create1POST /orcamentos
orcamento:update3PUT /orcamentos/{id}
PUT /orcamentos/status/{idOrcamento}/{idStatus}
POST /orcamentos/anexo/vincular/{anexoId}/{orcamentoId}
atendimento:read2GET /atendimentos/{id}
GET /atendimentos/historico
atendimento:create2POST /atendimentos
POST /atendimentos/novo-prontuario
atendimento:update2PUT /atendimentos/{id}
POST /atendimentos/prontuario
faturamento:read16GET /faturamento/guias
GET /faturamento/guias/buscar-por-numero-guia
GET /faturamento/guias/pacientes
GET /faturamento/guias/info-extras/{guiaMae}/{guiaFilha}
GET /faturamento/guias/valores-atualizados/{guiaMae}/{guiaFilha}
GET /faturamento/guias/conversoes-convenio/{guiaMae}/{guiaFilha}/{convenioId}
GET /faturamento/guias/{guiaMae}/filhas
GET /faturamento/guias/servico/{guiaFilha}
GET /faturamento/guias/valores-atendimento/{atendimentoId}
GET /faturamento/divergencias
GET /faturamento/recebimento
GET /faturamento/recebimento/opcoes
GET /faturamento/glosas
GET /faturamento/glosas/guia/{guiaMae}
GET /faturamento/glosas/status
GET /faturamento/glosas/motivos
faturamento:create1POST /faturamento/recebimento/registrar
faturamento:update7PUT /faturamento/guias/{servicoAtendimentoId}
PUT /faturamento/guias/{guiaMae}/confirmar
POST /faturamento/divergencias/{numeroGuiaMae}/faturar-diferenca
POST /faturamento/recebimento/devolver
PUT /faturamento/glosas/produto
PUT /faturamento/glosas/taxa
PUT /faturamento/glosas/servico
financeiro:read2GET /financeiro/movimentacoes
GET /financeiro/movimentacoes/{id}
financeiro:create2POST /financeiro/movimentacoes
POST /financeiro/movimentacoes/bulk
financeiro:update2PUT /financeiro/movimentacoes/{id}
POST /financeiro/pagamentos/confirmacao ✅ Novo — 13/10/2026
estoque:read9GET /estoque
GET /estoque/saldo-produtos
GET /estoque/{id}
GET /estoque/historico/{id}
GET /estoque/ultima-compra/{id}
GET /estoque/movimentacao/{id}
GET /estoque/buscar/{lote}/{produtoId}/{localizacaoId}
GET /estoque/lotes-produtos/{idProduto}/{idLocalizacao}
POST /estoque/previsao
estoque:create3POST /estoque/entrada
POST /estoque/saida
POST /estoque/transferencia
nfse:read14GET /nfse/emitentes
GET /nfse/emitentes/{id}
GET /nfse/perfis-fiscais
GET /nfse/perfis-fiscais/{id}
GET /nfse/tomadores
GET /nfse/tomadores/{id}
POST /nfse/tomadores/sincronizar-paciente/{pacienteId}
GET /nfse/notas
GET /nfse/notas/{id}
GET /nfse/notas/{id}/xml
GET /nfse/notas/{id}/links
GET /nfse/notas/{id}/danfse.html
GET /nfse/notas/{id}/danfse.pdf
GET /nfse/notas/{id}/tentativas
nfse:create8POST /nfse/tomadores
POST /nfse/tomadores/bulk
POST /nfse/notas
POST /nfse/notas/{id}/emitir
POST /nfse/notas/{id}/consultar-protocolo
POST /nfse/notas/{id}/emitir-contingencia
POST /nfse/notas/{id}/transmitir-contingencia
POST /nfse/notas/{id}/substituir
nfse:update3PUT /nfse/tomadores/{id}
POST /nfse/tomadores/{id}/completar
PUT /nfse/notas/{id}/tomador
nfse:delete3POST /nfse/notas/{id}/desistir
POST /nfse/notas/{id}/cancelar
POST /nfse/notas/{id}/analise-fiscal
parametro:read21GET /parametros/desconto
GET /parametros/desconto/colaboradores/{nivel}
GET /parametros/desconto/colaborador/{id}
GET /parametros/alcada-compra/colaborador/{id}
GET /parametros/financeiro
GET /parametros/orcamento
GET /parametros/estoque
GET /parametros/avisos
GET /parametros/avisos/{chave}
GET /parametros/acolhimento
GET /parametros/acolhimento/validar/{pacienteId}
GET /parametros/acolhimento/historico-confirmacoes/{pacienteId}
GET /parametros/servicos-online
GET /parametros/servicos-online/link
GET /parametros/servicos-online/agendamento/perguntas
GET /parametros/servicos-online/agendamento/perguntas/por-especialidade
GET /parametros/servicos-online/agendamento/perguntas/colaborador/{colaboradorId}
GET /parametros/termo
GET /parametros/dashboard-permissoes/graficos
GET /parametros/dashboard-permissoes/dashboards
GET /parametros/dashboard-atribuicao
parametro:create3POST /parametros/desconto/colaborador/{id}
POST /parametros/alcada-compra/colaborador/{id}
POST /parametros/servicos-online/agendamento/perguntas
parametro:update20PUT /parametros/desconto
PUT /parametros/financeiro
PUT /parametros/orcamento
PUT /parametros/estoque
PUT /parametros/avisos/{chave}
PUT /parametros/acolhimento
POST /parametros/acolhimento/atualizar-validacoes/{pacienteId}
PATCH /parametros/servicos-online/habilitar
PATCH /parametros/servicos-online/agendamento/habilitar
PATCH /parametros/servicos-online/agendamento/mudanca-colaborador/habilitar
PATCH /parametros/servicos-online/confirmacao/habilitar
PATCH /parametros/servicos-online/prontuario/habilitar
PATCH /parametros/servicos-online/lista-medico-convenio/habilitar
PATCH /parametros/servicos-online/textos-informativos
PUT /parametros/servicos-online/agendamento/perguntas/{id}
POST /parametros/servicos-online/agendamento/perguntas/{perguntaId}/colaborador/{colaboradorId}
PUT /parametros/termo
PUT /parametros/dashboard-permissoes/graficos
PUT /parametros/dashboard-permissoes/dashboards
PUT /parametros/dashboard-atribuicao
parametro:delete1DELETE /parametros/servicos-online/agendamento/perguntas/{id}
🧰 Kit de permissões para uma implantação completa (use ao gerar o rbt_ "Implantação e manutenção")

empresa:read/create/update, deposito:read/create, local:read/create, auxiliar:read, operadora:read/create/update, fornecedor:read/create, fabricante:read/create, taxa:read/create/update, produto:read/create/update, equipamento:read/create, servico:read/create/update, colaborador:read/create/update, gradeColaborador:read/create, gradeEquipamento:read/create, convenio:read/create/update, tabelaPreco:read/create/update, paciente:read/create/update — e, se for migrar histórico, atendimento:read/create/update. Opcionais (se a implantação também lançar saldo inicial de estoque, movimentações financeiras ou ajustar parâmetros pela API): estoque:read/create, financeiro:read/create, parametro:read/update. Deixe delete de fora até precisar.

5. Convenções

5.1 Listagens e paginação (envelope único)

curl -s "https://api.hmg.rabisistemas.dev/api/v1/integrations/servicos?ativo=true&page=1&pageSize=200&nome=consulta" \
  -H "Authorization: Bearer rbk_SEU_TOKEN"

5.2 Valores, datas e ids

5.3 Atualizações (PUT) — campo omitido mantém, null limpa, lista enviada substitui ✅ Atualizado — 13/10/2026

✅ Regra da API (desde 01–02/10/2026; Swagger de 13/10/2026): PUT parcial

Campo omitido mantém o valor atual; null limpa; lista omitida mantém; lista enviada substitui ([] apaga). Vale para /servicos, /orcamentos, /pacientes (e /pacientes/{id}/convenios/{vinculoId}), /colaboradores, /convenios, /grades-colaborador, /grades-equipamento, /financeiro/movimentacoes e /faturamento/guias/{servicoAtendimentoId}. A leitura (GET) devolve os nomes que o PUT aceita. Envie só o que muda; para trocar uma lista, mande a lista inteira já corrigida (parta do GET). Até 01/10/2026, gravar pela API sem todos os campos apagava dados não enviados (#634, corrigido) — a orientação antiga "envie sempre o objeto completo" deixou de valer nessas rotas.

Exemplos em PUT /servicos/{id}: { "nome": "X" } só renomeia; { "documentos": [{ "id": 3 }] } deixa só o documento 3; "valor": null vira 0; produto da composição enviado sem valorUnitario mantém o valor que já tinha (produto novo sem valor entra com 0). PUT cuja descrição no Swagger não diz nada sobre isso → trate como sobrescrita: faça o GET e reenvie o objeto completo.

RotaComportamento declarado no Swagger (13/10/2026)
PUT /servicos/{id}Parcial. Listas documentos, produtoIds, equipamentoIds, servicoTaxa, especialidadesId, servicosRelacionados: omitidas mantêm, enviadas substituem. perfilFiscalId: null desvincula.
PUT /convenios/{id}Parcial. empresaId, unidadesIds, operadoraId, datas, exigirToken e prazoLimiteEntregaGuias omitidos mantêm (null limpa/desvincula). unidadesIds enviado é a lista completa (unidades fora dela são desativadas no convênio); politicasPorTipoProduto enviado é a lista completa (as que faltarem são inativadas; omitido não mexe). Aceita os nomes da leitura limiteParcelasConvenios e kitDocumentosId. Na atualização o código ANS vai em codigoANS (na criação, registroANS).
PUT /pacientes/{id} · /pacientes/{id}/convenios/{vinculoId}Parcial. contato e convenioPlano omitidos mantêm; enviados substituem (contato/carteira com id que não veio é inativado). nomeSocial: null ou vazio limpa. No vínculo: convenioId, planoId, numeroDaCarterinha e validade omitidos mantêm.
PUT /colaboradores/{id}Parcial. Não reativa colaborador desativado. vinculoRepasse: produtos, servicos e taxas só são trocadas quando enviadas (com a linha geral — item vazio/null). Sucesso responde o número cru 201.
PUT /grades-colaborador/{id} · /grades-equipamento/{id}Parcial. Trocar modoConvenio (INCLUIR/EXCLUIR) inverte o sentido da lista de convênios; limitesConvenio só muda quando enviado. Na grade de colaborador, o corpo é um array com o id de cada horário.
PUT /orcamentos/{id}Parcial. procedimentos enviado substitui a lista sem perder histórico (serviço reconhecido por orcamentoServicoId mantém sessões e agendamentos). Orçamento aprovado não aceita mudar procedimentos/valores (registrar pagamento continua).
PUT /financeiro/movimentacoes/{id} · /faturamento/guias/{servicoAtendimentoId}Parcial. Movimentação: registroFinanceiro e duplicatas omitidos não mudam lançamentos e parcelas. Guia: produto/taxa com o próprio id muda só os campos enviados.
PUT /convenios/{id}/servicos · /taxas · /produtos · /colaboradores · /especialidades · /planosUpsert: campo omitido mantém. Em serviços, valorInternoConvenio null limpa; em taxas, valorConvertido null limpa; em produtos, valorUnitarioConversao/fatorK null limpam. As especialidades da aba Colaboradores são aditivas (nunca removem).
PUT /empresas/{id}Substitui o cadastro por completo — envie a empresa inteira.
PUT /operadoras/{id}Envie as listas completas de plano e contato: o servidor cria, atualiza ou remove para bater com o que foi enviado.
PUT /parametros/desconto · /parametros/financeiroDesconto: campo omitido não altera. Financeiro: os 3 campos numéricos omitidos ficam inalterados, mas omitir (ou mandar 0/""/false) em categoriaPagamentoId/centroDeCustoId grava null.
POST /atendimentos/prontuarioSobrescreve o texto do prontuário sem guardar a versão anterior.
PUT sem declaração (produtos, taxas, equipamentos, locais, depósitos, fornecedores, fabricantes, tabelas de preço, atendimento, tomador, demais parâmetros)A descrição não declara o comportamento → trate como sobrescrita: GET antes e objeto completo. (Na tabela de preço, os preços priceType1..3 são em reais e o omitido mantém.)

Onde o campo é aceito, null limpa e 0 é zero explícito (diferente de omitido e de null). Trava de versão: nas telas, desde 02/10/2026, quem grava sobre um registro alterado por outra pessoa recebe "Este registro foi alterado por outra pessoa. Recarregue a tela antes de alterar." (#640); na API a versão é opcional — sem enviá-la, a gravação não confere se outra pessoa alterou antes. Prefira ler (GET) logo antes de gravar.

5.4 DELETE = desativação lógica

DELETE inativa (ativo = false), não apaga. Particularidades:

RecursoO que acontece
OperadoraRecusa (400) se houver convênio ativo vinculado.
EmpresaRecusa (400) se tiver atendimentos, colaboradores, convênios, depósitos, locais ou movimentações financeiras ativas vinculadas.
LocalRecusa (409) se houver agendamentos, orçamentos, grades ou vínculos de serviço no local.
ColaboradorDesativa também grades, especialidades e vínculos de empresa; avisa (não bloqueia) se houver agendamento futuro.
ConvênioSe estiver em agendamentos ativos, a resposta traz um aviso.
ProdutoDesativa também os fornecedores vinculados ao produto (e remove a configuração de estoque dele). ✅ Desde 02/10/2026 (#626) Recusa com 409 se o produto estiver na composição de algum serviço ativo — a resposta traz a lista em servicos; o mesmo vale para PUT /produtos/{id} com ativo: false. Serviço inativo não bloqueia. Para liberar: substitua ou retire o produto nos serviços (PUT /servicos/{id} com a lista produtoIds corrigida) e tente de novo.
TaxaDesativação lógica (a taxa usa delete: true, não ativo). ✅ Desde 02/10/2026 (#626) Recusa com 409 (lista em servicos) se a taxa estiver na composição de serviço ativo; taxa inexistente → 404. Corrija com PUT /servicos/{id} (lista servicoTaxa corrigida).
Grades (colaborador/equipamento)Rotas de "excluir": a série a partir do horário (DELETE /grades-colaborador/{id}) ou só aquele horário (DELETE /grades-colaborador/unique/{id}).
Pergunta do agendamento onlineExclusão lógica (deleted = true).
Sem rota de exclusãoFornecedor, anexo de paciente, prontuário, movimentação financeira.

5.5 Lotes (/bulk) e abas do convênio

RotaMáx. por requisiçãoChave do corpo
POST /convenios/bulk, /pacientes/bulk, /operadoras/bulk, /servicos/bulk, /colaboradores/bulk, /produtos/bulk, /equipamentos/bulk, /taxas/bulk, /fornecedores/bulk, /fabricantes/bulk, /depositos/bulk, /financeiro/movimentacoes/bulk50o plural do recurso (convenios, pacientes…; financeiro: movimentacoes + responsavelId único)
POST /nfse/tomadores/bulk100tomadores
POST /tabelas-preco/produtos/bulk200precos
PUT /convenios/{id}/colaboradores100colaboradores
PUT /convenios/{id}/taxas|servicos|produtos|especialidades|planos200taxas, servicos, produtos, especialidades, planos

5.6 Códigos de resposta e o que fazer

CódigoSignificadoO que fazer
200 / 201 / 202Sucesso (201 = criado; alguns PUT respondem 202)Guarde o id devolvido — ele é a entrada do próximo passo.
207Lote com falha parcialLeia resultados; reenvie só ERRO/NAO_PROCESSADO.
400Requisição inválida (id inválido, lote vazio/grande demais, CPF inválido, dado inconsistente) — ou, em DELETE de empresa/operadora, vínculos ativosCorrija o corpo/parâmetro; leia a mensagem em error.
401Chave rejeitada — ausente, inválida, revogada ou expirada (qualquer rejeição da chave cai aqui)Confira o header Authorization: Bearer rbt_… (ou rbk_…); rbt_ expirado/revogado → a clínica gera ou renova na tela de Integrações; rbk_ expirada/revogada → peça chave nova ao time Rabi. Evite chegar aqui: monitore X-ApiKey-Expires-At. Desde 28/09/2026, erro de negócio que menciona "token" (ex.: token obrigatório do convênio) não vira mais 401.
403A chave não tem a permissão da rota (ou o token rbt_ é do tipo errado para esta API). A resposta traz a permissão que falta em escopoFaltante e, em error, onde liberá-laToken rbt_ de "Implantação e manutenção": Editar permissões na tela de Integrações e marque a que falta — o token não muda e vale na chamada seguinte. Chave rbk_: peça ao time Rabi uma que a inclua.
404Registro não encontrado nesta clínica — ou rota inexistente (desde 26/09/2026; antes a rota errada respondia 401 "jwt malformed")Confira o id (e se não é de outra clínica/ambiente — homologação e produção têm ids diferentes). Confira também o caminho e o método da rota no Swagger.
409Conflito: duplicidade (CNPJ, CPF, nome de local/depósito/equipamento), conflito de horário de grade, local com vínculos, login já existente; produto/taxa na composição de serviço ativo (desde 02/10/2026, lista em servicos); confirmação de pagamento de parcela já paga por outro pagamento ou com valor menorDuplicidade: busque o registro existente (GET) e reutilize o id. Composição: corrija os serviços listados e tente de novo.
422Referência inválida — um id apontado não existe ou está inativo (ex.: POST /locais com depósito inativo; convênio com empresa/operadora inexistente; orçamento bloqueado pelo Farol)Crie/ative o pré-requisito antes — quase sempre é ordem de implantação. Veja o roteiro.
429Lote/atualização já em andamentoAguarde o anterior terminar; não dispare lotes em paralelo do mesmo recurso.
503Falha real de rede/tempo ao validar a chave (não é chave errada — essa responde 401)Tente de novo com espera progressiva (ex.: 2 s, 4 s, 8 s). Se persistir, avise o time Rabi.

O corpo de erro segue o formato { "error": "mensagem" }. Em sucesso autenticado, confira também o cabeçalho X-ApiKey-Expires-At.

6. O que a API não cobre (Swagger oficial)

7. Mapa dos 25 grupos

Contagem pelo Swagger publicado em 13/10/2026: 193 caminhos (endpoints distintos) e 270 operações (até 30/09: 192 e 269 — entrou POST /financeiro/pagamentos/confirmacao) (método + caminho — ex.: GET e PUT em /convenios/{id} contam como 2 operações do mesmo caminho). Os grupos 1 a 20 estão na ordem do roteiro de implantação (tabela de preço interna antes dos convênios; grades de horário depois dos convênios; parâmetros no fim); os grupos 21 a 25 são de operação do dia a dia e de migração de histórico.

#GrupoO que cobreOperaçõesCaminhosReferência
1EmpresasEmpresas e unidades da clínica52Referência — Cadastros
2DepósitosDepósitos de estoque da clínica63Referência — Cadastros
3LocaisLocais de atendimento dentro de uma empresa/unidade52Referência — Cadastros
4AuxiliaresCadastros de domínio usados como ID em outras rotas — só leitura1414Referência — Cadastros
5OperadorasOperadoras de convênio63Referência — Cadastros
6FornecedoresFornecedores da clínica53Referência — Cadastros
7FabricantesFabricantes de produtos63Referência — Cadastros
8TaxasTaxas cobradas pela clínica63Referência — Cadastros
9ProdutosProdutos/materiais da clínica63Referência — Cadastros
10EquipamentosEquipamentos da clínica63Referência — Cadastros
11ServiçosServiços oferecidos pela clínica63Referência — Cadastros
12ColaboradoresProfissionais/equipe da clínica74Referência — Cadastros
13Tabelas de PreçoTabela de preço interna e preço de produto dentro dela85Referência — Cadastros
14ConvêniosCadastro de convênios da clínica2213Referência — Cadastros
15Grade de ColaboradorGrade de horários/agenda do colaborador74Referência — Cadastros
16Grade de EquipamentoGrade de horários/agenda do equipamento52Referência — Cadastros
17FinanceiroMovimentações financeiras e confirmação de pagamento (Pix/link)64Referência — Operação
18EstoqueMovimentação de estoque de produtos (entrada, saída, transferência)1212Referência — Operação
19PacientesCadastro de pacientes da clínica116Referência — Cadastros
20ParâmetrosRegras de negócio e controle de acesso do tenant4531Referência — Parâmetros
21AgendamentosNúcleo de agenda: buscar horário, criar, cancelar, listar87Referência — Operação
22OrçamentosEstimativa de custo pré-atendimento109Referência — Operação
23AtendimentosAtendimento e prontuário — voltado a migração de histórico65Referência — Operação
24FaturamentoPré-faturamento (guia de convênio/TISS), divergência, recebimento e glosa2424Referência — Operação
25NFS-eEmissão de nota fiscal de serviço e cadastro de tomadores2825Referência — Operação
Total25 grupos270193

8. Próximos passos

🚀
Implantação pela API
A ordem correta, passo a passo, com curl, campos obrigatórios e conferência pelo Farol.
📚
Referência completa
Todas as rotas: cadastros, operação e parâmetros — com parâmetros, corpo e respostas.
🩺
Erros e boas práticas
O que fazer em cada erro, como reprocessar lote 207, armadilhas conhecidas.
💲
Preços por convênio
As regras que a API aplica ao gravar as abas do convênio (Utiliza, Zerar, Pacote, 3 níveis).