⚙️ Referência — Operação

GET /agendamentos/datas/disponiveis

Datas disponíveis para agendamento · Permissão: agendamento:read

Parâmetros

Respostas

• 200 — responsavelId é obrigatório na prática — sem ele a rota devolve {datasDisponiveis: [], message: "Data disponível com grades encontradas"} direto, ignorando os outros filtros. tipoResponsavel deve ser exatamente COLABORADOR ou EQUIPAMENTO (case-sensitive); outro valor cai no mesmo fallback vazio.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /agendamentos/horarios/disponiveis

Horários disponíveis numa data · Permissão: agendamento:read

Corpo (application/json) — obrigatório

Campos obrigatórios: tipo, data, localId, agendamentoId

Respostas

• 200 — Array direto (sem envelope).
• 400 — tipo/data ausente ou inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /agendamentos/locais/disponiveis

Locais disponíveis para agendamento · Permissão: agendamento:read

Respostas

• 200 — Envelope de lista padrão, mas page/pageSize não são paginação real — sempre devolve tudo (page:1, pageSize:total).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /agendamentos/motivo-cancelamento

Listar motivos de cancelamento · Permissão: agendamento:read

Necessário para escolher motivoCancelamentoId ao cancelar. Bug conhecido: em erro de banco, o use case não lança — devolve o número 401 como "resultado", e a rota responde 200 com corpo 401 (número cru) em vez de um erro HTTP de verdade. Reportado ao time.

Respostas

• 200 — Envelope de lista padrão (page:1, pageSize:total, sem paginação real). Ver bug acima sobre o corpo 401.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /agendamentos

Listar agendamentos · Permissão: agendamento:read

data é obrigatório — a consulta interna sempre filtra por um dia (não dá pra listar vários dias de uma vez nesta rota).

Parâmetros

Respostas

• 200 — Lista paginada (do dia informado)
• 400 — Informe data
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /agendamentos

Criar agendamento · Permissão: agendamento:create

Sem pagamento no ato — o campo movimentacaoFinanceira não é suportado por esta API (dispara emissão automática de NFS-e). Consome o limite mensal do plano (agendamentos.mes).

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, paciente, paciente.id, idGrade, data, statusId, procedimentos, procedimentos[].procedimentoId, procedimentos[].convenioId

Respostas

• 201 — Agendamento criado
• 400 — Pagamento no ato não é suportado por esta API, ou responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Conflito de horário/farol de rentabilidade bloqueando a criação
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /agendamentos/{id}

Consultar agendamento · Permissão: agendamento:read

Parâmetros

Respostas

• 200 — Agendamento
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Agendamento não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PATCH /agendamentos/{id}/cancelar

Cancelar agendamento · Permissão: agendamento:delete

Libera reservas de medicamento vinculadas e notifica a fila de espera, se houver.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, motivoCancelamentoId

Respostas

• 200 — Corpo fixo — não reflete o resultado das notificações de fila de espera, que são disparadas de forma assíncrona (fire-and-forget) e não aparecem na resposta.
• 400 — Motivo de cancelamento é obrigatório, ou responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Este status não pode ser cancelado (ex.: já atendido, já cancelado)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos

Listar orçamentos · Permissão: orcamento:read

O shape do item muda por completo conforme pacienteId é informado ou não na query — são dois formatos de resposta atrás do mesmo endpoint, não só um filtro a mais.

Parâmetros

Respostas

• 200 — SEM pacienteId: paginação real, mas com uma ressalva — depois de paginar, o código ainda filtra a página em memória (remove sessões usadas > autorizadas), então dados.length pode vir menor que pageSize mesmo havendo mais resultados, e total pode não bater exatamente com a soma real de itens retornáveis. COM pacienteId: page sempre 1, pageSize/total = tamanho da lista completa (não é paginação real).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /orcamentos

Criar orçamento · Permissão: orcamento:create

Pagamento no ato (movimentacaoFinanceira) é permitido e pode disparar emissão automática de NFS-e. Bloqueado (422) se o farol de rentabilidade exigir aprovação e não houver token/pendência informada.

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, paciente, paciente.id, idGrade, gradeBaseId, responsavelBaseId, tipoAtendimentoConsulta, tipoRepeticao, data, hora, statusId, procedimentos, procedimentos[].procedimentoId, procedimentos[].convenioId, contatos

Se enviar movimentacaoFinanceira.registroFinanceiro, exige: movimentacaoFinanceira.registroFinanceiro[].quantidade, movimentacaoFinanceira.registroFinanceiro[].valorUnitario, movimentacaoFinanceira.registroFinanceiro[].contendo, movimentacaoFinanceira.registroFinanceiro[].centroDeCustoId, movimentacaoFinanceira.registroFinanceiro[].tipoConta, movimentacaoFinanceira.registroFinanceiro[].tipoConjunto

Se enviar movimentacaoFinanceira.duplicatas, exige: movimentacaoFinanceira.duplicatas[].vencimento, movimentacaoFinanceira.duplicatas[].valor, movimentacaoFinanceira.duplicatas[].aVista

Respostas

• 201 — Orçamento criado
• 400 — responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Bloqueado pelo farol de rentabilidade — falta aprovação
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos/status

