A chave é validada no provedor ao ser salva e fica no Vault. Nenhuma leitura devolve o segredo: só last4. O BotoZap usa só OpenAI e Anthropic, cujos termos da API excluem o uso dos dados enviados para treinamento.
Credenciais de provedores descontinuados
Em 17/10/2026 as credenciais de Google, OpenRouter, DeepSeek, xAI foram desativadas e o segredo delas foi apagado do Vault. Elas continuam na lista com active: false, validation_status: "invalid", last_error: "provider_not_enabled" e o provider antigo (google, openrouter, deepseek, xai), para você ver onde eram usadas, mas não executam: agentes, roteadores e finalidades que dependiam delas param com credential_unavailable. Não podem ser reativadas, revalidadas nem receber chave nova (422 provider_not_enabled). Cadastre uma credencial OpenAI ou Anthropic e use-a nos vínculos. Não é preciso excluir a antiga: versões de agente continuam citando a credencial, e a exclusão costuma voltar 409 in_use. Um vínculo cuja principal era uma delas e que tinha alternativa (fallback) OpenAI ou Anthropic passou a usar a alternativa como principal (exceto embedding); uma alternativa que apontava para uma delas foi removida do vínculo, para não derrubar a principal.
| provider | Nome | Onde gerar a chave |
|---|---|---|
anthropic | Anthropic · Claude | https://console.anthropic.com/settings/keys |
openai | OpenAI | https://platform.openai.com/api-keys |
Credenciais
GET /ai/credentials
Escopo agents:read
Query customer_id. Retorna todas as credenciais do Cliente, com os usos de cada uma.
POST /ai/credentials
Escopo agents:write
| Campo | Tipo e limites | Uso |
|---|---|---|
provider | openai, anthropic | Provedor da chave. Um provedor descontinuado (google, openrouter, deepseek, xai) é recusado com 422 provider_not_enabled. |
label | string 1–80 | Nome exibido. |
key | string 8–4096 | Segredo. Nunca é devolvido. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"provider": "openai",
"label": "OpenAI produção",
"key": "CHAVE_DO_SEU_PROVEDOR"
}Responde 201 com a credencial. Confira validation_status (valid, invalid ou pending) e last_error: só uma credencial válida e ativa pode ser publicada.
{
"id": "22222222-2222-4222-8222-222222222222",
"customer_id": "11111111-1111-4111-8111-111111111111",
"provider": "openai",
"label": "OpenAI produção",
"last4": "a1B2",
"revision": "1",
"active": true,
"validation_status": "valid",
"validated_at": "2026-09-25T13:00:00.000Z",
"last_error": null,
"models": [
"MODELO_A",
"MODELO_B"
],
"usage_count": 1,
"usages": [
{
"kind": "agent_version",
"id": "55555555-5555-4555-8555-555555555555",
"label": "Atendimento · v3"
}
]
}GET /ai/credentials/{id}
Escopo agents:read
Query customer_id. Mesmo formato do item da lista.
PATCH /ai/credentials/{id}
Escopo agents:write
Corpo com customer_id e expected_revision, mais uma das formas:
labele/ouactive: renomeia ou ativa/desativa;keysozinho: troca o segredo e valida de novo.keyjunto delabelouactiveé recusado com422 invalid.
Trocar a chave cria uma nova revisão. Em credencial de provedor descontinuado, active: true e key retornam 422 provider_not_enabled; renomear continua permitido.
POST /ai/credentials/{id}/revalidate
Escopo agents:write
Corpo {customer_id, expected_revision}. Consulta o provedor de novo e atualiza models e validation_status. Credencial de provedor descontinuado retorna 422 provider_not_enabled.
DELETE /ai/credentials/{id}
Escopo agents:write
Corpo {customer_id, expected_revision}. Responde 204. Uma credencial referenciada por versão, roteador ou finalidade retorna 409 in_use: troque os vínculos antes.
| Status | Código | Quando |
|---|---|---|
| 404 | not_found | Credencial inexistente neste Cliente. |
| 409 | revision_conflict | Revisão desatualizada. |
| 409 | in_use | Exclusão de credencial em uso. |
| 422 | invalid | Corpo fora do contrato ou modelo incompatível com a finalidade. |
| 422 | provider_not_enabled | Provedor descontinuado: criar, trocar a chave, revalidar ou reativar credencial que não seja OpenAI ou Anthropic, ou vincular uma finalidade a ela. |
| 503 | unavailable | Falha ao consultar as credenciais. |
Endpoints removidos: confirmação de uso de dados
Em 17/10/2026 a confirmação de uso de dados por credencial foi removida: com só OpenAI e Anthropic, cujos termos da API excluem o uso dos dados enviados para treinamento, ela nunca é exigida e nenhuma integração precisa fazer algo. Os endpoints GET /ai/credentials/{id}/data-use, POST /ai/credentials/{id}/data-use e POST /ai/credentials/{id}/data-use/revoke respondem 410 gone com o envelope de erro padrão e ficam assim por um período, para a integração que ainda os chame receber o aviso. Remova essas chamadas.
Finalidades
Cada chamada de modelo tem uma finalidade. O atendimento, o operador e o roteador usam o que foi publicado na versão ou no roteador. As outras usam o vínculo configurado aqui.
| purpose | Uso | Origem do modelo |
|---|---|---|
default | Padrão do Cliente | Vínculo próprio: padrão do Cliente |
agent_turn | Atendimento | Versão do agente |
agent_operator | Operador | Versão do agente |
router | Roteamento | Classificador do roteador |
followup | Acompanhamento | Vínculo próprio; sem ele, usa o padrão do Cliente |
proposal | Propostas | Vínculo próprio; sem ele, usa o padrão do Cliente |
transcription | Transcrição de áudio | Vínculo próprio com modelo de transcrição |
embedding | Base de conhecimento | Vínculo próprio, só OpenAI text-embedding-3-small |
guard | Proteção contra manipulação | Vínculo próprio; sem ele, usa o padrão do Cliente |
evaluator | Avaliação antes do envio | Vínculo próprio; sem ele, usa o padrão do Cliente |
classification | Classificação de conversas | Vínculo próprio; sem ele, usa o padrão do Cliente |
compaction | Compactação de memória | Vínculo próprio; sem ele, usa o padrão do Cliente |
case_chat | Consulta interna de casos | Vínculo próprio; sem ele, usa o padrão do Cliente |
learning_judge | Aprendizado: avaliação | Vínculo próprio; sem ele, usa Propostas e depois o padrão |
learning_distiller | Aprendizado: síntese | Vínculo próprio; sem ele, usa Propostas e depois o padrão |
vision | Descrição de imagens | Vínculo próprio; sem ele, usa o padrão do Cliente |
commercial_proposal | Propostas comerciais | Vínculo próprio; sem ele, usa o padrão do Cliente |
GET /ai/providers
Escopo agents:read
Query customer_id. Retorna providers (cada um com accepts_new_credentials, que indica se o provedor aceita credencial nova), purposes (rótulos), configurable_purposes, configuration_sources (onde ficam agent_turn, agent_operator e router), credentials e bindings.
PUT /ai/providers
Escopo agents:write
| Campo | Tipo e limites | Uso |
|---|---|---|
purpose | uma finalidade configurável | agent_turn, agent_operator e router são recusadas com 422. |
provider, model, credential_id | obrigatórios | Modelo compatível com a finalidade e credencial do mesmo provedor. |
fallback | objeto com provider, model, credential_id ou null | Alternativa usada quando o principal falha. |
{
"customer_id": "11111111-1111-4111-8111-111111111111",
"purpose": "embedding",
"provider": "openai",
"model": "text-embedding-3-small",
"credential_id": "22222222-2222-4222-8222-222222222222",
"fallback": null
}Retorna o vínculo salvo. embedding aceita apenas OpenAI text-embedding-3-small; transcription exige modelo de transcrição; vision recusa modelos que o catálogo indica sem entrada de imagem.
DELETE /ai/providers
Escopo agents:write
Corpo {customer_id, purpose}. Responde 204. A finalidade volta a herdar o padrão, quando herda.
Modelos e catálogo
GET /ai/providers/{provider}/models
Escopo agents:read
Query customer_id e credential_id. Lista os modelos que a credencial validada enxerga, com capabilities (text, transcription ou embedding).
GET /ai/providers/catalog
Escopo agents:read
Query customer_id. Último retrato do catálogo de cada credencial, sem chaves.
POST /ai/providers/catalog
Escopo agents:write · chave criada por um Administrador
Corpo {customer_id, credential_id, expected_revision}, com a revisão da credencial ("1" ou mais). Consulta o provedor com a sua chave e responde 201 com o retrato. Para provedores cuja lista não traz preço (OpenAI e Anthropic), pricing vem do endpoint do próprio provedor no catálogo público da OpenRouter, com source: "openrouter", só para o mesmo id (na Anthropic, sem a data e com a versão em ponto: claude-opus-4-5-20251101 → claude-opus-4.5); sem source, o preço é do próprio provedor. Preços do catálogo são sugestões: não alteram as tarifas de Uso e orçamento.
| Status | Código | Quando |
|---|---|---|
| 502 | provider_<erro> | O provedor não respondeu ao catálogo. Nada foi alterado. |
Visão geral do Agente de IA · Próxima: Agentes e versões
