Upload com mapeamento

Envia uma planilha com nomes de coluna próprios, informando o mapeamento para os campos da Arbitralis.

POSThttps://external-api.arbitralis.com.br/api/external/v1/notifications/batches/with-mapping

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

Igual ao upload de planilha, mas aceita arquivos com nomes de coluna próprios. Você envia um columnMapping que associa os campos da Arbitralis às colunas do seu arquivo.

Use quando o relatório vem de um ERP, de um sistema de cobrança ou de qualquer fonte cujo cabeçalho você não controla.

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

Campos multipart

filefileobrigatório

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

columnMappingstring (JSON)obrigatório

Objeto JSON serializado mapeando campos da Arbitralis para nomes de coluna do arquivo.

deliveryMethodstringobrigatório

Método de envio do lote. Obrigatório, exceto quando batchId é informado.

valoresDIGITALEMAIL_ONLYWHATSAPP_ONLYPHYSICALDIGITAL_PHYSICAL

batchNamestringopcional

Nome de exibição do lote.

batchCodestringopcional

Código único do lote, usado como chave de idempotência.

notificationTemplateIduuidobrigatório

Template de notificação do lote — o documento exibido no portal. Obrigatório, exceto quando batchId é informado. Obtenha em Listar templates.

batchIduuidopcional

Adiciona o arquivo a um lote já existente em vez de criar um novo.

Campos mapeáveis

A chave é o campo da Arbitralis; o valor é o nome exato da coluna no seu arquivo.

Chave	Campo correspondente
`fullName`	Nome completo do destinatário
`taxId`	CPF ou CNPJ
`email`	E-mail
`phoneNumber`	Telefone
`amount`	Valor do débito
`zipCode`	CEP
`street`	Logradouro
`number`	Número do imóvel
`complement`	Complemento
`neighborhood`	Bairro
`city`	Cidade
`state`	UF
`customFields`	Objeto com variáveis do template → nomes de coluna

Exemplo de columnMapping

{
  "fullName": "NOME DO CLIENTE",
  "taxId": "CPF/CNPJ",
  "email": "E-MAIL",
  "phoneNumber": "CELULAR",
  "amount": "VALOR EM ABERTO",
  "customFields": {
    "numero_contrato": "CONTRATO",
    "data_vencimento": "VENCIMENTO"
  }
}

Regras do mapeamento

Só mapeie os campos que existem no seu arquivo — campos ausentes no mapeamento simplesmente não são preenchidos.
Os nomes das colunas devem bater exatamente com o cabeçalho do arquivo, incluindo acentos, espaços e maiúsculas.
customFields mapeia variáveis do template (a chave configurada no painel) para colunas do arquivo.
O columnMapping viaja como string JSON dentro do multipart, não como objeto.

Mapeamento inválido rejeita o arquivo inteiro

Se o JSON não puder ser interpretado, a API responde 400 e nada é importado. Valide o JSON antes de montar o multipart.

Teste com um arquivo pequeno

Antes de importar dezenas de milhares de linhas, envie um recorte de 5 a 10 linhas com o mesmo cabeçalho. Confira em Listar itens se os campos caíram nos lugares certos e só então rode o arquivo completo.

Erros

Código	Causa
`400`	Arquivo inválido, campos ausentes ou `columnMapping` malformado
`401`	API key ausente, inválida ou inativa
`404`	`batchId` informado não existe neste workspace
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/with-mapping" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -F "[email protected]" \
  -F "deliveryMethod=DIGITAL" \
  -F "batchName=Importação ERP agosto" \
  -F "batchCode=erp-2026-08-01" \
  -F "notificationTemplateId=4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a" \
  -F 'columnMapping={"fullName":"NOME DO CLIENTE","taxId":"CPF/CNPJ","phoneNumber":"CELULAR","amount":"VALOR EM ABERTO"}'

import { readFileSync } from 'node:fs';

const columnMapping = {
  fullName: 'NOME DO CLIENTE',
  taxId: 'CPF/CNPJ',
  phoneNumber: 'CELULAR',
  amount: 'VALOR EM ABERTO',
  customFields: {
    numero_contrato: 'CONTRATO',
  },
};

const form = new FormData();
form.append(
  'file',
  new Blob([readFileSync('relatorio-erp.xlsx')], {
    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
  }),
  'relatorio-erp.xlsx'
);
form.append('deliveryMethod', 'DIGITAL');
form.append('batchCode', 'erp-2026-08-01');
form.append('notificationTemplateId', '4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a');
form.append('columnMapping', JSON.stringify(columnMapping));

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

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

import json
import requests

column_mapping = {
    "fullName": "NOME DO CLIENTE",
    "taxId": "CPF/CNPJ",
    "phoneNumber": "CELULAR",
    "amount": "VALOR EM ABERTO",
}

with open("relatorio-erp.xlsx", "rb") as arquivo:
    response = requests.post(
        "https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/with-mapping",
        headers={"X-API-KEY": "arb_live_SUA_CHAVE"},
        files={"file": ("relatorio-erp.xlsx", arquivo)},
        data={
            "deliveryMethod": "DIGITAL",
            "batchCode": "erp-2026-08-01",
            "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
            "columnMapping": json.dumps(column_mapping),
        },
        timeout=120,
    )

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

Resposta

{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
  },
  "message": "Batch created with column mapping successfully."
}