Listar status possíveis de orçamento · Permissão: orcamento:read

findMany() sem filtro nem ordenação — vem tudo, inclusive status com ativo:false, em ordem não garantida. Inclui os status automáticos (campo automatico: true: 8 Vencido, 10 Pago, 11 Agendado, 12 Concluído, 13 Renegociado), que só o sistema grava.

Respostas

• 200 — Array direto (sem envelope).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos/consideracoes

Listar considerações padrão de orçamento · Permissão: orcamento:read

Não é lista — é uma STRING crua (o texto configurado em ParametrosOrcamento.consideracoesGerais). Se nunca configurado, devolve string vazia "" (não null, não 404).

Respostas

• 200 — String crua com o texto configurado (ou vazia).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /orcamentos/{id}

Atualizar orçamento · Permissão: orcamento:update

Orçamento já aprovado não pode ter procedimentos/valores editados (precisa criar um novo) — exceção: registrar pagamento continua funcionando.

Atualização parcial: campo omitido mantém o valor atual; null limpa; lista omitida mantém; lista enviada substitui ([] apaga).

• procedimentos omitido: os serviços do orçamento não mudam.
• procedimentos enviado substitui a lista, sem perder histórico: o serviço já existente é reconhecido por orcamentoServicoId (ou pelo procedimentoId quando só há um igual) e atualizado no lugar — mantém sessões realizadas e o vínculo com agendamentos. Serviço sem correspondência é criado; serviço que não veio sai do orçamento (o agendamento ligado a ele tem o serviço desativado, como na tela).
• Por serviço: campo omitido (valor, sessões, senha, carteira, plano, profissional, grade, especialidade, solicitante) mantém; produtos/taxas omitidos mantêm, enviados substituem.
• Valores em reais. A leitura devolve produtos e taxas em centavos — divida por 100 antes de reenviar.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, paciente, paciente.id, idGrade, gradeBaseId, responsavelBaseId, tipoAtendimentoConsulta, tipoRepeticao, data, hora, statusId, procedimentos, procedimentos[].procedimentoId, procedimentos[].convenioId, contatos

Se enviar movimentacaoFinanceira.registroFinanceiro, exige: movimentacaoFinanceira.registroFinanceiro[].quantidade, movimentacaoFinanceira.registroFinanceiro[].valorUnitario, movimentacaoFinanceira.registroFinanceiro[].contendo, movimentacaoFinanceira.registroFinanceiro[].centroDeCustoId, movimentacaoFinanceira.registroFinanceiro[].tipoConta, movimentacaoFinanceira.registroFinanceiro[].tipoConjunto

Se enviar movimentacaoFinanceira.duplicatas, exige: movimentacaoFinanceira.duplicatas[].vencimento, movimentacaoFinanceira.duplicatas[].valor, movimentacaoFinanceira.duplicatas[].aVista

Respostas

• 201 — Orçamento atualizado
• 400 — responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Orçamento já aprovado não pode ser editado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /orcamentos/status/{idOrcamento}/{idStatus}

Alterar status do orçamento · Permissão: orcamento:update

Ao aprovar, promove agendamentos vinculados que estavam pendentes de orçamento e sincroniza o financeiro. Status automáticos (8 Vencido, 10 Pago, 11 Agendado, 12 Concluído, 13 Renegociado) são definidos pelo sistema e recusados aqui (422). Com o status automático ativo na clínica: só trocas permitidas (ex.: Vencido só vai para Cancelado); cancelar exige motivo no corpo e, havendo agendamento futuro ou pagamento, responde 409 ORCAMENTO_CANCELAR_CONFIRMAR até reenviar com confirmarCancelamento: true; reabrir Cancelado/Concluído exige autorizacao: { colaboradorId, senha } de nível 3 (403).

Parâmetros

Respostas

• 200 — Efeitos colaterais que não aparecem na resposta: pode promover agendamentos vinculados para "Confirmado", disparar notificação, sincronizar MovimentacaoFinanceira/duplicatas.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos/{id}/{isAgendamento}

Consultar orçamento · Permissão: orcamento:read

isAgendamento indica se o id é de orçamento ou de agendamento vinculado (1 ou 0).

Parâmetros

Respostas

• 200 — Orçamento
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Orçamento não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos/anexo/listar/{orcamentoId}

Listar anexos do orçamento · Permissão: orcamento:read

Sem URL assinada (só link cru — chave do storage). Se precisar da URL pra baixar, use GET /orcamentos/anexo/listar-necessarios/{pacienteId}.

Parâmetros

Respostas

• 200 — Array direto (sem envelope), ordenado por createdAt desc.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /orcamentos/anexo/listar-necessarios/{pacienteId}

Listar documentos necessários para o paciente · Permissão: orcamento:read

Agrupado por tipo de anexo. Anexos do paciente sem tipoAnexoId são excluídos silenciosamente do resultado inteiro.

Parâmetros

Respostas

• 200 — Array direto (sem envelope), grupos com algum anexado primeiro.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /orcamentos/anexo/vincular/{anexoId}/{orcamentoId}

