API de Agenda

Comece aqui

Com esta API, um sistema parceiro (secretária virtual, aplicativo, totem, portal) busca e cadastra pacientes, consulta horários vagos e marca, remarca, desmarca e confirma atendimentos na agenda da clínica. São 12 operações, todas em JSON sobre HTTPS.

1. Receba seus dados de acesso

   No credenciamento, a ATOS entrega a chave de acesso e o código da clínica (codClienteSSN) de cada ambiente. A chave de homologação só funciona na clínica de teste e a de produção só na clínica real, então um teste nunca atinge a agenda verdadeira por engano.

   Ambiente	Endereço	Para que serve
   Homologação	https://ws2ssn.sistemaatosclinicas.com	Clínica de teste. Marque, desmarque e cadastre à vontade.
   Produção	https://ws.sistemaatosclinicas.com	A agenda real da clínica. Liberada depois da homologação.

2. Preencha seus dados aqui

   Todos os exemplos desta página se ajustam ao que você digitar, prontos para copiar. O que você digita fica só nesta aba do navegador: nada é salvo nem enviado.

   Ambiente

   Homologação Produção

   Código da clínica

   O codClienteSSN recebido.

   Chave de acesso

   Vai no cabeçalho X-Api-Key. Guarde fora do código-fonte.

3. Faça a primeira chamada

   Cole no terminal. Se voltar a lista de convênios da clínica, está tudo certo.

   Deu 401? A chave está errada ou faltando. Deu 403? A chave não é deste ambiente ou deste código de clínica.

Como funciona

A agenda de cada profissional é uma grade de horários que a clínica abre com antecedência. Agendar é ocupar um horário vago dessa grade: não dá para marcar num horário que a clínica não abriu, mesmo com o profissional livre. Por isso o caminho é sempre consultar os horários livres e agendar em um deles.

Guarde o agendamentoId: Remarcar, Desmarcar e Confirmar usam ele.

Um atendimento do começo ao fim

1. Identificar o paciente. BuscarPaciente pelo celular. Sem cadastro, crie com CriarPaciente, ou direto no Agendar.

2. Carregar o catálogo. ListarProfissionais uma vez por dia basta. Guarde os identificadores do seu lado.

3. Oferecer horários. HorariosLivres por especialidade devolve as vagas de todos os profissionais numa chamada. Aqui entram as suas regras (convênio, preferências) para filtrar o que oferecer.

4. Marcar. Agendar numa das vagas e guardar o agendamentoId.

5. Acompanhar. Confirmar quando o paciente confirmar presença. Remarcar ou Desmarcar quando ele pedir.

6. Conferir antes de falar com o paciente. A recepção também mexe na agenda. Antes de mandar lembrete ou pedir confirmação, consulte AgendaDoPaciente: ela sempre mostra o estado atual.

Regras importantes

Como os erros voltam

Todo erro traz o código HTTP e um corpo neste formato:

{ "erro": "HORARIO_INDISPONIVEL",
  "mensagem": "Não há horário vago na agenda deste profissional nesta data e hora." }

Decida o que fazer pelo campo erro, que não muda. A mensagem é para log ou para adaptar ao usuário e pode mudar de redação. A lista completa está em Todos os erros.

Repetir uma chamada que ficou sem resposta

• Confirmar, Desmarcar e Remarcar podem ser repetidos sem risco. Se já estiver feito, a resposta é 200 com jaEstavaConfirmado, jaEstavaDesmarcado ou jaEstavaRemarcado igual a true.
• Agendar: antes de repetir, consulte AgendaDoPaciente para ver se o primeiro pedido já entrou. Repetir o mesmo horário normalmente devolve 409 HORARIO_INDISPONIVEL, porque a vaga já é do seu próprio agendamento.

Limite de chamadas

60 chamadas por minuto por chave. Acima disso volta 429 LIMITE_DE_CHAMADAS: espere alguns segundos e repita. Se precisar de mais, peça ajuste à ATOS.

Todo 200 de uma operação que altera a agenda só sai depois que a API relê o banco e confirma a mudança. Ela já aparece na tela da clínica.

Status do atendimento

Use o campo status (texto). O statusCodigo acompanha para os estados auxiliares.

Todos os erros

Referência única para programar o tratamento de erros. Cada operação lista também os seus.

Chamada sem codClienteSSN no endereço volta 404 com uma mensagem padrão do servidor, sem o campo erro.

Roteiro de homologação

Faça no ambiente de homologação, com a chave e o código de teste. Terminado o roteiro, a ATOS libera a chave de produção.

1. Segurança. Qualquer chamada sem X-Api-Key deve voltar 401. Com a chave de homologação apontando para outro código de clínica, 403.

2. Catálogo. ListarProfissionais e ListarConvenios carregam. Anote um profissionalId, um especialidadeId e o tipoDeEventoId dele.

3. Paciente. CriarPaciente com um celular de teste e, em seguida, BuscarPaciente com o mesmo número com 55 e com máscara: deve achar o mesmo id. Criar de novo devolve jaExistia: true.

4. Horários. HorariosLivres por profissional e por especialidade, com e sem turno.

5. Agendar. Numa vaga do passo anterior. Repetir a mesma chamada deve dar 409 HORARIO_INDISPONIVEL.

6. Ciclo. Confirmar, Remarcar e Desmarcar o mesmo agendamentoId, conferindo AgendaDoPaciente entre um passo e outro. Repita Confirmar e Desmarcar e confira os jaEstava….

7. Bordas. Hora "14" dá 400. Data passada e horário abaixo da antecedência mínima dão 422. Remarcar um agendamento desmarcado dá 409. Mais de 31 dias em HorariosLivres dá 400.

8. Mudanças e relatório. MudancasDesde com desde e, em seguida, com o proximoDesdeId recebido: as duas voltam 200. Os agendamentos feitos pela API não aparecem aqui (veja a operação). Relatorio dos últimos 30 dias volta 200.

O que fica com o parceiro

A API cuida de paciente, vaga na grade, antecedência mínima, limite de agendamentos por dia e limite de dias à frente. Estas regras não existem no Sistema ATOS e precisam ficar do seu lado:

• Convênio aceito por profissional. O sistema guarda o convênio do paciente e a lista de convênios da clínica, mas não quem aceita o quê.
• Pré-requisitos, como exigir avaliação antes de liberar sessões. Dá para calcular pelo histórico de AgendaDoPaciente.
• Hora marcada ou ordem de chegada por profissional. Para ordem de chegada, marque num horário ainda futuro da janela do dia; a recepção organiza a fila quando o paciente chega.
• Políticas de conversa: tolerância de atraso, prazo para cancelar, texto das mensagens.

Rotas da API fora de /api/IntegracaoAgenda/ são de uso interno da ATOS, podem mudar sem aviso e não devem ser usadas por parceiros.