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
- Verificar a conexão. Se
isAuthorizedforfalse, a resposta trazredirectUrl— a página de login da Conta Azul. - Abrir
redirectUrlno navegador. Após o login, a Conta Azul redireciona de volta com os parâmetroscodeestate. - Concluir a autorização enviando
codeestate. O backend troca o código pelos tokens de acesso. - Salvar as configurações:
financialAccountId,categoryIdesellerId(todos obrigatórios), usados em toda venda enviada.
O token é renovado com Renovar Token. Para trocar de conta, Desconectar e repetir o fluxo.
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
| Rota | Quando usar |
|---|---|
| Enviar Venda | Um orçamento (budgetId). Orçamento já enviado não é reenfileirado |
| Enviar Vendas em Lote | Até 100 orçamentos (budgetIds); a resposta traz o resultado de cada um |
| Listar Envios | Acompanhar o que foi enviado, paginado. Não devolve o conteúdo enviado, que contém dados do paciente |
| Reenviar Envio | Repetir 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
| Valor | Quando |
|---|---|
PENDING | Na fila, aguardando processamento |
SENT | Venda registrada na Conta Azul |
FAILED | O envio falhou — pode ser reenviado |
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étodo | Rota | Permissão | Descrição |
|---|---|---|---|
GET | /integrations/conta-azul/check-access-token | — | Estado da conexão e URL de autorização |
POST | /integrations/conta-azul/authorize | pública | Conclui 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/sale | read_movements | Envia a venda de um orçamento |
POST | /integrations/conta-azul/deliveries/batch | read_movements | Envia vários orçamentos |
GET | /integrations/conta-azul/deliveries | read_movements | Lista os envios |
POST | /integrations/conta-azul/deliveries/{id}/retry | read_movements | Reenvia um envio com falha |
"—" na coluna de permissão: a rota não exige permissão específica, apenas autenticação.
As rotas /deliveries estão na develop e ainda não foram publicadas em produção.