Vincular/desvincular anexo do orçamento (toggle) · Permissão: orcamento:update

Não é idempotente — é um toggle. Se o vínculo não existe, cria; se já existe, remove. Chamar duas vezes seguidas vincula e depois desvincula. Não é seguro re-tentar cegamente em caso de timeout/retry automático, já que a resposta vazia não informa qual dos dois estados resultou.

Parâmetros

Respostas

• 204 — Vínculo alternado (criado ou removido, conforme o estado anterior) — sem corpo.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Anexo não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /atendimentos

Criar atendimento · Permissão: atendimento:create

Voltado a migração de histórico — cria por trás um Agendamento sintético e um prontuário vazio. horarioInicioAtendimento sempre grava "agora"; use PUT /{id} com horarioInicio para corrigir com a data real.

Corpo (application/json) — obrigatório

Campos obrigatórios: pacienteId, colaboradorId, empresaId, servicoId, convenioId

Respostas

• 201 — Atendimento criado
• 400 — Campo obrigatório faltando ou inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /atendimentos/{id}

Atualizar atendimento · Permissão: atendimento:update

Principal uso: corrigir horarioInicio com a data real de um atendimento migrado.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId

Respostas

• 202 — Devolve o registro cru de Atendimento (sem includes de paciente/documentos). Se DocumentosAtendimentos foi enviado no corpo, é processado à parte e não aparece na resposta.
• 400 — responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Versão desatualizada (conflito de edição concorrente) — recarregue e tente de novo
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /atendimentos/{id}

Consultar atendimento · Permissão: atendimento:read

Todos os segmentos são opcionais: /atendimentos/{id}, /atendimentos/{id}/{pacienteId} ou filtre só por paciente/agendamento. Se id não existir, devolve 200 com corpo [] (array vazio), não 404.

Parâmetros

Respostas

• 200 — Objeto do atendimento (com paciente e agendamento incluídos, agendamento inclui status e convênios do paciente) quando encontrado — ou array vazio [] se o id não existir.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /atendimentos/prontuario

Editar prontuário · Permissão: atendimento:update

Sobrescreve o texto no lugar — não guarda a versão anterior.

Corpo (application/json) — obrigatório

Campos obrigatórios: prontuarioId, conteudo

Respostas

• 202 — Devolve o registro cru de ProntuarioAtendimento.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /atendimentos/novo-prontuario

Criar um novo prontuário no atendimento · Permissão: atendimento:create

Cria uma linha nova (o atendimento pode ter mais de um prontuário) — não edita o existente.

Corpo (application/json) — obrigatório

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Corpo de sucesso é um inteiro cru — o id do prontuário recém-criado, não um objeto.
• 400 — agendamentoId ou atendimentoId são obrigatórios
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Agendamento ou atendimento não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /atendimentos/historico

Histórico do paciente (linha do tempo) · Permissão: atendimento:read

Leitura ao vivo — reflete qualquer edição de prontuário na hora. pacienteId é obrigatório nesta API (a rota interna aceita omitir, mas sem filtro ela varre o histórico inteiro do tenant e pode travar/estourar tempo). Sem paginação real — sempre devolve o histórico completo que casar com os filtros, um item por atendimento encontrado.

Parâmetros

Respostas

• 200 — Array direto (sem envelope de paginação).
• 400 — Informe pacienteId
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias

Listar todas as guias em pré-faturamento · Permissão: faturamento:read

Respostas

• 200 — Lista de guias (nota: a rota interna usa items, normalizado pra dados nesta API)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/buscar-por-numero-guia

Buscar guia pelo número · Permissão: faturamento:read

O parâmetro de query é numero, não numeroGuia — e é obrigatório.

Parâmetros

Respostas

• 200 — Envelope de lista padrão, mesmo sendo uma busca por número específico (pode casar mais de um registro).
• 400 — Parâmetro 'numero' é obrigatório
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/pacientes

Listar pacientes com pré-faturamento pendente · Permissão: faturamento:read

Limitado a 50 por padrão.

Respostas

• 200 — Lista de pacientes
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/info-extras/{guiaMae}/{guiaFilha}

Informações extras da guia · Permissão: faturamento:read

Payload grande — dados cadastrais completos de paciente/convênio, autorização, e a composição de serviço/produtos/taxas (originais e convertidos pelo convênio). Valores monetários aqui já em reais.

Parâmetros

Respostas

• 200 — Informações extras
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/valores-atualizados/{guiaMae}/{guiaFilha}

Valores atualizados da guia · Permissão: faturamento:read

valorTotal é só o valor resolvido do serviço, apesar do nome — não é a soma de produtos+taxas.

Parâmetros

Respostas

• 200 — Valores atualizados (em reais)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/conversoes-convenio/{guiaMae}/{guiaFilha}/{convenioId}

Conversões de convênio disponíveis para a guia · Permissão: faturamento:read

Parâmetros

Respostas

• 200 — Conversões disponíveis (em reais)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/{guiaMae}/filhas

Listar guias filhas de uma guia mãe · Permissão: faturamento:read

A guia mãe (guiaFilha === guiaMae) vem primeiro na lista.

Parâmetros

Respostas

