Listar agentes

Retorna todos os agentes ativos disponíveis para criação de negociações no workspace.

GEThttps://external-api.arbitralis.com.br/api/external/v1/agents

AutenticaçãoX-API-KEYSíncrono — a resposta já traz o resultado

Retorna os agentes ativos do workspace. Cada agente é um fluxo automatizado que conduz negociações — envia mensagens, interpreta respostas e aplica as regras configuradas.

Este é o primeiro endpoint de qualquer integração de negociação: é aqui que você descobre os agenteId disponíveis e as variáveis que cada um espera.

Não há parâmetros.

Campos de cada agente

Campo	Descrição
`agenteId`	Identificador único. Use ao criar negociações
`nome`	Nome de exibição
`descricao`	O que o agente faz. Pode ser `null`
`canal`	Canal de comunicação — por exemplo `WHATSAPP`
`agenteVariables[]`	Variáveis aceitas em `agenteInput`
`etapas[]`	Etapas de alto nível do fluxo

Estrutura de `agenteVariables`

Campo	Descrição
`key`	Chave a usar no objeto `agenteInput`
`type`	Tipo esperado: `string`, `number`, `boolean` ou `json`
`required`	Se a variável é obrigatória na criação
`label`	Rótulo amigável para exibição
`description`	Descrição detalhada

Monte a UI a partir deste endpoint

agenteVariables traz tipo, obrigatoriedade e rótulo de cada campo — informação suficiente para gerar dinamicamente o formulário de criação de negociação, sem hard-code de campos no seu sistema.

Somente agentes ativos

A listagem traz apenas agentes com status ativo. Um agente desativado no painel some desta lista e passa a rejeitar criações de negociação com 422.

Não guarde agenteId indefinidamente

Agentes podem ser desativados ou substituídos pela equipe do escritório. Revalide a lista periodicamente em vez de fixar um agenteId no código da sua integração.

Próximo passo

Para saber exatamente quais campos de counterparty e quais custom fields um agente exige, consulte Obter um agente.

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`429`	Limite de requisições excedido

Requisição

curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/agents" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

const response = await fetch('https://external-api.arbitralis.com.br/api/external/v1/agents', {
  headers: { 'X-API-KEY': 'arb_live_SUA_CHAVE' },
});

const { data: agentes } = await response.json();

for (const agente of agentes) {
  const obrigatorias = agente.agenteVariables.filter((variavel) => variavel.required);
  console.log(agente.nome, '→', obrigatorias.map((v) => v.key).join(', '));
}

Resposta

{
  "success": true,
  "data": [
    {
      "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
      "nome": "Cobrança amigável",
      "descricao": "Negociação de dívidas em atraso com proposta de parcelamento",
      "canal": "WHATSAPP",
      "agenteVariables": [
        {
          "key": "valor_pleiteado",
          "type": "number",
          "required": true,
          "label": "Valor pleiteado",
          "description": "Valor total da dívida em aberto"
        },
        {
          "key": "piso",
          "type": "number",
          "required": true,
          "label": "Piso de negociação",
          "description": "Menor valor que o agente pode aceitar"
        },
        {
          "key": "instrucoes_extras",
          "type": "string",
          "required": false,
          "label": "Instruções extras",
          "description": "Orientações adicionais para o agente"
        }
      ],
      "etapas": ["Abordagem inicial", "Proposta", "Negociação", "Fechamento"]
    },
    {
      "agenteId": "5b6c7d8e-9f0a-4b2c-8d4e-5f6a7b8c9d0e",
      "nome": "Confirmação de acordo",
      "descricao": "Confirma os termos de um acordo já negociado",
      "canal": "WHATSAPP",
      "agenteVariables": [
        {
          "key": "valor_acordado",
          "type": "number",
          "required": true,
          "label": "Valor acordado"
        }
      ]
    }
  ]
}

Campos de cada agente

Estrutura de agenteVariables

Somente agentes ativos

Próximo passo

Erros

Estrutura de `agenteVariables`