Enviar carta física

Gera o PDF e dispara o envio postal de um item de notificação específico.

POSThttps://external-api.arbitralis.com.br/api/external/v1/notifications/items/{itemId}/send-physical

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

Dispara a geração do PDF e o envio postal de um item já criado. Se você não informar o endereço, a API usa o endereço cadastrado na parte devedora do item.

Parâmetros de rota

itemIduuidobrigatório

Identificador do item de notificação.

Body

recipientobjectopcional

Sobrescreve os dados do destinatário. Se omitido, usa os dados da parte devedora do item.

notificationTemplateIduuidopcional

Sobrescreve o template de notificação. Se omitido, usa o template do lote.

recipient

namestringopcional

Nome completo do destinatário impresso na carta.

addressobjectopcional

Endereço de entrega. Se omitido, usa o endereço da parte devedora do item.

recipient.address

zipCodestring | numberobrigatório

CEP de entrega.

streetstringobrigatório

Logradouro.

numberstring | numberobrigatório

Número do imóvel.

neighborhoodstringobrigatório

Bairro.

citystringobrigatório

Cidade.

statestringobrigatório

UF, com no mínimo 2 caracteres.

complementstringopcional

Complemento do endereço.

Como funciona o envio físico

A API valida o endereço e o template.
O PDF da carta é gerado a partir do template, com as variáveis do item interpoladas.
A carta é despachada ao parceiro postal.
O status de postagem e entrega é atualizado no item conforme os retornos dos Correios.

O messageId na resposta identifica a mensagem de processamento interna — não o código de rastreio postal. Acompanhe o status do item pela listagem de itens do lote.

Endereço incompleto bloqueia o envio

CEP, logradouro, número, bairro, cidade e UF são obrigatórios — seja no cadastro da parte, seja no override. Endereço incompleto retorna 422 e a carta não é gerada.

Erros

Código	Causa
`400`	Endereço, template ou dados ausentes/inválidos
`401`	API key ausente, inválida ou inativa
`404`	Item não encontrado neste workspace
`422`	Item não validado para envio físico ou endereço inválido
`429`	Limite de requisições excedido

Requisição

curl -X POST "https://external-api.arbitralis.com.br/api/external/v1/notifications/items/7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f/send-physical" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: arb_live_SUA_CHAVE" \
  -d '{}'

const itemId = '7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f';

const response = await fetch(
  `https://external-api.arbitralis.com.br/api/external/v1/notifications/items/${itemId}/send-physical`,
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': 'arb_live_SUA_CHAVE',
    },
    body: JSON.stringify({}),
  }
);

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

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

Resposta

{
  "success": true,
  "data": {
    "messageId": "10943812734981299"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Endereço do item é inválido para envio físico.",
    "errorEventId": "b1f3c6d8-2a44-4d9e-9f10-7c5b8e2a1d33"
  }
}