• 200 — Lista de guias filhas
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/servico/{guiaFilha}

Serviço vinculado a uma guia filha · Permissão: faturamento:read

Payload grande: devolve as linhas cruas de ServicoAtendimento (toda coluna do modelo) com relações completas de colaborador, conversão de convênio, produtos/taxas/equipamentos usados — não um resumo. Valores (valorServico, valorServicoConvertido) vêm em centavos, sem conversão.

Parâmetros

Respostas

• 200 — Linhas de ServicoAtendimento (payload grande, ver descrição)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/guias/valores-atendimento/{atendimentoId}

Valores faturados de um atendimento · Permissão: faturamento:read

Um item por serviço prestado no atendimento.

Parâmetros

Respostas

• 200 — Valores do atendimento (em reais)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /faturamento/guias/{servicoAtendimentoId}

Editar a guia por completo · Permissão: faturamento:update

Edição da guia: número da guia, conversão de convênio/colaborador, valores de produto/taxa/serviço. Não sensibiliza estoque (já foi baixado no consumo real do atendimento).

Atualização parcial: campo omitido mantém o valor atual; null limpa; lista omitida mantém; lista enviada substitui ([] apaga).

• colaborador, colaboradorConvertido, servicoConvertido, produtos e taxas são opcionais.
• centroConsumoId, especialidade do executante (colaborador.colaboradorEspecialidadeId) e colaborador convertido omitidos mantêm; null desvincula.
• Produto/taxa com produtoAtendimentoId/taxaAtendimentoId: só os campos enviados mudam (quantidade, valor, código etc. omitidos mantêm). Produto/taxa sem esse id é adicionado. Itens que não vieram não são removidos.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, preFaturamento

Respostas

• 201 — Corpo simples — não ecoa o objeto preFaturamento enviado.
• 400 — responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /faturamento/guias/{guiaMae}/confirmar

Confirmar pré-faturamento da guia · Permissão: faturamento:update

Valida campos TISS obrigatórios (ex.: número da guia da operadora) e marca a guia como pré-faturada.

Parâmetros

Respostas

• 201 — Corpo de sucesso é o número cru 200 (não um objeto) — comportamento observado, o use case retorna o literal 200 e o controller devolve isso como corpo com status HTTP 201.
• 400 — Guia/serviço não encontrado, ou validação TISS falhou (lista de campos faltando na mensagem)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/divergencias

Listar divergências atendido x faturado · Permissão: faturamento:read

Cache Redis de 60s (quando disponível) — dado pode estar até 60s desatualizado.

Parâmetros

Respostas

• 200 — Lista paginada.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /faturamento/divergencias/{numeroGuiaMae}/faturar-diferenca

Faturar a diferença de uma divergência · Permissão: faturamento:update

Para itens sub-faturados, inclui a diferença num lote. Bloqueado (409) se houver item sobre-faturado — esse caso exige correção manual.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId

Respostas

• 200 — Diferença faturada
• 400 — responsavelId ausente/inválido, ou não há divergência pendente para esta guia
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Item sobre-faturado, ou a diferença não corresponde a nenhum registro — exige correção manual
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/recebimento

Listar recebimento físico de guias · Permissão: faturamento:read

Parâmetros

Respostas

• 200 — Lista paginada
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/recebimento/opcoes

Opções de filtro do recebimento de guia · Permissão: faturamento:read

Respostas

• 200 — Opções (valores distintos já cadastrados)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /faturamento/recebimento/registrar

Registrar recebimento físico de guias · Permissão: faturamento:create

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, guias

Respostas

• 201 — Corpo simples — não ecoa ids nem quantas guias foram processadas.
• 400 — Nenhuma guia informada, ou responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /faturamento/recebimento/devolver

Registrar devolução de guias · Permissão: faturamento:update

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, guias

Respostas

• 200 — Corpo simples — não ecoa ids nem quantas guias foram processadas.
• 400 — Nenhuma guia informada, ou responsavelId ausente/inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/glosas

Listar itens em conta a receber (elegíveis a glosa) · Permissão: faturamento:read

Respostas

• 200 — Lista de itens
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/glosas/guia/{guiaMae}

Listar serviços/produtos/taxas de uma guia mãe · Permissão: faturamento:read

Não é uma lista apesar do nome — é um único objeto agregado com três arrays internos. valor/valorPagoGlosa aqui vêm como string, em centavos brutos (diferente de valorTotal de /glosas, que é string em reais).

Parâmetros

Respostas

• 200 — Itens da guia
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/glosas/status

Listar status de glosa possíveis · Permissão: faturamento:read

id não é numérico — é o próprio valor do enum como texto (ex.: "GLOSADO").

Respostas

• 200 — Lista de status
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /faturamento/glosas/motivos

Listar motivos de glosa · Permissão: faturamento:read

Respostas

• 200 — Lista de motivos
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /faturamento/glosas/produto

Registrar glosa de produto · Permissão: faturamento:update

