Credenciais e provedores

Cadastre as chaves dos seus provedores, escolha o modelo de cada finalidade e mantenha o catálogo de modelos atualizado.

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.

providerNomeOnde gerar a chave
anthropicAnthropic · Claudehttps://console.anthropic.com/settings/keys
openaiOpenAIhttps://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

CampoTipo e limitesUso
provideropenai, anthropicProvedor da chave. Um provedor descontinuado (google, openrouter, deepseek, xai) é recusado com 422 provider_not_enabled.
labelstring 1–80Nome exibido.
keystring 8–4096Segredo. 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:

  • label e/ou active: renomeia ou ativa/desativa;
  • key sozinho: troca o segredo e valida de novo. key junto de label ou active é recusado com 422 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.

StatusCódigoQuando
404not_foundCredencial inexistente neste Cliente.
409revision_conflictRevisão desatualizada.
409in_useExclusão de credencial em uso.
422invalidCorpo fora do contrato ou modelo incompatível com a finalidade.
422provider_not_enabledProvedor descontinuado: criar, trocar a chave, revalidar ou reativar credencial que não seja OpenAI ou Anthropic, ou vincular uma finalidade a ela.
503unavailableFalha 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.

purposeUsoOrigem do modelo
defaultPadrão do ClienteVínculo próprio: padrão do Cliente
agent_turnAtendimentoVersão do agente
agent_operatorOperadorVersão do agente
routerRoteamentoClassificador do roteador
followupAcompanhamentoVínculo próprio; sem ele, usa o padrão do Cliente
proposalPropostasVínculo próprio; sem ele, usa o padrão do Cliente
transcriptionTranscrição de áudioVínculo próprio com modelo de transcrição
embeddingBase de conhecimentoVínculo próprio, só OpenAI text-embedding-3-small
guardProteção contra manipulaçãoVínculo próprio; sem ele, usa o padrão do Cliente
evaluatorAvaliação antes do envioVínculo próprio; sem ele, usa o padrão do Cliente
classificationClassificação de conversasVínculo próprio; sem ele, usa o padrão do Cliente
compactionCompactação de memóriaVínculo próprio; sem ele, usa o padrão do Cliente
case_chatConsulta interna de casosVínculo próprio; sem ele, usa o padrão do Cliente
learning_judgeAprendizado: avaliaçãoVínculo próprio; sem ele, usa Propostas e depois o padrão
learning_distillerAprendizado: sínteseVínculo próprio; sem ele, usa Propostas e depois o padrão
visionDescrição de imagensVínculo próprio; sem ele, usa o padrão do Cliente
commercial_proposalPropostas comerciaisVí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

CampoTipo e limitesUso
purposeuma finalidade configurávelagent_turn, agent_operator e router são recusadas com 422.
provider, model, credential_idobrigatóriosModelo compatível com a finalidade e credencial do mesmo provedor.
fallbackobjeto com provider, model, credential_id ou nullAlternativa 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.

StatusCódigoQuando
502provider_<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