Upload de planilha

Envia um arquivo CSV ou XLSX para criar um lote de notificações no formato padrão de colunas.

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

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

Envia uma planilha para criar um lote de notificações. O arquivo precisa seguir o formato padrão de colunas da Arbitralis para o método de envio escolhido — baixe o modelo em Baixar modelo de planilha.

Se a sua planilha usa outros nomes de coluna, use Upload com mapeamento.

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

Campos multipart

filefileobrigatório

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

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.

Colunas esperadas

As colunas variam conforme o método de envio. Use ; como separador em arquivos CSV.

Envio digital

DIGITAL / EMAIL_ONLY / WHATSAPP_ONLY

nome;cpf_cnpj;email;telefone;valor
Maria Souza;12345678900;[email protected];+5511999999999;1500.75
João Pereira;98765432100;[email protected];+5521988888888;890.00

Carta física

PHYSICAL

nome;cpf_cnpj;cep;logradouro;numero;complemento;bairro;cidade;uf;valor
Maria Souza;12345678900;01310-100;Avenida Paulista;1000;Conj 52;Bela Vista;São Paulo;SP;1500.75

Digital + físico

DIGITAL_PHYSICAL

nome;cpf_cnpj;email;telefone;cep;logradouro;numero;complemento;bairro;cidade;uf;valor
Maria Souza;12345678900;[email protected];+5511999999999;01310-100;Avenida Paulista;1000;Conj 52;Bela Vista;São Paulo;SP;1500.75

As colunas dependem do método de envio

As colunas de contato são determinadas pelo deliveryMethod, não pelo template. Em DIGITAL e DIGITAL_PHYSICAL as colunas email e telefone sempre aparecem — deixe a célula vazia quando o item tiver apenas um dos contatos. O notificationTemplateId acrescenta ao final uma coluna por variável personalizada do template.

O cabeçalho é validado por correspondência exata. Gere o modelo de planilha com os mesmos parâmetros do upload para não errar.

Restrições do arquivo

Restrição	Valor
Extensões aceitas	`.csv`, `.xlsx`, `.xls`
Tamanho máximo	50 MB
Linhas de dados	Ao menos 1 (arquivo só com cabeçalho é rejeitado)
Separador CSV	`;`
Codificação recomendada	UTF-8

O processamento é assíncrono

A resposta 201 significa que o arquivo foi aceito, não que os itens já existem. A leitura e a validação das linhas acontecem em segundo plano.

Depois do upload:

Acompanhe o progresso com Obter um lote ou pelo stream de status.
Quando o lote terminar a validação, revise os itens inválidos em Listar itens ou baixe o relatório em Exportar erros em CSV.
Dispare os envios com Confirmar envio do lote.

Configure um timeout generoso

O upload de arquivos grandes pode levar dezenas de segundos. Configure o timeout do seu cliente HTTP para pelo menos 60 segundos neste endpoint.

Erros

Código	Causa
`400`	Arquivo inválido, ausente, acima de 50 MB, vazio, ou `deliveryMethod` faltando
`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" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -F "[email protected]" \
  -F "deliveryMethod=DIGITAL" \
  -F "batchName=Cobrança agosto/2026" \
  -F "batchCode=cobranca-2026-08-lote-01" \
  -F "notificationTemplateId=4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a"

import { readFileSync } from 'node:fs';

const form = new FormData();
form.append(
  'file',
  new Blob([readFileSync('cobranca-agosto.csv')], { type: 'text/csv' }),
  'cobranca-agosto.csv'
);
form.append('deliveryMethod', 'DIGITAL');
form.append('batchName', 'Cobrança agosto/2026');
form.append('batchCode', 'cobranca-2026-08-lote-01');
form.append('notificationTemplateId', '4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a');

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

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

import requests

with open("cobranca-agosto.csv", "rb") as arquivo:
    response = requests.post(
        "https://external-api.arbitralis.com.br/api/external/v1/notifications/batches",
        headers={"X-API-KEY": "arb_live_SUA_CHAVE"},
        files={"file": ("cobranca-agosto.csv", arquivo, "text/csv")},
        data={
            "deliveryMethod": "DIGITAL",
            "batchName": "Cobrança agosto/2026",
            "batchCode": "cobranca-2026-08-lote-01",
            "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
        },
        timeout=120,
    )

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

Resposta

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