Só grava o resultado da glosa no item (não gera lançamento financeiro). Nomes de campo reais do body (confirmados no código, diferentes do que o nome sugere): ProdutoAtendimentoId — apesar do nome, é o id de produtoConvercao (a linha de conversão pelo convênio), não o id de ProdutoAtendimento. valorPagoGlosa precisa ser enviado em centavos (padrão diferente de outras rotas de faturamento, que usam reais). Erro de motivoGlosado (id) não encontrado em term_mensagens devolve 401, não 400/422 — comportamento observado, não é sobre autenticação.

Corpo (application/json) — obrigatório

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Nenhum eco do registro atualizado.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /faturamento/glosas/taxa

Registrar glosa de taxa · Permissão: faturamento:update

Mesmas ressalvas de PUT /faturamento/glosas/produto (id é de taxaConvercao, valorPagoGlosa em centavos, erro de motivo devolve 401).

Corpo (application/json) — obrigatório

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Nenhum eco do registro atualizado.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /faturamento/glosas/servico

Registrar glosa de serviço · Permissão: faturamento:update

Mesmas ressalvas de PUT /faturamento/glosas/produto (id é de servicoConversao, valorPagoGlosa em centavos, erro de motivo devolve 401).

Corpo (application/json) — obrigatório

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Nenhum eco do registro atualizado.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /financeiro/pagamentos/confirmacao

Confirma pagamento (Pix ou link) e dá baixa automática na parcela · Permissão: financeiro:update

