Obter uma negociação

Retorna o estado atual de um caso de negociação — status, contraparte e conversa vinculada.

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

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

Retorna o estado atual de uma negociação. Use para acompanhar o andamento do caso e sincronizar o status com o seu sistema.

Parâmetros de rota

iduuidobrigatório

Identificador do caso de negociação.

Campos da resposta

Campo	Descrição
`negociacaoId`	Identificador do caso
`agenteId`	Agente atribuído. Pode ser `null`
`title`	Título de exibição
`status`	Status atual — ver tabela abaixo
`numeroNegociacao`	Número legível, no formato `NEG-AAAA-NNNN`. Pode ser `null`
`counterparty`	Nome, telefone e e-mail da contraparte
`conversaId`	Conversa vinculada. `null` enquanto ela não é criada
`dataCriacao`	Criação, em ISO 8601
`dataAtualizacao`	Última atualização, em ISO 8601
`archivedAt`	Arquivamento, em ISO 8601, ou `null`

Status

Status	Significado	Ações possíveis
`SCHEDULED`	Agendada; o agente inicia na data marcada	—
`STARTED`	Recém-criada e iniciada	Pausar, encerrar
`ACTIVE`	Em andamento	Pausar, encerrar
`PAUSED`	Pausada; o agente não atua	Retomar, encerrar
`AGREEMENT_CLOSED`	Encerrada com acordo	Nenhuma — não permite reabertura
`NO_AGREEMENT`	Encerrada sem acordo	Reabrir
`CLOSED`	Encerrada por desistência ou cancelamento	Reabrir

Arquivamento é independente do status

Uma negociação arquivada mantém o status que tinha. Para saber se ela está arquivada, verifique archivedAt — não o status.

Sincronizando com o seu sistema

Consulte este endpoint periodicamente para as negociações em aberto:

Sincronização periódica

const EM_ANDAMENTO = ['SCHEDULED', 'STARTED', 'ACTIVE', 'PAUSED'];

async function sincronizar(negociacoesLocais, apiKey) {
  const base = 'https://external-api.arbitralis.com.br/api/external/v1';

  for (const local of negociacoesLocais.filter((n) => EM_ANDAMENTO.includes(n.status))) {
    const response = await fetch(`${base}/extrajudicial/negotiations/${local.id}`, {
      headers: { 'X-API-KEY': apiKey },
    });

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

    if (data.status !== local.status) {
      await atualizarStatusLocal(local.id, data.status);
    }
  }
}

Cuidado com o limite de requisições

Consultar centenas de negociações uma a uma consome rapidamente o teto de 60 requisições por minuto. Priorize os casos em andamento, espace as verificações e considere consultar pelo lote quando as negociações vieram de uma campanha.

Erros

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

Requisição

curl -X GET "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" \
  -H "X-API-KEY: arb_live_SUA_CHAVE"

const negociacaoId = '1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d';

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

const { data: negociacao } = await response.json();
const encerrada = ['AGREEMENT_CLOSED', 'NO_AGREEMENT', 'CLOSED'].includes(negociacao.status);

import requests

negociacao_id = "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"

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

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

Resposta

{
  "success": true,
  "data": {
    "negociacaoId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
    "title": "Cobrança - Maria Souza",
    "status": "ACTIVE",
    "numeroNegociacao": "NEG-2026-0042",
    "counterparty": {
      "name": "Maria Souza",
      "phone": "+5511999999999",
      "email": "[email protected]"
    },
    "conversaId": "9f8e7d6c-5b4a-4928-9706-f5e4d3c2b1a0",
    "dataCriacao": "2026-08-07T14:32:10.000Z",
    "dataAtualizacao": "2026-08-07T16:45:22.000Z",
    "archivedAt": null
  }
}