Criar negociação

Cria e inicia uma negociação extrajudicial conduzida por um agente, imediatamente ou de forma agendada.

POSThttps://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations

AutenticaçãoX-API-KEYAssíncrono — o processamento continua depois da resposta

Cria uma negociação e coloca o agente para trabalhar. A partir daí o agente executa conforme sua configuração: envia a primeira mensagem, interpreta as respostas, gerencia propostas e escala para um humano quando necessário.

Antes de chamar este endpoint, consulte Obter um agente para saber quais variáveis o agente escolhido exige.

Body

agenteIduuidobrigatório

Agente que conduzirá a negociação. Obtenha em Listar agentes.

counterpartyobjectobrigatório

Dados da pessoa com quem será negociado.

startModestringobrigatório

NOW inicia o agente imediatamente. SCHEDULED exige scheduledFor.

valoresNOWSCHEDULED

scheduledForstringopcional

Data e hora de início em ISO 8601. Obrigatório quando startMode é SCHEDULED.

agenteInputobjectopcional

Variáveis do agente. As chaves aceitas vêm de agenteVariables em Obter um agente.

titlestringopcional

Título de exibição da negociação, até 255 caracteres. Gerado automaticamente se omitido.

objectivestringopcional

Objetivo breve da negociação, até 100 caracteres.

externalIdstringopcional

Identificador de referência no seu sistema, até 255 caracteres. Ver a observação sobre idempotência abaixo.

counterparty

cpfCnpjstringobrigatório

CPF (11 dígitos) ou CNPJ (14 dígitos). Aceita apenas dígitos ou formatado.

namestringobrigatório

Nome completo da contraparte, até 255 caracteres.

phonestringobrigatório

Telefone em formato internacional. Canal principal de comunicação do agente.

emailstringopcional

E-mail da contraparte, usado como contato secundário.

Idempotência por telefone e agente

Se já existe uma negociação ativa com o mesmo telefone e o mesmo agente na empresa, a API devolve o caso existente com 200 em vez de criar um duplicado. Isso impede que a mesma pessoa receba duas abordagens simultâneas do mesmo agente.

Resposta	Significado
`201` com `status: "STARTED"`	Negociação nova, agente iniciado
`201` com `status: "SCHEDULED"`	Negociação nova, início agendado
`200` com qualquer outro status	Caso ativo já existia e foi devolvido

externalId não é chave de idempotência aqui

Na criação individual, externalId serve apenas como referência sua para rastreio. A regra de idempotência é telefone + agente. Para idempotência por identificador próprio, use Criar lote via JSON, onde externalId é a chave por item.

Agendamento

Com startMode: "SCHEDULED", informe scheduledFor em ISO 8601:

{
  "startMode": "SCHEDULED",
  "scheduledFor": "2026-08-12T13:00:00Z"
}

A negociação nasce com status SCHEDULED e o agente só entra em ação na data marcada.

Erros comuns

Situação	Como evitar
`agenteInput` com chave inexistente	Envie apenas as chaves de `agenteVariables` (Obter um agente)
Variável obrigatória ausente	Verifique `required` em `agenteVariables`
Agente não encontrado	Revalide a lista — o agente pode ter sido desativado
Telefone sem DDI	Use formato internacional: `+5511999999999`

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`422`	Campo obrigatório ausente, variável desconhecida em `agenteInput`, ou agente não encontrado
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
    "title": "Cobrança - Maria Souza",
    "objective": "Cobrar R$ 1.500,75",
    "startMode": "NOW",
    "counterparty": {
      "cpfCnpj": "12345678900",
      "name": "Maria Souza",
      "phone": "+5511999999999",
      "email": "[email protected]"
    },
    "agenteInput": {
      "valor_pleiteado": 1500.75,
      "piso": 1200.00,
      "numero_contrato": "8842"
    },
    "externalId": "contrato-8842"
  }'

const response = await fetch(
  'https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'arb_live_SUA_CHAVE',
    },
    body: JSON.stringify({
      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',
      },
      externalId: 'contrato-8842',
    }),
  }
);

const { data } = await response.json();
const criouAgora = response.status === 201;

import requests

response = requests.post(
    "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "arb_live_SUA_CHAVE",
    },
    json={
        "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
        "startMode": "NOW",
        "counterparty": {
            "cpfCnpj": "12345678900",
            "name": "Maria Souza",
            "phone": "+5511999999999",
        },
        "agenteInput": {
            "valor_pleiteado": 1500.75,
            "piso": 1200.00,
            "numero_contrato": "8842",
        },
    },
)

data = response.json()["data"]

{
  "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
  "startMode": "SCHEDULED",
  "scheduledFor": "2026-08-12T13:00:00Z",
  "counterparty": {
    "cpfCnpj": "12345678900",
    "name": "Maria Souza",
    "phone": "+5511999999999"
  },
  "agenteInput": {
    "valor_pleiteado": 1500.75,
    "piso": 1200.0
  }
}

Resposta

{
  "success": true,
  "data": {
    "negociacaoId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "status": "STARTED"
  },
  "message": "Negotiation created successfully."
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Variável desconhecida em agenteInput: valor_total",
    "errorEventId": "b1f3c6d8-2a44-4d9e-9f10-7c5b8e2a1d33"
  }
}