Para o provedor de pagamento (#409) avisar que a cobrança foi paga. Identifique a parcela por duplicataId ou por identificadorCobranca (o txid/id da cobrança gravado no campo transacao da parcela). A parcela fica paga com identificadorPagamento (endToEndId do Pix ou id da transação do link), o que já a comprova. Idempotente: repetir a mesma confirmação devolve jaConfirmado: true (200) sem pagar de novo. Valor menor que o da parcela → 409.

Corpo (application/json) — obrigatório

Campos obrigatórios: valor, identificadorPagamento, meio

Respostas

• 200 — Pagamento já confirmado antes (idempotente)
• 201 — Parcela paga
• 404 — Parcela da cobrança não encontrada
• 409 — Parcela paga por outro pagamento ou valor menor que o da parcela

GET /financeiro/movimentacoes

Listar movimentações financeiras · Permissão: financeiro:read

Parâmetros

Respostas

• 200 — Lista paginada
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /financeiro/movimentacoes

Cadastrar movimentação financeira · Permissão: financeiro:create

Pode disparar emissão automática de NFS-e dependendo da configuração do emitente.

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, tipoMovimentacaoFinanceira, tipoFinanceiro, categoriaDePagamentoId, contasCaixaId, data, parcelas, registroFinanceiro, registroFinanceiro[].quantidade, registroFinanceiro[].valorUnitario, registroFinanceiro[].contendo, registroFinanceiro[].centroDeCustoId, registroFinanceiro[].tipoConta, registroFinanceiro[].tipoConjunto

Se enviar duplicatas, exige: duplicatas[].vencimento, duplicatas[].valor, duplicatas[].aVista

Respostas

• 201 — Movimentação criada
• 400 — responsavelId ausente/inválido, ou conta caixa não encontrada
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /financeiro/movimentacoes/bulk

Cadastrar várias movimentações financeiras de uma vez · Permissão: financeiro:create

Até 50 itens por requisição (chave movimentacoes), todos com o mesmo responsavelId. 207 = falha parcial.

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, movimentacoes, movimentacoes[].responsavelId, movimentacoes[].tipoMovimentacaoFinanceira, movimentacoes[].tipoFinanceiro, movimentacoes[].categoriaDePagamentoId, movimentacoes[].contasCaixaId, movimentacoes[].data, movimentacoes[].parcelas, movimentacoes[].registroFinanceiro, movimentacoes[].registroFinanceiro[].quantidade, movimentacoes[].registroFinanceiro[].valorUnitario, movimentacoes[].registroFinanceiro[].contendo, movimentacoes[].registroFinanceiro[].centroDeCustoId, movimentacoes[].registroFinanceiro[].tipoConta, movimentacoes[].registroFinanceiro[].tipoConjunto

Se enviar movimentacoes[].duplicatas, exige: movimentacoes[].duplicatas[].vencimento, movimentacoes[].duplicatas[].valor, movimentacoes[].duplicatas[].aVista

Cada item de movimentacoes[] tem os mesmos campos de POST /financeiro/movimentacoes (máx. 50 itens).

Respostas

• 201 — Todas criadas
• 207 — Falha parcial
• 400 — Lote vazio ou acima de 50 itens
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 429 — Já existe um lote em andamento para esta clínica e recurso
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /financeiro/movimentacoes/{id}

Consultar movimentação financeira · Permissão: financeiro:read

Parâmetros

Respostas

• 200 — Movimentação
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Movimentação não encontrada
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /financeiro/movimentacoes/{id}

Atualizar movimentação financeira · Permissão: financeiro:update

Pode disparar emissão automática de NFS-e dependendo da configuração do emitente (fire-and-forget — falha só é logada, não afeta a resposta). A resposta é bem mais rica que o schema MovimentacaoFinanceira documentado nas rotas de leitura — o repository busca com include: {RegistroFinanceiro: true, duplicatas: true} e devolve tudo.

Atualização parcial: campo omitido mantém o valor atual; null limpa; lista omitida mantém; lista enviada substitui ([] apaga). Nenhum campo é obrigatório.

• registroFinanceiro e duplicatas omitidos: lançamentos e parcelas não mudam.
• Lista enviada: item com id é atualizado no lugar e só nos campos enviados — o lançamento mantém vínculos (atendimento, guia do XML, glosa, orçamento, estoque) e a parcela mantém conciliação e anexo. Item sem id é criado (precisa vir completo). Item que não veio é removido. id de outra movimentação responde 400.
• Valores em reais. A leitura (GET) devolve em centavos — divida por 100 antes de reenviar.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, tipoMovimentacaoFinanceira, tipoFinanceiro, categoriaDePagamentoId, contasCaixaId, data, parcelas, registroFinanceiro, registroFinanceiro[].quantidade, registroFinanceiro[].valorUnitario, registroFinanceiro[].contendo, registroFinanceiro[].centroDeCustoId, registroFinanceiro[].tipoConta, registroFinanceiro[].tipoConjunto

Se enviar duplicatas, exige: duplicatas[].vencimento, duplicatas[].valor, duplicatas[].aVista

Respostas

• 200 — Todos os campos escalares de MovimentacaoFinanceira + RegistroFinanceiro[] + duplicatas[]. Todo valor monetário (valorUnitario, valor, valorPago, multa, juros, outrosAcrescimos, desconto, descontoGeral, valorPagoGlosa) é inteiro em centavos.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Movimentação não encontrada
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque

Listar posições de estoque · Permissão: estoque:read

Só linhas de entrada (movimentações de saída/transferência não aparecem aqui — use /estoque/historico/{id} pra ver todo o histórico de um produto).

Parâmetros

Respostas

• 200 — Lista paginada
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/saldo-produtos

Saldo atual em estoque por produto · Permissão: estoque:read

Quantidade calculada (soma de entradas menos saídas), não um campo fixo.

Parâmetros

Respostas

• 200 — Lista paginada. Cada item tem todos os campos do cadastro do produto (Fabricante/TipoProduto incluídos) mais 3 campos calculados: unidadeTotal (saldo restante), valor (custo total em reais, já convertido) e valorUnitario (custo médio por unidade, em reais). A lista bruta de posições usada no cálculo não aparece no item.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/{id}

Consultar posição de estoque · Permissão: estoque:read

Parâmetros

Respostas

• 200 — Posição de estoque
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Posição não encontrada
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/historico/{id}

Histórico de movimentações de um produto · Permissão: estoque:read

Sem paginação real apesar do nome do parâmetro id — devolve o histórico completo do produto sempre (o use case aceita skip/take, mas o controller nunca os lê da query, então nunca são usados). Linhas de entrada com valorUnitarioEntrada <= 0 são removidas; saída e outros tipos são sempre mantidos.

Parâmetros

Respostas

• 200 — Array direto (sem envelope de paginação) com o histórico completo do produto.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Falha ao buscar histórico de movimentações
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/ultima-compra/{id}

Última compra de um produto · Permissão: estoque:read

Nunca lança erro de "não encontrado" — se não houver dados, os valores vêm 0.

Parâmetros

Respostas

• 200 — Sempre 200, mesmo sem dados (valores ficam 0 nesse caso).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/movimentacao/{id}

Consultar movimentação por id · Permissão: estoque:read

id aqui é o id da própria posição de estoque (diferente de /estoque/historico/{id}, onde é o id do produto). Sem conversão de centavos (diferente de todas as outras rotas de estoque) e sem nenhum include de nome — só os campos crus do Prisma, com FKs como id.

Parâmetros

Respostas

• 200 — Se id não existir, devolve 200 com corpo null (não 404).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Falha ao buscar movimentação de estoque
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/buscar/{lote}/{produtoId}/{localizacaoId}

Buscar posição por lote/produto/depósito · Permissão: estoque:read

Só considera entradas com saldo positivo (quantidade > 0, TipoDeMovimentacaoId=1). Mesmo formato cru do GET /estoque/movimentacao/{id} — sem conversão de centavos, sem includes de nome.

Parâmetros

Respostas

• 200 — Se não achar, devolve 200 com corpo null (não 404).
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Falha ao buscar posição de estoque
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /estoque/lotes-produtos/{idProduto}/{idLocalizacao}

Listar lotes disponíveis de um produto em um depósito · Permissão: estoque:read

Mesmo controller e mesmo shape de GET /estoque — só entradas (TipoDeMovimentacaoId=1), com valores já convertidos para reais.

Parâmetros

Respostas

• 200 — Lista paginada — mesmo shape de item de GET /estoque.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /estoque/entrada

Registrar entrada de estoque · Permissão: estoque:create

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, produtoId, localizacaoId, motivoId, quantidade

Respostas

• 201 — Entrada registrada
• 400 — responsavelId ausente/inválido, ou campo obrigatório faltando
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Falha ao registrar entrada de estoque
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /estoque/saida

Registrar saída de estoque · Permissão: estoque:create

Recusada se não houver saldo suficiente, a não ser que permitirNegativo: true.

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, produtoId, localizacaoId, motivoId, quantidade, lote

Respostas

• 201 — Saída registrada
• 400 — responsavelId ausente/inválido, ou campo obrigatório faltando
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — Estoque insuficiente, motivo inválido para saída, ou depósito inativo
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /estoque/transferencia

Transferir estoque entre depósitos · Permissão: estoque:create

Corpo (application/json) — obrigatório

Campos obrigatórios: responsavelId, produtoId, localizacaoId, localizacaoParaId, motivoId, quantidade, lote

Respostas

• 201 — Transferência registrada
• 400 — responsavelId ausente/inválido, ou campo obrigatório faltando
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Este depósito não possui este produto com este lote/validade
• 422 — Estoque insuficiente para transferência
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /estoque/previsao

Previsão de consumo de estoque · Permissão: estoque:read

Não envolve valores monetários, só quantidades.

Corpo (application/json) — obrigatório

Campos obrigatórios: localId, produtos, produtos[].produtoId

Respostas

• 200 — Previsão por produto.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 422 — localId ausente ou produtos não é um array
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/emitentes

Listar emitentes · Permissão: nfse:read

Necessário para escolher emitenteId ao calcular uma nota. Sem certificado digital nem configuração de infraestrutura — isso não é exposto por esta API.

Respostas

• 200 — Lista
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/emitentes/{id}

Consultar emitente · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Emitente
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Emitente não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/perfis-fiscais

Listar perfis fiscais · Permissão: nfse:read

Necessário para escolher perfilId ao calcular uma nota.

Respostas

• 200 — Lista
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/perfis-fiscais/{id}

Consultar perfil fiscal · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Perfil fiscal
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Perfil não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/tomadores

Listar tomadores · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Lista (até 20 resultados)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/tomadores

Cadastrar tomador · Permissão: nfse:create

Corpo (application/json) — obrigatório

Campos obrigatórios: nome, tipo

Respostas

• 201 — Tomador criado
• 400 — Informe nome e tipo, e cnpj (14 dígitos) ou cpf (11 dígitos)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/tomadores/bulk

Cadastrar vários tomadores de uma vez · Permissão: nfse:create

Até 100 itens por requisição (chave tomadores). 207 = falha parcial.

Corpo (application/json) — obrigatório

Campos obrigatórios: tomadores, tomadores[].nome, tomadores[].tipo

Cada item de tomadores[] tem os mesmos campos de POST /nfse/tomadores (máx. 100 itens).

Respostas

• 201 — Todos criados
• 207 — Falha parcial
• 400 — Lote vazio ou acima de 100 itens
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 429 — Já existe um lote em andamento para esta clínica e recurso
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/tomadores/{id}

Consultar tomador · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Tomador
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Tomador não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /nfse/tomadores/{id}

Atualizar tomador · Permissão: nfse:update

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: nome, tipo

Respostas

• 200 — Tomador atualizado
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Tomador não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/tomadores/{id}/completar

Completar cadastro do tomador · Permissão: nfse:update

Preenche campos vazios a partir do histórico de notas e/ou consulta à Receita Federal (PJ). Só preenche o que já não estiver preenchido.

Parâmetros

Corpo (application/json)

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Campos preenchidos. Efeito colateral: já grava os campos preenchidos no tomador (prisma.nfseTomador.update) — a resposta é o diff aplicado, não o tomador inteiro atualizado.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Tomador não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/tomadores/sincronizar-paciente/{pacienteId}

Sincronizar tomador a partir de um paciente · Permissão: nfse:read

Cria/garante um tomador clonando o perfil fiscal padrão de pessoa física, sem precisar configurar fiscal por paciente. Idempotente (find-or-create por paciente).

Parâmetros

Respostas

• 200 — Tomador sincronizado
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Paciente não encontrado
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas

Listar notas · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Lista
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas

Calcular nota (não emite) · Permissão: nfse:create

Calcula e confere os valores, sem enviar nada à prefeitura ainda — use POST /nfse/notas/{id}/emitir para efetivar. Idempotente via header Idempotency-Key ou campo chaveIdempotencia.

Corpo (application/json) — obrigatório

Campos obrigatórios: emitenteId, tomadorId, perfilId, valorServicos, dataCompetencia

Respostas

• 201 — Nota calculada
• 400 — emitenteId/tomadorId/perfilId inválido ou inativo, ou valorServicos/dataCompetencia inválido
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Guarda de tomador falhou (ex.: documento não confirmado)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}

