Criar notificação

Cria uma notificação extrajudicial individual, com opção de confirmar o envio imediatamente ou agendar.

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

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

Cria uma notificação extrajudicial individual no workspace da API key. A API gera automaticamente um lote individual para acomodar o item — por isso a resposta traz tanto o item quanto o lote.

Por padrão a notificação nasce como rascunho. Use confirmSend: true para disparar na hora, ou combine com scheduledDate e scheduledTime para agendar.

Template e método de envio

Toda notificação precisa de um template de notificação (notificationTemplateId) — o documento que o destinatário visualiza e baixa no portal. Obtenha os disponíveis em Listar templates.

O template é um só, independente do canal. O deliveryMethod define apenas por onde o aviso chega ao destinatário e, com isso, quais dados de contato você precisa informar:

`deliveryMethod`	Blocos obrigatórios
`DIGITAL`	`contact` (com `emails` e/ou `phoneNumbers`)
`EMAIL_ONLY`	`contact` (com `emails`)
`WHATSAPP_ONLY`	`contact` (com `phoneNumbers`)
`PHYSICAL`	`address`
`DIGITAL_PHYSICAL`	`contact` e `address`

Body

deliveryMethodstringobrigatório

Canal de envio da notificação.

valoresDIGITALEMAIL_ONLYWHATSAPP_ONLYPHYSICALDIGITAL_PHYSICAL

notificationTemplateIduuidobrigatório

Template de notificação — o documento exibido no portal. Obtenha em Listar templates.

amountnumberobrigatório

Valor monetário do débito ou da causa, em reais. Deve ser maior ou igual a 0 e no máximo 999.999.999,99.

contactobjectopcional

Dados de contato do destinatário. Obrigatório para os métodos digitais.

addressobjectopcional

Endereço de entrega. Obrigatório para os métodos físicos.

descriptionstringopcional

Breve relato do caso, até 2000 caracteres. Exibido apenas internamente.

responseOptionsarrayopcional

Opções de resposta exibidas ao destinatário no portal. Mínimo 1, máximo 3.

negotiationMarginnumberopcional

Desconto máximo permitido no portal de negociação, em percentual de 0 a 100.

metadataobjectopcional

Mapa livre de chave-valor com dados seus. Todos os valores devem ser strings. É aqui que vão as variáveis personalizadas que o template declara — veja Obter um template.

requesterPersonIduuidopcional

Pessoa requerente já cadastrada. Se omitido, a notificação é criada sem requerente vinculado.

recipientPersonIduuidopcional

Pessoa destinatária já cadastrada. Se omitido, uma nova pessoa é criada a partir de contact.taxId e contact.name.

confirmSendbooleanopcionalpadrão false

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

scheduledDatestringopcional

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

scheduledTimestringopcional

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

contact

emailsstring[]opcional

E-mails do destinatário. Obrigatório para DIGITAL, EMAIL_ONLY e DIGITAL_PHYSICAL.

phoneNumbersstring[]opcional

Telefones em formato internacional. Obrigatório para DIGITAL, WHATSAPP_ONLY e DIGITAL_PHYSICAL.

namestringopcional

Nome completo do destinatário, até 200 caracteres. Obrigatório para envio físico.

taxIdstringopcional

CPF ou CNPJ do destinatário. Usado para localizar ou criar a pessoa no sistema.

address

zipCodestringobrigatório

CEP no formato 00000-000 ou 00000000.

streetstringobrigatório

Logradouro. Entre 3 e 200 caracteres.

numberstringobrigatório

Número do imóvel.

neighborhoodstringobrigatório

Bairro. Entre 2 e 100 caracteres.

citystringobrigatório

Cidade. Entre 2 e 100 caracteres.

statestringobrigatório

UF com exatamente 2 letras.

complementstringopcional

Complemento — apartamento, sala, bloco.

referencestringopcional

Ponto de referência para facilitar a entrega.

responseOptions[]

labelstringobrigatório

Texto exibido ao destinatário, até 120 caracteres.

typestringobrigatório

Tipo da opção de resposta.

valoresRESPONSEMANIFESTATIONDISAGREEMENTNEGOTIATION_REQUEST

