Criar lote via JSON

Cria um lote de até 1000 notificações a partir de um array JSON, com validação item a item.

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

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

Cria um lote de notificações a partir de um array de objetos. É a alternativa servidor-a-servidor ao upload de planilha: cada objeto em items[] equivale a uma linha da planilha, e você recebe o veredito de validação de cada um na mesma resposta.

O lote define o método de envio e o template de notificação padrão; cada item pode sobrescrevê-los.

Body

deliveryMethodstringobrigatório

Método de envio padrão do lote. Cada item pode sobrescrever.

valoresDIGITALEMAIL_ONLYWHATSAPP_ONLYPHYSICALDIGITAL_PHYSICAL

notificationTemplateIduuidobrigatório

Template de notificação padrão do lote — o documento exibido no portal. Cada item pode sobrescrever. Obtenha em Listar templates.

itemsarrayobrigatório

Itens de notificação. Mínimo 1, máximo 1000 por chamada.

batchNamestringopcional

Nome de exibição do lote, até 100 caracteres. Se omitido, usa a data e a hora atuais.

batchCodestringopcional

Código único do lote, até 50 caracteres. Chave de idempotência — ver abaixo.

confirmSendbooleanopcionalpadrão false

Se true, confirma e despacha o envio logo após a criação.

scheduledDatestringopcional

Data do agendamento no formato YYYY-MM-DD. Exige confirmSend: true.

scheduledTimestringopcional

Hora do agendamento no formato HH:MM. Exige confirmSend: true.

items[]

externalIdstringobrigatório

Identificador do registro no seu sistema. Chave de idempotência por item, até 255 caracteres.

amountnumberobrigatório

Valor do débito em reais. Maior ou igual a 0, no máximo 999.999.999,99.

contactobjectobrigatório

Dados de contato do destinatário.

addressobjectopcional

Endereço do destinatário. Obrigatório quando o método de envio inclui carta física.

descriptionstringopcional

Breve descrição do caso, até 2000 caracteres.

negotiationMarginnumberopcional

Desconto máximo permitido no portal, em percentual de 0 a 100.

metadataobjectopcional

Dados customizados chave-valor. Todos os valores devem ser strings. É aqui que vão as variáveis personalizadas declaradas pelo template.

deliveryMethodstringopcional

Sobrescreve o método de envio para este item.

O template é do lote, não do item

notificationTemplateId existe apenas no nível do lote — todos os itens usam o mesmo documento. Para enviar templates diferentes, crie lotes separados.

items[].contact

namestringobrigatório

Nome completo do destinatário, até 200 caracteres.

taxIdstringobrigatório

CPF ou CNPJ do destinatário. Entre 11 e 18 caracteres.

phoneNumbersstring[]opcional

Telefones em formato internacional.

emailsstring[]opcional

Endereços de e-mail.

Validação item a item

O lote é aceito mesmo com itens inválidos. Cada item recebe seu próprio veredito:

`status`	Significado
`VALIDATED`	Item aceito e criado. `itemId` preenchido
`INVALID`	Item rejeitado. Veja `errors`

Itens inválidos não impedem o processamento dos válidos. Corrija-os e reenvie apenas eles, com o mesmo batchCode.

Reconciliando o resultado

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

for (const item of data.items) {
  if (item.status === 'INVALID') {
    await registrarFalha(item.externalId, item.errors);
    continue;
  }

  await salvarItemId(item.externalId, item.itemId);
}

Idempotência e lotes grandes

Se um lote com o mesmo batchCode já existir na empresa, a API responde 200 com o lote existente em vez de criar um novo.

Isso permite dividir volumes grandes: envie 1000 itens por chamada mantendo o mesmo batchCode e os itens são agregados ao mesmo lote.

Acima de 5000 itens, prefira a planilha

Para volumes muito grandes, o upload de planilha costuma ser mais eficiente — um único arquivo de até 50 MB, processado de forma assíncrona.

Do lote ao envio

Com confirmSend: false (padrão), o lote fica aguardando confirmação. Para disparar depois, chame Confirmar envio do lote — isso permite revisar os itens inválidos antes de enviar qualquer coisa.

confirmSend dispara de imediato

Com confirmSend: true, os itens válidos são despachados assim que o lote é criado. Não há etapa de revisão. Use apenas quando os dados já vierem validados da sua ponta.

Erros

Código	Causa
`400`	Corpo inválido ou método de envio não habilitado para a empresa
`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/notifications/batches/json" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "batchName": "Cobrança agosto/2026",
    "batchCode": "cobranca-2026-08-lote-01",
    "deliveryMethod": "DIGITAL",
    "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
    "confirmSend": false,
    "items": [
      {
        "externalId": "contrato-8842",
        "amount": 1500.75,
        "description": "Parcela 3/12 em atraso",
        "contact": {
          "name": "Maria Souza",
          "taxId": "12345678900",
          "phoneNumbers": ["+5511999999999"],
          "emails": ["[email protected]"]
        },
        "metadata": { "numero_contrato": "8842", "data_vencimento": "2026-07-10" }
      },
      {
        "externalId": "contrato-8843",
        "amount": 890.00,
        "contact": {
          "name": "João Pereira",
          "taxId": "98765432100",
          "phoneNumbers": ["+5521988888888"]
        }
      }
    ]
  }'

const response = await fetch(
  'https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/json',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'arb_live_SUA_CHAVE',
    },
    body: JSON.stringify({
      batchName: 'Cobrança agosto/2026',
      batchCode: 'cobranca-2026-08-lote-01',
      deliveryMethod: 'DIGITAL',
      notificationTemplateId: '4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a',
      items: cobrancas.map((cobranca) => ({
        externalId: cobranca.id,
        amount: cobranca.valor,
        contact: {
          name: cobranca.devedor.nome,
          taxId: cobranca.devedor.cpf,
          phoneNumbers: [cobranca.devedor.telefone],
        },
      })),
    }),
  }
);

const { data } = await response.json();
const invalidos = data.items.filter((item) => item.status === 'INVALID');

import requests

response = requests.post(
    "https://external-api.arbitralis.com.br/api/external/v1/notifications/batches/json",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "arb_live_SUA_CHAVE",
    },
    json={
        "batchName": "Cobrança agosto/2026",
        "batchCode": "cobranca-2026-08-lote-01",
        "deliveryMethod": "DIGITAL",
        "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
        "items": [
            {
                "externalId": "contrato-8842",
                "amount": 1500.75,
                "contact": {
                    "name": "Maria Souza",
                    "taxId": "12345678900",
                    "phoneNumbers": ["+5511999999999"],
                },
            }
        ],
    },
)

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

Resposta

{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "batchCode": "cobranca-2026-08-lote-01",
    "totalItems": 2,
    "totalValid": 1,
    "totalInvalid": 1,
    "status": "PENDING_CONFIRMATION",
    "items": [
      {
        "externalId": "contrato-8842",
        "itemId": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
        "status": "VALIDATED"
      },
      {
        "externalId": "contrato-8843",
        "status": "INVALID",
        "errors": [
          {
            "code": "VALIDATION_ERROR",
            "field": "contact.taxId",
            "message": "CPF/CNPJ inválido"
          }
        ]
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "batchId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "batchCode": "cobranca-2026-08-lote-01",
    "totalItems": 2,
    "totalValid": 2,
    "totalInvalid": 0,
    "status": "QUEUED",
    "items": []
  }
}