Consultar nota · Permissão: nfse:read

Parâmetros

Respostas

• 200 — Nota
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota não encontrada
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/emitir

Emitir nota — EFEITO FISCAL · Permissão: nfse:create

Envia a nota de verdade à prefeitura. Consome o limite mensal do plano (nfse.notas.mes). Campo forcar: true no corpo emite mesmo se a conferência automática não estiver apta (assume o risco). modo: "assincrono" só vale para o padrão nacional.

Parâmetros

Corpo (application/json)

Nenhum campo obrigatório no nível principal.

Respostas

• 200 — Nota emitida
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Nota já emitida, ou não apta para emissão
• 502 — Falha na comunicação com a prefeitura
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/consultar-protocolo

Consultar protocolo de emissão assíncrona · Permissão: nfse:create

Só para notas emitidas no modo: "assincrono" — verifica se a prefeitura já processou e, se sim, grava o resultado (mesmo desfecho de emitir síncrono).

Parâmetros

Respostas

• 200 — Nota atualizada (ainda processando ou já emitida)
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Esta nota não está aguardando protocolo assíncrono
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/emitir-contingencia

Emitir em contingência — EFEITO FISCAL · Permissão: nfse:create

Gera a nota localmente, sem contato com a prefeitura (para quando o webservice está fora do ar). Precisa ser transmitida depois via transmitir-contingencia, dentro do prazo municipal.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: justificativa

