RECURSO DE API

Cobrança e Finanças

Fatura, cobrança idempotente, saldo corrente, conciliação de fechamento de dia e e-Fatura. O valor monetário é armazenado como numeric(14,2); o saldo corrente é derivado, não é gravado manualmente.

Acesso Antecipado Toda a API

Endpoints

12 endpoint

Endpoints deste recurso. Cada endpoint é limitado aos dados da clínica à qual a chave de API está vinculada; os endpoints de gravação suportam o cabeçalho Idempotency-Key.

POST /v1/invoices Cria uma fatura admin · secretário · médico

GET /v1/invoices Lista as faturas admin

GET /v1/invoices/{id} Obtém os detalhes da fatura Todos os papéis autorizados

POST /v1/invoices/{id}/void Cancela a fatura (lançamento reverso) admin

POST /v1/invoices/{id}/einvoice Envia a fatura como e-Fatura (GİB) admin

GET /v1/einvoices Lista os registros de e-Fatura admin

POST /v1/payments Registra uma cobrança (idempotente) admin · secretário · médico

GET /v1/patients/{id}/balance Obtém o saldo corrente do paciente Todos os papéis autorizados

GET /v1/patients/{id}/ledger Lista os movimentos de conta-corrente do paciente Todos os papéis autorizados

GET /v1/cash/day Obtém o resumo de caixa do fechamento de dia admin · secretário

GET /v1/cari Lista os saldos correntes (conta-corrente) admin · secretário

GET /v1/billing/summary Obtém o resumo financeiro/de cobranças admin · secretário

Exemplo de Uso

Registrar cobrança (idempotente)

Requisição

curl -X POST https://api.udentiva.com/v1/payments \
  -H "Authorization: Bearer udk_live_xxx" \
  -H "Idempotency-Key: pay-7c3f..." \
  -H "Content-Type: application/json" \
  -d '{"patient_id":"c0ffee00-...","amount":"1500.00","method":"card"}'

Resposta

HTTP/1.1 201 Created
{
  "id": "pmt-9001",
  "amount": "1500.00",
  "method": "card",
  "created_at": "2026-06-24T09:15:00Z"
}

# Aynı Idempotency-Key ile tekrar → aynı kayıt döner, ikinci tahsilat OLUŞMAZ.

Segurança neste recurso

Segurança não é um recurso, é a própria arquitetura. As garantias que se aplicam a este recurso:

Cobrança idempotente: graças à Idempotency-Key + bloqueio no servidor, mesmo em uma repetição de rede o mesmo pagamento não é registrado duas vezes (sem cobrança dupla).

O valor monetário é sempre numeric(14,2); não se faz aritmética com o valor vindo do cliente, o arredondamento ocorre em um único ponto no servidor.

Cancelamento/reembolso = lançamento reverso (void/refund); a linha não é fisicamente excluída. O saldo corrente é derivado como Σfatura − Σpagamento.

A operação multi-entidade (fatura + item + pagamento) é atômica em uma única transaction: ou tudo ou nada.

Todo o modelo de segurança →

Formato de Erro

Os erros retornam em um envelope consistente; o código é destinado à máquina, a mensagem ao usuário. Erro interno/stack nunca é vazado.

{
  "error": {
    "code": "validation_failed",
    "message": "Campo inválido: e-mail"
  }
}

Outros Recursos

Pacientes Agendamentos e calendário Odontograma & Tratamento Estoque Imagem Laboratório Lead & CRM Turismo de saúde Relatórios & BI Webhooks Transferência de Dados (Export API)

Deseja acesso antecipado?

Seja o primeiro a saber quando a API for lançada.

Entre em Contato