Skip to main content

Visão Geral da Integração com a Conta Azul

A integração envia as vendas da clínica (orçamentos pagos) para o ERP Conta Azul. A conexão é feita por OAuth: a clínica autoriza o acesso uma vez, define a conta financeira, a categoria e o vendedor usados em toda venda, e a partir daí os orçamentos são enviados por uma fila, com histórico de cada envio.


Base​

https://api-dev.imagemais.com.br/api/integrations/conta-azul

Todas as rotas exigem autenticação e são isoladas pela conta (accountId) do token, exceto Concluir Autorização, que é pública porque é chamada no retorno do login da Conta Azul.


Conectar a conta​

  1. Verificar a conexão. Se isAuthorized for false, a resposta traz redirectUrl — a página de login da Conta Azul.
  2. Abrir redirectUrl no navegador. Após o login, a Conta Azul redireciona de volta com os parâmetros code e state.
  3. Concluir a autorização enviando code e state. O backend troca o código pelos tokens de acesso.
  4. Salvar as configurações: financialAccountId, categoryId e sellerId (todos obrigatórios), usados em toda venda enviada.

O token é renovado com Renovar Token. Para trocar de conta, Desconectar e repetir o fluxo.

Desconectar é GET

Desconectar Conta usa o método GET e remove a conexão. Não a chame para consultar o estado — para isso existe Verificar Conexão.


Enviar vendas​

RotaQuando usar
Enviar VendaUm orçamento (budgetId). Orçamento já enviado não é reenfileirado
Enviar Vendas em LoteAté 100 orçamentos (budgetIds); a resposta traz o resultado de cada um
Listar EnviosAcompanhar o que foi enviado, paginado. Não devolve o conteúdo enviado, que contém dados do paciente
Reenviar EnvioRepetir um envio que falhou

Os envios são processados em fila, então a resposta de envio confirma o enfileiramento, não a chegada na Conta Azul — acompanhe o resultado em Listar Envios.

Estados de um envio

ValorQuando
PENDINGNa fila, aguardando processamento
SENTVenda registrada na Conta Azul
FAILEDO envio falhou — pode ser reenviado
Limites do reenvio

Um envio já concluído não pode ser reenviado, porque duplicaria a venda ("Envio já concluído — reenviar duplicaria a venda na Conta Azul"). E só dentro do mês do movimento: passada a competência, o acerto deve ser feito direto na Conta Azul ("Movimento de competência já encerrada; o reenvio precisa ser feito na Conta Azul").


Rotas​

MétodoRotaPermissãoDescrição
GET/integrations/conta-azul/check-access-token—Estado da conexão e URL de autorização
POST/integrations/conta-azul/authorizepúblicaConclui a autorização OAuth
POST/integrations/conta-azul/renew-access-token—Renova o token
GET/integrations/conta-azul/disconnect—Desconecta a conta
GET/integrations/conta-azul/settings—Configurações padrão
POST/integrations/conta-azul/settings—Salva as configurações
POST/integrations/conta-azul/saleread_movementsEnvia a venda de um orçamento
POST/integrations/conta-azul/deliveries/batchread_movementsEnvia vários orçamentos
GET/integrations/conta-azul/deliveriesread_movementsLista os envios
POST/integrations/conta-azul/deliveries/{id}/retryread_movementsReenvia um envio com falha

"—" na coluna de permissão: a rota não exige permissão específica, apenas autenticação.

Envio em lote, listagem e reenvio

As rotas /deliveries estão na develop e ainda não foram publicadas em produção.