Respostas

• 200 — Nota emitida em contingência
• 400 — Justificativa com menos de 15 caracteres
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/transmitir-contingencia

Transmitir nota emitida em contingência — EFEITO FISCAL · Permissão: nfse:create

Parâmetros

Respostas

• 200 — Nota transmitida
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Esta nota não está aguardando transmissão de contingência
• 502 — Falha na comunicação com a prefeitura
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

PUT /nfse/notas/{id}/tomador

Trocar tomador da nota · Permissão: nfse:update

Só antes de enviar à prefeitura (status calculada/conferida/erro). Usado para um pagador avulso (CPF/nome informados na hora).

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: cpf, nome

Respostas

• 200 — Tomador trocado
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Nota já enviada à prefeitura — não pode mais trocar o tomador
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/desistir

Desistir da nota (antes de emitir) · Permissão: nfse:delete

Só para nota ainda não emitida — nota já emitida se cancela, não se desiste.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: motivo

Respostas

• 200 — Nota marcada como desistida
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Nota já emitida ou em outro status incompatível
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/cancelar

Cancelar nota emitida — EFEITO FISCAL · Permissão: nfse:delete

Cancelamento de verdade na prefeitura (padrão nacional com fallback ABRASF).

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: motivo

Respostas

• 200 — Nota cancelada
• 400 — Motivo com menos de 15 caracteres
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Só nota emitida pode ser cancelada
• 502 — Falha na comunicação com a prefeitura
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/substituir

Calcular nota substituindo uma já emitida · Permissão: nfse:create

Calcula uma nota nova reaproveitando os dados da antiga (só sobrescreve o que for enviado no corpo). A antiga só é cancelada de verdade quando a nova emitir com sucesso.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: motivo

Respostas

• 201 — Nova nota calculada
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Só nota emitida pode ser substituída, ou já tem substituta em andamento
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

POST /nfse/notas/{id}/analise-fiscal

Solicitar análise fiscal de cancelamento fora do prazo · Permissão: nfse:delete

Só padrão nacional. O desfecho é assíncrono — a nota fica em analise_fiscal_pendente até a prefeitura decidir.

Parâmetros

Corpo (application/json) — obrigatório

Campos obrigatórios: motivo

Respostas

• 200 — Pedido enviado
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 409 — Só nota emitida no padrão nacional pode solicitar análise fiscal
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}/xml

Baixar XML da NFS-e · Permissão: nfse:read

Não é JSON — Content-Type: application/xml, com Content-Disposition: attachment; filename="NFSe_00001234.xml". Corpo é o XML já assinado, cru.

Parâmetros

Respostas

• 200 — Arquivo XML
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota sem XML (não foi emitida)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}/links

Links oficiais de visualização/autenticidade · Permissão: nfse:read

Sem ?atualizar=1, devolve o que já está gravado (se existir); com ?atualizar=1, reconsulta a prefeitura.

Parâmetros

Respostas

• 200 — Links
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota não encontrada, ou prefeitura não devolveu links
• 409 — Nota ainda não foi emitida
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}/danfse.html

Visualizar DANFSe (HTML) · Permissão: nfse:read

Não é JSON — Content-Type: text/html, sem Content-Disposition (renderizável inline, não é anexo).

Parâmetros

Respostas

• 200 — HTML do DANFSe
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota sem XML (não foi emitida)
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}/danfse.pdf

Baixar DANFSe (PDF) · Permissão: nfse:read

Não é JSON, é binário — Content-Type: application/pdf, Content-Disposition: attachment; filename="NFSe_00001234.pdf".

Parâmetros

Respostas

• 200 — Arquivo PDF
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota sem XML (não foi emitida)
• 500 — PDF indisponível — a mensagem indica o motivo e recomenda usar danfse.html + "salvar como PDF"
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si

GET /nfse/notas/{id}/tentativas

Histórico de tentativas de comunicação com a prefeitura · Permissão: nfse:read

?xml=1 inclui requisição/resposta bruta trocada com a prefeitura (pode ser grande e sensível).

Parâmetros

Respostas

• 200 — Array direto, sem envelope de paginação.
• 401 — Token ausente, inválido, revogado ou expirado
• 403 — A chave não tem a permissão exigida pela rota (devolvida em escopoFaltante)
• 404 — Nota não encontrada
• 503 — Não foi possível validar a chave no momento — falha de rede/indisponibilidade, não problema com a chave em si