🔌 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
| Uso | Exemplo | Onde começar |
|---|---|---|
| Implantar uma clínica inteira | Empresa, 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 sistema | Pacientes em lote (com convênio/carteirinha e anexos), histórico de atendimentos e prontuário. | Migração de histórico |
| Manter cadastros | Reajuste de tabela de convênio, novos serviços, novos profissionais e seus logins, grades de horário. | Referência — Cadastros |
| Integrar a operação | Buscar horário e agendar, orçamento, pré-faturamento, recebimento e glosa, movimentação financeira, estoque, NFS-e. | Referência — Operação |
| Agente de IA implantador | Uma 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
- PUT parcial passa a ser a regra (correção do #634, em produção desde 01–02/10/2026): campo omitido mantém o valor atual;
nulllimpa; 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/movimentacoese/faturamento/guias/{servicoAtendimentoId}. A leitura (GET) devolve os nomes que oPUTaceita. Acabou a orientação "envie sempre o objeto completo" nessas rotas e o risco de "gravar pela API apaga o que não foi enviado" (ex.: o documento obrigatório PRESCRIÇÃO MÉDICA do serviço) — ver 5.3. - Serviço: novos campos
documentos(documentos obrigatórios — exigidos no agendamento, no acolhimento, na autorização e pela IA) eperfilFiscalId(perfil fiscal da NFS-e;nulldesvincula). Produto da composição enviado semvalorUnitariomantém o valor que já tinha; produto novo sem valor entra com 0. - 403 traz
escopoFaltante— a permissão que falta — e, emerror, onde liberá-la (ex.: "Serviços > Excluir"). - Tokens
rbt_(#653): as permissões escolhidas na geração são editáveis depois, sem trocar o token (a alteração vale na requisição seguinte); Renovar revisa permissões e validade (30, 90, 365 dias ou sem validade), gera valor novo e invalida o anterior; orbt_também envia o cabeçalhoX-ApiKey-Expires-At(3.1). - Paciente: novo campo
nomeSocial(opcional; exibido nas telas como "SOCIAL (civil)" e enviado no campo Nome Social da guia/XML TISS;nullou vazio limpa) — nome social em produção desde 05/10/2026. - Produto (#635):
codigoEANcomo texto com 8, 12, 13 ou 14 dígitos (preserva zero à esquerda — número ainda é aceito, mas perde os zeros);codigoNCMtexto com exatamente 8 dígitos;codigoProdutoaté 10 caracteres (letras, números, ponto, hífen ou barra — padrão TISS). - Tabela de preço interna (#652):
priceType1..3em reais (ex.:19547.56= R$ 19.547,56) na rota unitária e no lote; omitido mantém,nulllimpa. Lotes carregados antes de 28/09/2026 precisam ser conferidos. - Repasse do colaborador (#643): em
vinculoRepasse, item comservico/produto/taxavazio ounullé a linha geral do tipo (vale para todo item sem linha própria); no máximo uma geral por tipo (400se vierem duas); a linha específica substitui a geral; específica com 0 e 0% = sem repasse naquele item; tipo sem nenhuma linha = sem repasse. - Produto/taxa em uso (#626, desde 02/10):
DELETE /produtos/{id},PUT /produtos/{id}comativo: falseeDELETE /taxas/{id}respondem 409, com a lista emservicos, se o item estiver na composição de serviço ativo (5.4). - Nova rota POST
/financeiro/pagamentos/confirmacao(financeiro:update): para o provedor de pagamento avisar que a cobrança (Pix ou link) foi paga — identifica a parcela porduplicataIdouidentificadorCobranca; corpovalor(reais),identificadorPagamento,meio(PIX/LINK) e, opcional,dataPagamento.201parcela paga;200já confirmado (jaConfirmado: true, idempotente);404parcela não encontrada;409paga por outro pagamento ou valor menor que o da parcela. ✅ Atualização 15/10: Links de Pagamento Pix (#409) em produção desde 13/10: com um provedor Pix ativo na clínica (Configurações › Parâmetros › Pagamentos (links)), o próprio Rabi gera o link e dá a baixa sozinho — ver Financeiro › Links de Pagamento. Esta rota segue disponível para um sistema externo confirmar pagamento recebido por outro meio. - Orçamento: 🟡 Chegando quando o status automático for ligado (#656 — o motor está desligado em produção), os status automáticos (8 Vencido, 10 Pago, 11 Agendado, 12 Concluído, 13 Renegociado) passam a ser recusados (
422) emPUT /orcamentos/status/…. Hoje o sistema já mostra os novos nomes, mas a troca automática de status ainda não está ativa — confira pagamento e sessões abrindo o orçamento.
✅ 30/09/2026 — token da clínica (rbt_) passa a ser o caminho recomendado. ✅ Novo — 30/09/2026
- Decisão do Diretor (30/09): para implantar e manter uma clínica pela API — inclusive pelo kit de Implantação com IA — use o token
rbt_da própria clínica, do tipo "Implantação e manutenção", gerado em Configurações › Parâmetros › Integrações só com as permissões da implantação. A chaverbk_emitida pelo time Rabi continua valendo para quem já tem — é a alternativa (3.1). - Swagger sem mudança desde 28/09/2026 (269 operações / 192 caminhos).
- Telas de convênio em modo consulta (#632, em produção desde 29/09): na tela, alterar um convênio exige clicar em Liberar para edição; a API não muda —
PUT /convenios/{id}/…grava normalmente (5.5).
✅ 28/09/2026 (17:43) — correção geral de campos opcionais e de gravações erradas, em produção. ✅ Novo — 29/09/2026
- Campo opcional omitido não derruba mais a rota (antes:
500ou400genérico) em praticamente todos os cadastros e operações: serviço (especialidadesIde listas), produto, taxa, equipamento, colaborador (e login), grades, convênio, empresa, local, depósito, operadora (codigoCNESno lote), parâmetros (acolhimento, habilitar), paciente (endereço, convênios, responsável legal), agendamento, orçamento, atendimento, pré-faturamento, fornecedor e fabricante. Caso real:POST /servicossemespecialidadesIdrespondia500 … (reading 'filter'). - Serviço — contrato novo: as taxas do serviço vão em
servicoTaxa: [{ taxaId, quantidade }]— saíramtaxaServicoIdevalorTaxaServico.produtoIds,equipamentoIdseservicosRelacionadosaceitam ID puro ou objeto ({ id, quantidade, valorUnitario }·{ id }·{ servicoId, quantidade }). Exemplo no Passo 8 da implantação. - Estoque — contrato novo:
POST /estoque/saidaePOST /estoque/transferenciaexigemlote— envienullpara produto sem lote (antes, sem lote, o Rabi usava um lote qualquer). - Rotas que falhavam mesmo com o corpo completo — corrigidas:
POST /pacientes/bulk(respondia criado sem gravar) ePOST /colaboradores/bulk;/grades-equipamento(500 depois de gravar);/tabelas-preco/produtos(respondia sem esperar a gravação, e o lote de preços gravava sem converter para centavos);POST /orcamentosdevolviadata: null; erro de negócio com a palavra "token" (ex.: token obrigatório do convênio) virava401— agora só falha real de autenticação responde 401; emissão de NFS-e do lote de movimentações. - Gravações erradas sem aviso — corrigidas:
PUTde movimentação sem duplicatas apagava todas as parcelas (o PUT externo passou a ter as mesmas validações do interno);PUTde fornecedor semativoreativava o fornecedor; UF ausente gravava a primeira UF (operadora, empresa, colaborador); saída/transferência de estoque sem lote usava um lote qualquer; agendamento sem contatos mexia nos contatos do paciente; glosa semmotivoGlosadoligava um motivo arbitrário; grade de colaborador ficava órfã quando a associação falhava. - Swagger de 28/09/2026: mesmas 269 operações / 192 caminhos; mudaram 3 schemas (
ServicoCreate,EstoqueSaidaCreate,EstoqueTransferenciaCreate). As páginas de referência já refletem o contrato novo. - ✅ em produção desde 28/09/2026 Tokens de integração gerados pela própria clínica (
rbt_, #624) e habilitação da TalkMe (#597) — ver 3.1. A chaverbk_do time Rabi continua valendo.
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
- Nova operação GET
/convenios/{id}/farol/itens/{servicoRaizId}(permissãoconvenio:read): a árvore de um serviço raiz no convênio, sem paginação (resposta{ dados: [...] }, tipicamente poucas dezenas de linhas), comfarol_servico,margem_servico_pcte os totais já calculados por subárvore (cadaSUBSERVICOtraz o total da própria subárvore). Preferível a/farol/itensquando você já sabe o serviço.404= convênio não encontrado ou serviço raiz não encontrado/não utilizado neste convênio. É a mesma árvore do painel Expandir serviço da tela (concluído em 25/09, #625). /farol/itens,/farol/servicose/farol/produtosagora documentados por completo. Cada linha de itens traz, entre outros,conta_no_total,motivo_exclusao,margem_servico_pct,farol_servico,receita_total_servicoe os valores em reais — lista completa em Como ler cada linha de farol/itens. Correção: diferente do que este manual dizia até 25/09, a API externa traz sim margem, "conta no total" e o motivo da exclusão.- Leitura segura para o PUT:
GET /servicos/{id}agora devolveespecialidadesIdeservicosRelacionados(composição);GET /convenios/{id}devolveunidadesIdsepoliticasPorTipoProduto(+ prazos, datas eexigirToken) — com os mesmos nomes que oPUTespera. Antes, regravar um serviço/convênio sem essas listas apagava composição, especialidades, unidades e políticas. Receita: GET → altere → PUT com o objeto completo (5.3). ✅ Atualização 13/10/2026: desde 01–02/10 o PUT parcial é a regra nessas rotas — envie só o que muda. - Rota inexistente responde 404 (antes caía em
401 "jwt malformed", parecendo problema de chave). Chave rejeitada continua 401; 503 só para falha real de validação/rede. - ⚠️ Excluir produto/taxa:
DELETE /produtos/{id}eDELETE /taxas/{id}hoje não verificam se o item está na composição de algum serviço — ele some da composição sem aviso e o serviço passa a ser faturado sem aquela receita. Após a #626 (roadmap, Sprint 12), responderão 409 com a lista de serviços (5.4). ✅ Atualização 13/10/2026: o bloqueio (409) está em produção desde 02/10. - Tokens de integração da clínica (#624) e habilitação da TalkMe (#597) — anunciados aqui em 26/09 como "em homologação"; ✅ em produção desde 28/09/2026 (3.1).
✅ 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.)
GET /agendamentosexigedata(um dia por consulta) e pagina de verdade; filtrospacienteId,profissionalId,statusId,page,pageSize(máx. 200).- As 4 listagens que estavam fora do padrão —
/tabelas-preco,/orcamentos,/financeiro/movimentacoes,/estoque/saldo-produtos— agora usam o envelope{ dados, page, pageSize, total, totalPages }. Toda rota de listagem da API usa esse envelope (5.1 — com as poucas leituras de "array direto" sinalizadas na própria rota). GET /grades-colaboradoreGET /grades-equipamentopaginados de verdade, com filtroscolaboradorId/equipamentoId,localIdevigenteEm.GET /orcamentoscom filtrosid,pacienteId,pacienteCpf,pacienteNome,statusId,createdAtDe,createdAtAtee paginação real.GET /convenios/{id}/farol/itenscom filtroservicoAtivo(serviço raiz ativo/inativo no cadastro).- Toda resposta autenticada com sucesso traz o cabeçalho
X-ApiKey-Expires-At(validade da chave, ISO 8601) — ver 3. Autenticação. - Qualquer chave rejeitada responde 401; o 503 ficou só para falha real de rede/tempo ao validar a chave.
- Swagger atualizado: as mesmas 268 operações / 191 caminhos, agora com 155 schemas de resposta e 65 operações com descrição/parâmetros novos. As convenções oficiais foram reescritas — veja 5. Convenções (envelope, valores monetários,
PUT).
✅ 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
| Ambiente | URL base (prefixe todas as rotas com ela) | Quando usar |
|---|---|---|
| Produção | https://api.rabisistemas.com.br/api/v1/integrations | Implantação real da clínica. |
| Homologação (rotulado "Desenvolvimento" no Swagger) | https://api.hmg.rabisistemas.dev/api/v1/integrations | Ensaiar 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.
| Ponto | Como funciona |
|---|---|
| Onde nasce a chave | Recomendado: 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ões | Cada 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. |
| Validade | Depois de expirar — ou se for revogada — a chave passa a responder 401. |
| Monitorar a validade | Toda 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ção | Token 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 única | O token completo aparece uma única vez, na criação (ou na renovação). Perdeu? Renove (rbt_) ou peça outra chave (rbk_). |
| Revogação | Depois 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ção | Qualquer 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
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 chaverbk_— tabela). Vai no mesmo cabeçalho:Authorization: Bearer rbt_…. Sem a permissão da rota →403comescopoFaltante. ✅ 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.
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.
- 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 chaverbk_, pelo time Rabi no portal comercial (lembre dos até 60 s de tolerância). - Integração contínua? Registre o
X-ApiKey-Expires-Ate crie um alerta com antecedência (ex.: 15 dias): comrbt_, a clínica usa Renovar na tela de Integrações (o valor anterior deixa de valer — troque-o no sistema integrado); comrbk_, 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 orbt_(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.
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)
- Toda rota de listagem devolve o mesmo envelope:
{ dados: [...], page, pageSize, total, totalPages }— inclusive/tabelas-preco,/orcamentos,/financeiro/movimentacoese/estoque/saldo-produtos(normalizadas em 25/09/2026). - Parâmetros
page(padrão1) epageSize(padrão50, máximo200). Percorra atépage = totalPages. ✅ Novo — 14/10/2026 O teto de 200 itens por página passou a valer em toda a API externa (#669):pageSizeacima de 200 é reduzido sem erro — não conte com a página vir do tamanho pedido; percorra pelas páginas. - Leituras que não são paginadas de fato (ex.:
GET /empresas,GET /locais, auxiliares, avisos) usam o mesmo envelope, compagesempre1epageSize/totaliguais ao tamanho da lista inteira devolvida. - Percorra por
totalPages, não pelo tamanho da página: emGET /orcamentos(sempacienteId) a página é filtrada depois de paginar, entãodadospode vir com menos itens quepageSizemesmo havendo mais páginas. GET /convenios/{id}/farol/itens/{servicoRaizId}(novo, 26/09/2026) devolve só{ dados: [...] }, sempage/total: é a árvore inteira de um serviço, sem paginação.- Leituras de detalhe fora do envelope — a descrição da resposta no Swagger diz "Array direto": ex.:
GET /atendimentos/historico,GET /estoque/historico/{id},GET /tabelas-preco/precificacao,GET /orcamentos/status, anexos de orçamento eGET /nfse/notas/{id}/tentativas. Leia a descrição da rota. GET /agendamentosexigedata(a consulta é sempre de um dia — para vários dias, uma chamada por dia) e pagina de verdade; filtrospacienteId,profissionalId,statusId.GET /grades-colaboradoreGET /grades-equipamentosão paginadas de verdade, com filtroscolaboradorId/equipamentoId,localIdevigenteEm(só grades vigentes na data) — use-os para não trazer a grade inteira da clínica.GET /estoquepaginado, com filtrosprodutoIdelocalizacaoId(só linhas de entrada; histórico completo em/estoque/historico/{id}).GET /orcamentospaginado, com filtrosid,pacienteId,pacienteCpf,pacienteNome,statusId,createdAtDe,createdAtAte— atenção: compacienteIdo formato do item muda (a descrição da rota traz os dois formatos).- Filtro
ativo: nas listagens que o aceitam (convênios, pacientes, operadoras, serviços, colaboradores, produtos, equipamentos, taxas, fabricantes, depósitos), sem informar a lista traz ativos e inativos. Use?ativo=truepara conferir só o que está valendo.
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
- Valores monetários em reais na maioria das rotas — mas não em todas. Em reais,
50= R$ 50,00. Algumas rotas de leitura de faturamento devolvem valor em centavos ou como string — e isso está dito na descrição de cada uma no Swagger (ex.:GET /faturamento/guias/servico/{guiaFilha}eGET /faturamento/glosas/guia/{guiaMae}). Regra prática: fora das exceções sinalizadas na descrição da rota, é reais; ao consumir faturamento, leia a descrição da rota antes de somar ou comparar valores. - Datas em ISO 8601 —
2026-01-01T00:00:00.000Z(date-time) ou2026-09-24(date), conforme o campo. - Vários cadastros aceitam CNPJ com ou sem máscara. UF: empresa aceita id ou sigla (
"DF"); operadora e colaborador exigem o nome por extenso da UF ("Distrito Federal"); pacientes usamunidadeFederativaId. ConsulteGET /auxiliares/unidades-federativas. Desde 28/09/2026, UF omitida não grava mais a primeira UF da lista (operadora, empresa, colaborador). responsavelId: muitas escritas operacionais (agendamento, orçamento, atendimento, estoque, financeiro, faturamento) exigem o id de um colaborador já cadastrado, que fica registrado como responsável.
5.3 Atualizações (PUT) — campo omitido mantém, null limpa, lista enviada substitui ✅ Atualizado — 13/10/2026
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.
| Rota | Comportamento 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 · /planos | Upsert: 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/financeiro | Desconto: 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/prontuario | Sobrescreve 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:
| Recurso | O que acontece |
|---|---|
| Operadora | Recusa (400) se houver convênio ativo vinculado. |
| Empresa | Recusa (400) se tiver atendimentos, colaboradores, convênios, depósitos, locais ou movimentações financeiras ativas vinculadas. |
| Local | Recusa (409) se houver agendamentos, orçamentos, grades ou vínculos de serviço no local. |
| Colaborador | Desativa também grades, especialidades e vínculos de empresa; avisa (não bloqueia) se houver agendamento futuro. |
| Convênio | Se estiver em agendamentos ativos, a resposta traz um aviso. |
| Produto | Desativa 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. |
| Taxa | Desativaçã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 online | Exclusão lógica (deleted = true). |
| Sem rota de exclusão | Fornecedor, anexo de paciente, prontuário, movimentação financeira. |
5.5 Lotes (/bulk) e abas do convênio
| Rota | Máx. por requisição | Chave 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/bulk | 50 | o plural do recurso (convenios, pacientes…; financeiro: movimentacoes + responsavelId único) |
POST /nfse/tomadores/bulk | 100 | tomadores |
POST /tabelas-preco/produtos/bulk | 200 | precos |
PUT /convenios/{id}/colaboradores | 100 | colaboradores |
PUT /convenios/{id}/taxas|servicos|produtos|especialidades|planos | 200 | taxas, servicos, produtos, especialidades, planos |
- 201 = todos criados (nas abas do convênio: 200 = todos processados).
- 207 Multi-Status = falha parcial: confira
resultadositem a item peloindice(posição no array, começando em 0). ItensCRIADO/ATUALIZADOjá estão gravados — cada item é gravado em transação própria, nunca pela metade. - 400 = lote vazio, sem a chave esperada ou acima do limite.
- 429 = já existe um lote em andamento para a clínica e o recurso (nas abas do convênio: uma atualização por vez por convênio). Espere terminar e envie o próximo — lotes são sequenciais.
- Processamento interrompido após 45 segundos: o restante volta como
NAO_PROCESSADO. - Reenvie só os itens com
ERROouNAO_PROCESSADO. Detalhes em reprocessar um lote 207. - ✅ Novo — 30/09/2026 A API não tem "modo consulta": desde 29/09 (#632) as telas de convênio abrem em modo consulta e, desde 01/10, só gravam no Salvar depois de Liberar para edição; pela API,
PUT /convenios/{id}/…grava direto, como sempre (e o autor aparece no Histórico do convênio como "API externa"). Cuidado redobrado: confira o corpo antes de enviar e leia de volta peloGET/farol.
5.6 Códigos de resposta e o que fazer
| Código | Significado | O que fazer |
|---|---|---|
200 / 201 / 202 | Sucesso (201 = criado; alguns PUT respondem 202) | Guarde o id devolvido — ele é a entrada do próximo passo. |
207 | Lote com falha parcial | Leia resultados; reenvie só ERRO/NAO_PROCESSADO. |
400 | Requisição inválida (id inválido, lote vazio/grande demais, CPF inválido, dado inconsistente) — ou, em DELETE de empresa/operadora, vínculos ativos | Corrija o corpo/parâmetro; leia a mensagem em error. |
401 | Chave 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. |
403 | A 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á-la | Token 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. |
404 | Registro 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. |
409 | Conflito: 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 menor | Duplicidade: busque o registro existente (GET) e reutilize o id. Composição: corrija os serviços listados e tente de novo. |
422 | Referê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. |
429 | Lote/atualização já em andamento | Aguarde o anterior terminar; não dispare lotes em paralelo do mesmo recurso. |
503 | Falha 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)
- Exclusão de fornecedor (só leitura/criação/edição — a exclusão interna é física, não desativação).
- Preço de venda do produto (
valorUnitariobruto é exposto; o preço calculado pela engine de precificação, não). - Certificado digital, numeração e sincronização de histórico do NFS-e com a prefeitura (infraestrutura da clínica).
- Bloqueio de agenda, fila de espera, confirmação por SMS e edição campo a campo de guia de pré-faturamento (coberta pela edição completa da guia).
- Finalização de atendimento (baixa de estoque) e recursos usados no atendimento — o módulo de atendimento é voltado a migração de histórico, não à operação clínica ao vivo.
- Exclusão de prontuário e de movimentação financeira.
- Importação/exportação Excel em qualquer módulo.
- Criação dos tipos auxiliares (tipos de produto, de código, de serviço, de guia, de taxa, unidades de medida, princípios ativos etc.): a API só os lê (
GET /auxiliares/*). Crie pela tela e informe os ids.
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.
| # | Grupo | O que cobre | Operações | Caminhos | Referência |
|---|---|---|---|---|---|
| 1 | Empresas | Empresas e unidades da clínica | 5 | 2 | Referência — Cadastros |
| 2 | Depósitos | Depósitos de estoque da clínica | 6 | 3 | Referência — Cadastros |
| 3 | Locais | Locais de atendimento dentro de uma empresa/unidade | 5 | 2 | Referência — Cadastros |
| 4 | Auxiliares | Cadastros de domínio usados como ID em outras rotas — só leitura | 14 | 14 | Referência — Cadastros |
| 5 | Operadoras | Operadoras de convênio | 6 | 3 | Referência — Cadastros |
| 6 | Fornecedores | Fornecedores da clínica | 5 | 3 | Referência — Cadastros |
| 7 | Fabricantes | Fabricantes de produtos | 6 | 3 | Referência — Cadastros |
| 8 | Taxas | Taxas cobradas pela clínica | 6 | 3 | Referência — Cadastros |
| 9 | Produtos | Produtos/materiais da clínica | 6 | 3 | Referência — Cadastros |
| 10 | Equipamentos | Equipamentos da clínica | 6 | 3 | Referência — Cadastros |
| 11 | Serviços | Serviços oferecidos pela clínica | 6 | 3 | Referência — Cadastros |
| 12 | Colaboradores | Profissionais/equipe da clínica | 7 | 4 | Referência — Cadastros |
| 13 | Tabelas de Preço | Tabela de preço interna e preço de produto dentro dela | 8 | 5 | Referência — Cadastros |
| 14 | Convênios | Cadastro de convênios da clínica | 22 | 13 | Referência — Cadastros |
| 15 | Grade de Colaborador | Grade de horários/agenda do colaborador | 7 | 4 | Referência — Cadastros |
| 16 | Grade de Equipamento | Grade de horários/agenda do equipamento | 5 | 2 | Referência — Cadastros |
| 17 | Financeiro | Movimentações financeiras e confirmação de pagamento (Pix/link) | 6 | 4 | Referência — Operação |
| 18 | Estoque | Movimentação de estoque de produtos (entrada, saída, transferência) | 12 | 12 | Referência — Operação |
| 19 | Pacientes | Cadastro de pacientes da clínica | 11 | 6 | Referência — Cadastros |
| 20 | Parâmetros | Regras de negócio e controle de acesso do tenant | 45 | 31 | Referência — Parâmetros |
| 21 | Agendamentos | Núcleo de agenda: buscar horário, criar, cancelar, listar | 8 | 7 | Referência — Operação |
| 22 | Orçamentos | Estimativa de custo pré-atendimento | 10 | 9 | Referência — Operação |
| 23 | Atendimentos | Atendimento e prontuário — voltado a migração de histórico | 6 | 5 | Referência — Operação |
| 24 | Faturamento | Pré-faturamento (guia de convênio/TISS), divergência, recebimento e glosa | 24 | 24 | Referência — Operação |
| 25 | NFS-e | Emissão de nota fiscal de serviço e cadastro de tomadores | 28 | 25 | Referência — Operação |
| Total | 25 grupos | 270 | 193 |