Agendamento

Para agendar em vez de enviar imediatamente, combine os três campos:

Agendar para 12/08/2026 às 09:30

{
  "confirmSend": true,
  "scheduledDate": "2026-08-12",
  "scheduledTime": "09:30"
}

Fuso horário do agendamento

scheduledDate e scheduledTime são interpretados no fuso do servidor da Arbitralis (horário de Brasília). Converta antes de enviar se o seu sistema opera em outro fuso.

Criando ou reaproveitando a pessoa

Com recipientPersonId, a notificação é vinculada à pessoa já cadastrada.
Sem ele, a API cria uma nova pessoa a partir de contact.taxId e contact.name.

Para evitar cadastros duplicados, chame Validar documento primeiro e reaproveite o existingPerson.id retornado.

Volume

Este endpoint cria uma notificação por chamada e consome uma requisição do seu limite. Para vários destinatários, use Criar lote via JSON — até 1000 itens em uma única requisição.

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`422`	`notificationTemplateId` ausente ou inválido, ou `contact`/`address` faltando para o método
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/notifications" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "deliveryMethod": "DIGITAL",
    "amount": 1500.75,
    "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
    "description": "Parcela 3/12 do contrato 8842 em atraso",
    "contact": {
      "name": "Maria Souza",
      "taxId": "12345678900",
      "emails": ["[email protected]"],
      "phoneNumbers": ["+5511999999999"]
    },
    "responseOptions": [
      { "label": "Quero negociar", "type": "NEGOTIATION_REQUEST" },
      { "label": "Já paguei", "type": "MANIFESTATION" }
    ],
    "negotiationMargin": 20,
    "metadata": {
      "numero_contrato": "8842",
      "data_vencimento": "2026-07-10"
    },
    "confirmSend": true
  }'

const response = await fetch(
  'https://external-api.arbitralis.com.br/api/external/v1/notifications',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'arb_live_SUA_CHAVE',
    },
    body: JSON.stringify({
      deliveryMethod: 'DIGITAL',
      amount: 1500.75,
      notificationTemplateId: '4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a',
      contact: {
        name: 'Maria Souza',
        taxId: '12345678900',
        emails: ['[email protected]'],
        phoneNumbers: ['+5511999999999'],
      },
      confirmSend: true,
    }),
  }
);

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

import requests

response = requests.post(
    "https://external-api.arbitralis.com.br/api/external/v1/notifications",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "arb_live_SUA_CHAVE",
    },
    json={
        "deliveryMethod": "DIGITAL",
        "amount": 1500.75,
        "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
        "contact": {
            "name": "Maria Souza",
            "taxId": "12345678900",
            "emails": ["[email protected]"],
            "phoneNumbers": ["+5511999999999"],
        },
        "confirmSend": True,
    },
)

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

{
  "deliveryMethod": "PHYSICAL",
  "amount": 3200.00,
  "notificationTemplateId": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a",
  "contact": {
    "name": "João Pereira",
    "taxId": "98765432100"
  },
  "address": {
    "zipCode": "01310-100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Conjunto 52",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}

Resposta

{
  "success": true,
  "data": {
    "item": {
      "id": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "loteId": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "status": "PENDENTE",
      "valor": 1500.75,
      "dataCriacao": "2026-08-07T14:32:10.000Z"
    },
    "lote": {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "batchName": "Individual Digital - 07/08/2026 14:32",
      "status": "AGUARDANDO_ENVIO",
      "sendMethod": "DIGITAL",
      "totais": {
        "totalItens": 1,
        "validos": 1,
        "invalidos": 0,
        "enviados": 0,
        "pendentes": 1
      },
      "dataCriacao": "2026-08-07T14:32:10.000Z"
    }
  },
  "message": "Criado com sucesso"
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input: expected string, received undefined",
    "details": [
      {
        "code": "invalid_type",
        "path": ["notificationTemplateId"],
        "message": "Invalid input: expected string, received undefined"
      }
    ],
    "errorEventId": "b1f3c6d8-2a44-4d9e-9f10-7c5b8e2a1d33"
  }
}