Developer Hub / API (A7)

referência de integração developer hub aura · omnichannel inteligente · central it tecnologia da informação s/a · agosto de 2026 para quem é este documento para a equipe técnica que vai conectar um sistema ao aura iniciar um atendimento a partir de outro sistema, receber mensagens por webhook, incorporar o chat num site ou fazer o aura consultar uma base externa tudo aqui é feito para integração externa as rotas de administração do console não estão documentadas por decisão de projeto são internas, mudam sem aviso e não fazem parte do contrato de integração o objetivo é você fazer a primeira chamada funcionar em menos de dez minutos, sem precisar falar com ninguém conteúdo 1 #sec0 primeiros passos #sec0 7 #sec6 incorporar o chat no site #sec6 2 #sec1 ambientes e urls #sec1 8 #sec7 conectar seus sistemas #sec7 3 #sec2 autenticação #sec2 9 #sec8 códigos de erro #sec8 4 #sec3 iniciar um atendimento #sec3 10 #sec9 limites e desempenho #sec9 5 #sec4 consultar, atualizar e encerrar #sec4 11 #sec10 versionamento e mudanças #sec10 6 #sec5 receber mensagens por webhook #sec5 1\ primeiros passos o caminho mais curto até a primeira chamada bem sucedida cinco passos, e nenhum depende de suporte passo o que acontece 1 peça a chave de integração o administrador do workspace gera em administração › integrações a chave e o segredo aparecem uma única vez e não são recuperáveis depois 2 peça a rota a rota é um identificador curto que aponta para um ponto específico do fluxo de atendimento exemplo segunda via, agendamento 3 consulte o contrato o próprio aura devolve o contrato pronto da rota, com url, cabeçalhos, corpo esperado e um exemplo de chamada 4 assine o corpo toda chamada que altera estado exige assinatura hmac sha256 do corpo sem ela a requisição é recusada 5 chame e confirme a resposta traz o identificador da sessão consulte o estado dela para confirmar que a conversa foi criada 1 1 peça o contrato pronto antes de escrever código, peça ao administrador do workspace que consulte o contrato da rota no console a plataforma monta o contrato sozinha, com a url exata, os cabeçalhos, o corpo esperado e um exemplo de chamada isso evita divergência entre o que está escrito e o que a api aceita de fato 1 2 sua primeira chamada curl x post 'https //seu dominio/api/flow/segunda via/sessions' \ h 'x api key \<sua chave>' \ h 'x signature \<hmac sha256 do corpo>' \ h 'content type application/json' \ d '{"telefone" "+5511999999999","protocolo" "proto 123"}' resposta esperada, com código 202 { "session id" "9f2c ", "conversa id" null, "estado" "armada", "protocolo" "proto 123", "telefone" "+5511999999999", "modo" "armar", "aviso" "sessão armada — inicia quando o cidadão enviar a 1ª mensagem" } 2\ ambientes e urls ambiente para quê base homologação desenvolver e testar a integração informada na contratação produção operação real informada na contratação cada workspace tem a própria base a url não é a mesma entre clientes, e por isso este documento usa seu dominio como marcador o contrato da rota devolve a url correta já preenchida comece sempre por homologação a chave de homologação é distinta da de produção e não vale no outro ambiente uma sessão criada em homologação abre conversa de verdade no workspace de teste, então use um número de telefone controlado 3\ autenticação a plataforma usa dois mecanismos combinados uma chave que identifica o workspace e uma assinatura que prova que o corpo não foi alterado no caminho cabeçalho o que é x api key identifica o workspace é por ela que a plataforma sabe em qual base gravar obrigatória em todas as chamadas x signature hmac sha256 do corpo da requisição, em hexadecimal, usando o segredo da chave obrigatória em toda chamada que altera estado criar, atualizar e encerrar sessão o prefixo sha256= é aceito e ignorado, e a comparação não diferencia maiúsculas de minúsculas idempotency key opcional evita que uma repetição da mesma chamada crie duas conversas se ausente, o campo protocolo cumpre o mesmo papel 3 1 como calcular a assinatura a assinatura é calculada sobre os bytes exatos do corpo enviado, não sobre o objeto antes de serializar se você serializar duas vezes com formatação diferente, a assinatura não confere import hmac, hashlib, json, requests corpo = json dumps({"telefone" "+5511999999999", "protocolo" "proto 123"}) encode() assinatura = hmac new(segredo encode(), corpo, hashlib sha256) hexdigest() requests post(url, data=corpo, headers={ "x api key" chave, "x signature" assinatura, "content type" "application/json"}) formatos de assinatura aceitos as três formas abaixo são equivalentes e todas passam na verificação a1b2c3… · sha256=a1b2c3… · a1b2c3… em maiúsculas isso facilita reaproveitar código de integração escrito para outros provedores, que costumam usar o prefixo a chave aparece uma vez só no momento em que o administrador gera a chave, a plataforma devolve a chave e o segredo depois disso, o segredo não é recuperável por nenhum caminho se perder, gere outra guarde o segredo em cofre de credenciais, nunca em código versionado ele autoriza abrir atendimento em nome do workspace 4\ iniciar um atendimento é o endpoint principal do aura para integração um sistema externo — uma unidade de resposta audível, um portal, um sistema de protocolo — inicia um atendimento já com as informações que ele conhece post /api/flow/ /sessions 4 1 corpo da requisição campo obrigatório descrição telefone sim formato internacional e 164, com o código do país exemplo +5511999999999 número fora do padrão é recusado protocolo não identificador do atendimento no seu sistema serve também como chave de idempotência repetir o mesmo protocolo devolve a sessão existente em vez de abrir outra conversa modo não armar (padrão) ou proativo ver 4 2 variaveis não pares de chave e valor que entram no contexto da conversa e ficam disponíveis no fluxo a rota pode exigir determinadas variáveis telefone e protocolo já entram como variáveis não é preciso repetir os dois dentro de variaveis a plataforma injeta telefone e protocolo no contexto do fluxo automaticamente, e eles contam como variável obrigatória atendida quando a rota os exigir se você enviar o mesmo nome dentro de variaveis, o valor do campo do topo prevalece 4 2 os dois modos modo como funciona armar prepara o contexto e espera a conversa só começa quando a pessoa enviar a primeira mensagem pelo canal é o padrão, e o mais previsível nada é enviado até que haja interesse do outro lado proativo a plataforma inicia a conversa exige um canal ativo no assistente fora da janela de 24 horas do whatsapp, a primeira mensagem precisa ser um modelo aprovado — é regra do provedor, não da plataforma 4 3 o que a chamada faz com uma conversa em andamento a chamada tem prioridade uma sessão armada move a conversa mesmo que a pessoa esteja no meio de um formulário, e o que ela tiver escrito antes do salto é descartado para não virar resposta do passo novo a única recusa é atendimento humano se a conversa estiver com um atendente, a chamada é recusada com código 409 nos dois modos a plataforma não rouba a conversa de quem está atendendo trate o 409 como situação normal do fluxo, não como erro de integração significa que uma pessoa já está cuidando do caso 4 4 respostas código significado o que fazer 202 sessão criada guarde o session id em modo armar, a conversa começa quando a pessoa escrever 200 sessão já existia a mesma chave de idempotência foi usada antes a resposta traz idempotente true não é erro 409 conversa em atendimento humano não repita imediatamente aguarde ou trate no seu processo 422 dado inválido ou variável faltando a mensagem indica qual corrija e reenvie 5\ consultar, atualizar e encerrar depois de criar a sessão, três operações acompanham o ciclo de vida dela 5 1 consultar o estado get /api/flow/sessions/ x api key \<sua chave> não exige assinatura, porque não altera nada devolve o estado atual e o identificador da conversa, quando ela já tiver sido criada estado o que significa armada a sessão está preparada e aguarda a pessoa enviar a primeira mensagem ativa a conversa foi posicionada no ponto do fluxo e está em andamento expirada passou da validade sem ser consumida não vai mais iniciar conversa nenhuma crie outra sessão encerrada encerrada pelo seu sistema não reabre a sessão vencida não some consultar uma sessão vencida devolve 200 com estado expirada, não 404 a sessão continua no banco como rastro da chamada, mas deixa de ser elegível para iniciar conversa trate expirada como estado final seu sistema não deve ficar aguardando uma sessão nesse estado 5 2 acrescentar informação ao contexto patch /api/flow/sessions/ {"variaveis" {"status pedido" "aprovado"}} as variáveis enviadas são mescladas com as existentes, não substituem o conjunto serve para o caso em que o seu sistema descobre algo depois de a sessão já ter sido criada 5 3 encerrar delete /api/flow/sessions/ encerra a sessão ela não reabre para começar de novo, crie outra 5 4 respostas das três operações código quando o que fazer 200 operação concluída consultar devolve o estado atual atualizar devolve as variáveis já mescladas encerrar devolve a sessão como encerrada 401 chave ausente ou inválida, ou assinatura incorreta atualizar e encerrar exigem assinatura do corpo consultar não exige 404 sessão inexistente vale para consultar, atualizar e encerrar confira o identificador sessão que existe mas venceu devolve 200 com estado expirada, não 404 422 variável com nome reservado, na atualização a mensagem lista quais nomes foram recusados ver 5 5 5 5 nomes de variável reservados dois grupos de nomes são recusados com código 422 a mensagem de erro lista quais foram rejeitados grupo nomes começam com sublinhado qualquer nome iniciado por é controle do motor sobrescrevê los permitiria pular etapas de autenticação do fluxo estruturas do motor api · contato · canal · canal familia · canal de acesso · canal de acesso nome · identificador · pagina · dispositivo se a sua informação tem um desses nomes, use um prefixo do seu sistema por exemplo, no lugar de contato, use origem contato a rota pode ser desativada sem aviso ao integrador quando a equipe de atendimento republica o fluxo e o ponto que originou a rota deixou de existir, a rota é desativada automaticamente e passa a devolver 404 isso protege contra rota órfã aceitando chamada para um ponto que não existe mais combine com a equipe do workspace que mudanças no fluxo precisam considerar as integrações ativas 6\ receber mensagens por webhook este é o caminho oposto o provedor do canal entrega mensagens para a plataforma se você é o provedor, ou está construindo um canal próprio, é aqui que a mensagem entra post /webhook/ / get /webhook/ / o get existe para o handshake de verificação que alguns provedores exigem antes de começar a entregar a plataforma devolve o desafio em texto puro quando o token confere 6 1 verificação da origem a plataforma aceita dois mecanismos, e pelo menos um precisa estar configurado no canal mecanismo como funciona assinatura nativa quando o provedor assina o corpo, a plataforma valida com o segredo do canal é o caso de whatsapp, telegram e teams segredo compartilhado para provedores sem assinatura própria o operador define um segredo no canal e o envia no cabeçalho x webhook secret ou como parâmetro na url quando o modo estrito está ligado, canal que não pode ser verificado por nenhum dos dois recebe 401 e a mensagem não entra 6 2 resposta { "status" "ok", "aceitos" 1, "duplicados" 0, "sem canal" 0, "sem fluxo" 0 } contador o que significa aceitos mensagens que entraram na fila de processamento duplicados já recebidas antes, identificadas pelo identificador externo a plataforma é idempotente na entrada reentrega não duplica conversa sem canal não foi possível resolver o canal de destino confira o identificador do canal sem fluxo o canal existe mas não tem fluxo publicado se nada foi aceito por esse motivo, a plataforma devolve 409 para o provedor reentregar depois 7\ incorporar o chat no site o widget é um arquivo javascript puro, sem dependência de framework e sem etapa de build ele baixa a própria aparência da plataforma e monta a interface em tempo de execução \<script src="https //seu dominio/widget js" data tenant="\<id do workspace>" data channel="\<id do canal>">\</script> a aparência — cores, textos, saudação, convite, botão de histórico — é configurada no console, em canais, e não no código do site isso permite que a equipe de atendimento ajuste sem depender de publicação no seu site 7 1 o que o widget entrega conversa com anexo, áudio gravado no navegador e emoji chamada de voz e vídeo com o atendente, quando a fila permite histórico das conversas anteriores da própria pessoa, com download em pacote continuidade após atualizar a página, sem repetir a saudação 7 2 os endpoints internos do widget não são interface de integração ao inspecionar o navegador, você vai ver o widget chamando endpoints próprios para enviar mensagem, carregar histórico e receber entrega em tempo real eles são internos do canal e não fazem parte do contrato deste documento o motivo é de segurança, e é a mesma razão pela qual eles não estão documentados aqui nesse canal a identidade da pessoa é um valor gerado pelo próprio navegador, sem sessão assinada pelo servidor o widget cuida disso sozinho, mas um sistema externo que reutilizasse esses endpoints estaria construindo sobre uma superfície que ainda não tem autenticação forte se você precisa de acesso programático à conversa use o bot como api, descrito nas seções 4 e 5 ele tem chave, assinatura e idempotência, e é o caminho suportado para um sistema externo interagir com um atendimento se o seu caso não couber ali, fale com a central it antes de construir sobre um endpoint do widget identidade da pessoa no widget sem login, o widget identifica a pessoa por um valor aleatório guardado no navegador é suficiente para continuidade da conversa, mas não é autenticação quando o caso exigir identidade confirmada, use o passo de autenticação dentro do fluxo código por e mail ou provedor de identidade, incluindo gov br 8\ conectar seus sistemas o caminho inverso o fluxo de atendimento consulta ou alimenta um sistema seu no meio da conversa consultar um protocolo, abrir um chamado, verificar um cadastro forma quando usar integração cadastrada o administrador cadastra a conexão uma vez, com credenciais cifradas, e o fluxo passa a usar sem configurar chamada em cada ponto é o caminho recomendado chamada http direta para um caso pontual que não justifica cadastro o nó do fluxo monta a chamada, e os campos da resposta ficam disponíveis como variáveis servidor mcp para expor um conjunto de ferramentas ao assistente em vez de uma chamada por vez o fluxo aciona o servidor e o assistente escolhe a ferramenta conforme a conversa existe conexão nativa com citsmart, agility e glpi no glpi basta a credencial de acesso para abertura de chamado para os demais sistemas, a conexão é configurada com endereço e credencial, e a plataforma testa antes de salvar como as credenciais são tratadas credencial de integração é cifrada em repouso e nunca volta em nenhuma resposta da api a plataforma devolve apenas quais campos estão preenchidos, para o formulário de edição saber o que já foi salvo há uma proteção adicional se alguém alterar o endereço de destino de uma integração existente, os segredos guardados não são reenviados para o endereço novo isso impede que uma credencial seja extraída apontando a integração para outro servidor 9\ códigos de erro 9 1 formato da resposta de erro todo erro devolve o mesmo envelope, para o seu código tratar de forma uniforme sem depender de texto solto { "erro" { "codigo" 422, "mensagem" "telefone inválido — informe em formato internacional (e 164)" } } em falha de validação de formato, o envelope traz um campo adicional detalhe com a lista de campos que falharam, para você corrigir todos de uma vez em vez de descobrir um por chamada { "erro" { "codigo" 422, "mensagem" "validação falhou", "detalhe" \[ { "loc" \["body","telefone"], "msg" " " } ] } } 9 2 códigos código causa o que fazer 400 corpo malformado o json não pôde ser lido, ou não é um objeto confira a serialização 401 chave ausente ou inválida verifique o cabeçalho x api key e se a chave é do ambiente certo 401 assinatura inválida o hmac não confere com o corpo assine os bytes exatos enviados, não o objeto antes de serializar 403 acesso fora do workspace a chave não tem permissão sobre o recurso pedido confira se está usando a chave do workspace correto 404 rota inexistente ou inativa o identificador da rota não existe no workspace, ou foi desativado 404 sessão inexistente o identificador não existe sessão vencida não devolve 404 devolve 200 com estado expirada 409 conversa em atendimento humano situação esperada aguarde ou trate no seu processo 422 telefone inválido use o formato internacional e 164, com código do país 422 variável obrigatória ausente a rota exige variáveis específicas a mensagem lista quais faltaram 422 nome de variável reservado nome começando com sublinhado, ou coincidente com estrutura do motor 9 3 como tratar cada família família tratamento recomendado 4xx de validação não repita a mesma chamada ela vai falhar de novo corrija o dado e reenvie 401 não repita é configuração, não intermitência 409 repita mais tarde, com espera a conversa pode sair do atendimento humano 5xx repita com espera crescente entre as tentativas use a chave de idempotência para não duplicar conversa 10\ limites e desempenho a plataforma não aplica cota por chave de integração o que existe são limites operacionais e de contrato, que valem a pena conhecer antes de dimensionar a integração item comportamento validade da sessão 24 horas por padrão depois disso a sessão passa a ser reportada como expirada e não inicia mais conversa crie outra idempotência repetir a mesma chave dentro da validade devolve a sessão existente, não cria outra reentrega de webhook mensagem já recebida é contabilizada como duplicada e ignorada pode reentregar sem medo de duplicar conversa tempo de resposta da plataforma a criação de sessão responde rápido porque o processamento da conversa é assíncrono não aguarde a resposta do atendimento na mesma chamada volume contratado o volume de atendimento é dimensionado em contrato consumo acima do contratado é tratado comercialmente, não bloqueado tecnicamente 10 1 como identificar a chave em uso a chave começa com ak e o console mostra os primeiros nove caracteres serve para confirmar qual chave está configurada em cada sistema, sem expor o restante 10 2 onde ver o que a sua integração enviou toda chamada recebida vira registro no workspace, aceita ou recusada, com o corpo enviado, o código de resposta e o resultado o administrador consulta isso no console use o registro antes de abrir chamado quando uma chamada não produz o efeito esperado, o registro mostra exatamente o que chegou e por que foi recusada na maioria dos casos a causa é visível ali telefone fora do padrão, variável faltando, ou conversa já em atendimento humano chamada recusada por chave inválida é a única que não aparece sem chave válida a plataforma não sabe em qual workspace registrar uma recomendação de arquitetura não trate a criação de sessão como chamada síncrona que devolve o resultado do atendimento ela devolve que a sessão foi criada o acompanhamento do que aconteceu depois é feito consultando a sessão, ou pelos relatórios da plataforma integração que espera resposta imediata do atendimento vai bloquear 10 3 endpoints de saúde para monitoramento da integração em produção, dois endpoints respondem sem autenticação endpoint o que responde get /health devolve 200 e status ok quando o serviço está de pé é barato e não consulta dependência serve para verificação de disponibilidade do processo get /health/ready verifica banco de dados e fila devolve 200 com status ok, ou 503 com status degraded e o detalhe de qual dependência falhou é o que indica se a plataforma consegue de fato processar { "status" "ok", "checks" { "db" "ok", "redis" "ok", "minio" "ok" } } 11\ versionamento e mudanças os endpoints deste documento fazem parte do contrato de integração e não mudam de forma incompatível sem aviso mudança incompatível significa remover campo, mudar tipo, mudar o significado de um código de resposta ou tornar obrigatório um campo que era opcional tipo de mudança como acontece campo novo na resposta pode acontecer a qualquer momento sua integração deve ignorar campos que não conhece endpoint novo pode acontecer a qualquer momento não afeta o que já existe mudança incompatível comunicada com antecedência ao contato técnico registrado no contrato, com prazo para adequação rotas do console não fazem parte deste contrato e mudam sem aviso não construa integração sobre elas 11 1 especificação legível por máquina a plataforma não publica a especificação técnica da api em homologação nem em produção é decisão de segurança a especificação lista todos os endpoints do sistema, inclusive os internos do console, e serviria de mapa para reconhecimento se a sua ferramenta de integração precisa de um esquema, peça à central it a especificação apenas dos endpoints deste documento 11 2 acompanhar o atendimento a plataforma recebe webhooks dos canais, mas não envia notificação de volta ao seu sistema quando o atendimento avança para acompanhar, consulte a sessão, ou combine com a equipe do workspace um passo no próprio fluxo que chame um endereço seu no momento que interessa o que não documentamos, e por quê a plataforma tem muitos outros endpoints, usados pelo console de atendimento eles não estão aqui de propósito são internos, mudam junto com a interface e não têm garantia de estabilidade se a sua integração precisa de algo que não está neste documento, fale com a central it antes de construir sobre uma rota interna provavelmente existe um caminho suportado, e se não existir, ele pode entrar no contrato documento técnico da central it endereços, chaves e identificadores são fornecidos na contratação e variam por workspace