Upload de planilha

Envia um arquivo CSV ou XLSX para criar um lote de negociações, com mapeamento de colunas opcional.

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

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

Envia uma planilha para criar um lote de negociações. O arquivo é processado de forma assíncrona e o lote nasce em validação — nada é disparado até que você confirme o lote.

A requisição é multipart/form-data.

Campos multipart

filefileobrigatório

Arquivo .csv, .xlsx ou .xls. Máximo de 10 MB.

agenteIduuidobrigatório

Agente que conduzirá as negociações do lote.

titlestringopcional

Título de exibição do lote. Se omitido, usa a data atual.

mapeamentostring (JSON)opcional

Objeto JSON serializado mapeando nomes de coluna do arquivo para campos de destino. Máximo de 64 KB.

Mapeamento de colunas

Diferente do upload de notificações, aqui a chave é o nome da coluna no seu arquivo e o valor é o campo de destino.

mapeamento

{
  "NOME DO CLIENTE": "name",
  "CPF/CNPJ": "cpfCnpj",
  "CELULAR": "phone",
  "E-MAIL": "email",
  "VALOR DÍVIDA": "amount",
  "VALOR MÍNIMO": "floor",
  "PROTOCOLO": "campo_personalizado_protocolo"
}

Campos de destino reconhecidos

Destino	Significado
`name`	Nome completo da contraparte
`phone`	Telefone
`email`	E-mail
`cpfCnpj`	CPF ou CNPJ
`amount`	Valor da dívida
`floor`	Piso de negociação
`margin`	Margem de desconto

Qualquer outro valor é tratado como chave de custom field e precisa corresponder a um campo personalizado ativo no workspace.

Sinônimos aceitos

Além dos nomes acima, o mapeamento aceita variações em português para os campos base: nome, telefone, whatsapp, cpf_cnpj, valor e valorDivida.

Os totais vêm zerados na resposta

A resposta 201 confirma que o arquivo foi aceito, antes de ser processado — por isso totalRows, totalValid e totalInvalid vêm zerados. Os números reais aparecem em Obter um lote depois que a validação termina.

Restrições do arquivo

Restrição	Valor
Extensões aceitas	`.csv`, `.xlsx`, `.xls`
Tamanho máximo	10 MB
Tamanho do `mapeamento`	64 KB
Separador CSV	`;`
Codificação recomendada	UTF-8

Fluxo completo

1. Upload da planilha    → POST /extrajudicial/negotiations/batches/csv
2. Aguardar validação    → GET  /extrajudicial/negotiations/batches/{id}
3. Revisar itens         → GET  /extrajudicial/negotiations/batches/{id}/items
4. Confirmar e disparar  → POST /extrajudicial/negotiations/batches/{id}/confirm

Teste com um recorte primeiro

Antes de subir a campanha completa, envie 5 a 10 linhas com o mesmo cabeçalho e confira em Listar itens se os campos caíram nos lugares certos.

Erros

Código	Causa
`400`	Arquivo inválido, acima de 10 MB, `agenteId` ausente, agente inativo, ou `mapeamento` malformado
`401`	API key ausente, inválida ou inativa
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/csv" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -F "[email protected]" \
  -F "agenteId=3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c" \
  -F "title=Campanha agosto/2026" \
  -F 'mapeamento={"NOME DO CLIENTE":"name","CPF/CNPJ":"cpfCnpj","CELULAR":"phone","VALOR DÍVIDA":"amount"}'

import { readFileSync } from 'node:fs';

const mapeamento = {
  'NOME DO CLIENTE': 'name',
  'CPF/CNPJ': 'cpfCnpj',
  CELULAR: 'phone',
  'VALOR DÍVIDA': 'amount',
  'VALOR MÍNIMO': 'floor',
};

const form = new FormData();
form.append(
  'file',
  new Blob([readFileSync('campanha-agosto.csv')], { type: 'text/csv' }),
  'campanha-agosto.csv'
);
form.append('agenteId', '3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c');
form.append('title', 'Campanha agosto/2026');
form.append('mapeamento', JSON.stringify(mapeamento));

const response = await fetch(
  'https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/csv',
  {
    method: 'POST',
    headers: { 'X-API-KEY': 'arb_live_SUA_CHAVE' },
    body: form,
  }
);

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

import json
import requests

mapeamento = {
    "NOME DO CLIENTE": "name",
    "CPF/CNPJ": "cpfCnpj",
    "CELULAR": "phone",
    "VALOR DÍVIDA": "amount",
}

with open("campanha-agosto.csv", "rb") as arquivo:
    response = requests.post(
        "https://external-api.arbitralis.com.br/api/external/v1/extrajudicial/negotiations/batches/csv",
        headers={"X-API-KEY": "arb_live_SUA_CHAVE"},
        files={"file": ("campanha-agosto.csv", arquivo, "text/csv")},
        data={
            "agenteId": "3f0a1c2e-8b7d-4e5a-9c1f-2d3e4f5a6b7c",
            "title": "Campanha agosto/2026",
            "mapeamento": json.dumps(mapeamento),
        },
        timeout=120,
    )

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

Resposta

{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "totalRows": 0,
    "totalValid": 0,
    "totalInvalid": 0
  },
  "message": "CSV accepted for processing."
}