Obter um agente

Retorna o detalhe de um agente, incluindo os campos de contraparte e os custom fields obrigatórios.

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

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

Retorna o detalhe completo de um agente. Além das informações de Listar agentes, traz os requisitos exatos para criar uma negociação com ele:

requiredCounterpartyFields — quais campos de counterparty são obrigatórios.
requiredCustomFields — quais custom fields devem vir em agenteInput.

Consulte este endpoint antes de montar o payload de criação.

Parâmetros de rota

iduuidobrigatório

Identificador do agente.

Campos exclusivos do detalhe

Campo	Descrição
`requiredCounterpartyFields`	Campos de `counterparty` obrigatórios para este agente
`requiredCustomFields`	Chaves de custom fields que devem constar em `agenteInput`, derivadas dos templates do agente

Montando o payload a partir do detalhe

O detalhe do agente descreve exatamente o payload de Criar negociação:

Payload derivado do exemplo acima

{
  "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
  "startMode": "NOW",
  "counterparty": {
    "cpfCnpj": "12345678900",
    "name": "Maria Souza",
    "phone": "+5511999999999"
  },
  "agenteInput": {
    "valor_pleiteado": 1500.75,
    "piso": 1200.0,
    "numero_contrato": "8842"
  }
}

Valide antes de enviar

Comparar as chaves do seu agenteInput com agenteVariables do lado do cliente evita um round-trip de 422. Em lotes, essa validação prévia evita dezenas de itens rejeitados.

Variável desconhecida é rejeitada

Enviar em agenteInput uma chave que não consta em agenteVariables faz a criação retornar 422. Envie apenas as chaves declaradas pelo agente.

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`404`	Agente não encontrado ou inativo neste workspace
`429`	Limite de requisições excedido

Requisição

curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/agents/3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

const agenteId = '3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c';

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

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

const faltando = agente.agenteVariables
  .filter((variavel) => variavel.required)
  .filter((variavel) => !(variavel.key in meuPayload.agenteInput));

if (faltando.length > 0) {
  throw new Error(`Variáveis obrigatórias ausentes: ${faltando.map((v) => v.key).join(', ')}`);
}

import requests

agente_id = "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c"

response = requests.get(
    f"https://external-api.arbitralis.com.br/api/external/v1/agents/{agente_id}",
    headers={"X-API-KEY": "arb_live_SUA_CHAVE"},
)

agente = response.json()["data"]
obrigatorias = [v["key"] for v in agente["agenteVariables"] if v["required"]]

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": "numero_contrato",
        "type": "string",
        "required": true,
        "label": "Número do contrato"
      }
    ],
    "requiredCounterpartyFields": ["cpfCnpj", "name", "phone"],
    "requiredCustomFields": ["numero_contrato"]
  }
}