Prestador (Parceiro)

API máquina-a-máquina para o sistema do prestador confirmar a execução de agendamentos.

Visão Geral

Um prestador de serviços de saúde (clínica, laboratório) cadastrado no portal pode integrar o próprio sistema à Avizuaí para confirmar automaticamente a execução dos agendamentos — marcando cada um como REALIZADO ou FALTOU.

Esta API é server-to-server (não usa login de usuário) e é autenticada por uma credencial de API do prestador (chave nbwp_).

Base URL: /api/external/prestador/v1

Esta API de parceiro expõe apenas o registro de execução — não há endpoint de listagem de agendamentos por aqui. O sistema do prestador é notificado dos agendamentos por webhook (modelo push) e responde confirmando a execução. Veja abaixo.

Fluxo de integração

O prestador cadastra, no Portal do Prestador, um webhook apontando para uma URL do próprio sistema e gera uma credencial nbwp_.
A Avizuaí envia eventos de agendamento para essa URL (agendamento confirmado, cancelado, realizado, faltou).
Ao atender o paciente, o sistema do prestador chama POST /execucao confirmando o desfecho (REALIZADO ou FALTOU).

Como receber os agendamentos (webhooks)

Os agendamentos chegam ao seu sistema por webhook — configurado no Portal do Prestador (seção Webhooks). Você informa a URL de destino e um segredo; a Avizuaí assina cada entrega com HMAC-SHA256 para você validar a autenticidade.

Eventos de agendamento disponíveis:

Evento	Quando
`AGENDAMENTO_CONFIRMADO`	O paciente confirmou o comparecimento
`AGENDAMENTO_CANCELADO`	O agendamento foi cancelado
`AGENDAMENTO_REALIZADO`	Execução registrada como realizada
`AGENDAMENTO_FALTOU`	Execução registrada como falta

A entrega, o cabeçalho de assinatura e o formato do payload seguem o mesmo padrão de webhooks da plataforma — ver Webhooks. O sistema do prestador usa esses eventos para saber quais agendamentos existem e, então, confirma a execução pelo endpoint abaixo.

Autenticação

As requisições são autenticadas por dois headers, validados contra a credencial cadastrada:

Header	Descrição
`X-Api-Key`	Chave pública da credencial, com prefixo `nbwp_`
`X-Api-Secret`	Segredo da credencial (exibido apenas uma vez na criação/regeneração)

A credencial nbwp_ é gerada pelo prestador no Portal do Prestador (seção Credenciais). O segredo é mostrado uma única vez — guarde-o com segurança. A credencial pode ter allowlist de IP e limite de requisições por minuto. Se perder o segredo, regenere (o anterior deixa de valer).

Registrar Execução

POST

/api/external/prestador/v1/execucao

Marca um agendamento como REALIZADO ou FALTOU. O agendamento é resolvido por agendamentoId ou por numeroPedido, sempre dentro do escopo do prestador autenticado.

Campo	Tipo	Obrigatório	Descrição
`agendamentoId`	`number`	Condicional	ID do agendamento na Avizuaí. Informe este ou `numeroPedido`.
`numeroPedido`	`string`	Condicional	Número do pedido do legado. Alternativa ao `agendamentoId`.
`resultado`	`string`	Obrigatório	`REALIZADO` ou `FALTOU`
`observacao`	`string`	Opcional	Observação livre registrada na execução

Header opcional de idempotência:

Header	Descrição
`Idempotency-Key`	Chave única da operação. Reenvios com a mesma chave não reprocessam — devolvem o resultado original (`status: "replay"`).

# Confirmar que o agendamento foi realizado
curl -X POST https://api.avizuai.com.br/api/external/prestador/v1/execucao \
  -H "X-Api-Key: nbwp_sua-chave" \
  -H "X-Api-Secret: seu-segredo" \
  -H "Idempotency-Key: 5f2c-2026-000123" \
  -H "Content-Type: application/json" \
  -d '{
    "numeroPedido": "PED-2026-0042",
    "resultado": "REALIZADO",
    "observacao": "Paciente compareceu no horário."
  }'

Resposta de sucesso (200):

{
  "status": "ok",
  "agendamentoId": 1234,
  "resultado": "REALIZADO"
}

Reenvio idempotente (mesma Idempotency-Key) — 200:

{
  "status": "replay",
  "agendamentoId": 1234,
  "resultado": "REALIZADO"
}

Códigos de Retorno

Status	Quando
`200 OK`	Execução registrada (`status: ok`) ou replay idempotente (`status: replay`)
`400 Bad Request`	`resultado` ausente/ inválido ou nenhum identificador informado
`401 Unauthorized`	Chave/segredo inválidos, IP fora da allowlist ou credencial inativa
`404 Not Found`	Agendamento não encontrado no escopo do prestador
`409 Conflict`	Transição inválida (agendamento já encerrado)

O escopo (município/aplicação e prestador) é derivado da própria credencial — não é enviado no corpo. Cada prestador só enxerga e altera os próprios agendamentos.

Próximos Passos

📅 Agendamentos 🔌 Webhooks ⚠ Códigos de Erro