Validar documento

Valida um CPF ou CNPJ e verifica se já existe uma pessoa cadastrada com esse documento no workspace.

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

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

Use este endpoint antes de criar notificações para descartar documentos inválidos e descobrir se o destinatário já está cadastrado no workspace. Isso reduz o volume de itens rejeitados no processamento do lote.

A validação verifica os dígitos do CPF/CNPJ e cruza o nome informado com os registros existentes.

Body

taxIdstringobrigatório

CPF ou CNPJ da pessoa. Aceita apenas dígitos ou formatado. Entre 11 e 18 caracteres.

namestringobrigatório

Nome completo da pessoa. Mínimo de 2 caracteres. Usado para cruzar com registros existentes.

Campos da resposta

Campo	Tipo	Descrição
`valid`	boolean	Se o documento passou na validação
`errors`	string[]	Lista de problemas encontrados. Vazia quando `valid` é `true`
`officialName`	string \| null	Nome oficial retornado pela validação ou do cadastro existente
`existingPerson`	object \| null	Pessoa já cadastrada com esse documento, ou `null`

Reaproveite a pessoa existente

Quando existingPerson vem preenchido, use o id retornado no campo recipientPersonId de Criar notificação. Isso evita cadastro duplicado e mantém o histórico do destinatário unificado.

Um HTTP 200 não significa documento válido

Este endpoint responde 200 mesmo para documentos inválidos — a validação é o conteúdo da resposta, não o status. Sempre leia o campo valid.

Tratamento correto

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

if (!data.valid) {
  console.warn('Documento rejeitado:', data.errors);
  return;
}

Erros

Código	Causa
`401`	API key ausente, inválida ou inativa
`422`	`taxId` ou `name` fora do formato exigido
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/notifications/validate-document" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{
    "taxId": "12345678900",
    "name": "Maria Souza"
  }'

const response = await fetch(
  'https://external-api.arbitralis.com.br/api/external/v1/notifications/validate-document',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'arb_live_SUA_CHAVE',
    },
    body: JSON.stringify({
      taxId: '12345678900',
      name: 'Maria Souza',
    }),
  }
);

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

import requests

response = requests.post(
    "https://external-api.arbitralis.com.br/api/external/v1/notifications/validate-document",
    headers={
        "Content-Type": "application/json",
        "X-API-KEY": "arb_live_SUA_CHAVE",
    },
    json={
        "taxId": "12345678900",
        "name": "Maria Souza",
    },
)

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

$response = file_get_contents(
    'https://external-api.arbitralis.com.br/api/external/v1/notifications/validate-document',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => "Content-Type: application/json\r\nX-API-KEY: arb_live_SUA_CHAVE\r\n",
            'content' => json_encode([
                'taxId' => '12345678900',
                'name' => 'Maria Souza',
            ]),
        ],
    ])
);

$data = json_decode($response, true)['data'];

Resposta

{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "officialName": "MARIA SOUZA",
    "existingPerson": {
      "id": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
      "name": "Maria Souza"
    }
  }
}