Registrar um ato

POST /notices
Authorization: Bearer <access token>
Idempotency-Key: 7f1c9f2e-2d55-4d0a-9a7f-2f1e6a3c1b04
Content-Type: application/json

{
  "noticeType": "SUMMONS",
  "recipient": {
    "name": "Maria de Souza",
    "cpf": "12345678909",
    "phone": "5571999998888"
  },
  "case": {
    "number": "0801234-56.2026.8.05.0001",
    "courtDivision": "1ª Vara Cível",
    "subjectMatter": "Cobrança",
    "plaintiffName": "Município de Sítio Novo",
    "plaintiffLawyer": null,
    "defendantName": "Maria de Souza",
    "defendantLawyer": null
  },
  "sourceDocument": {
    "key": "tenants/demo/notices/2026/mandado.pdf",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  },
  "customFields": {
    "processoOrigem": {
      "label": "Processo de origem",
      "type": "TEXT",
      "value": "0801111-22.2025.8.05.0001"
    }
  },
  "deadlineAt": "2026-10-01T02:59:59.999Z"
}

Resposta 201:

{
  "id": "019928f4-3c21-7a4b-8f0e-6c2d5b1a9f77",
  "protocol": "2026.0000.0001",
  "status": "PENDING"
}

Os campos completos estão na referência.

A chave de idempotência é obrigatória

O cabeçalho Idempotency-Key não é opcional. Sem ele a requisição é recusada com 400.

Gere um valor novo por ato (um UUID serve) e reutilize o mesmo valor ao repetir a chamada. É isso que torna seguro repetir depois de um timeout de rede, quando você não sabe se o ato chegou a ser criado.

Situação	Resposta
Chave nova	201 com o ato criado
Chave já usada neste órgão	200 com o mesmo registro, sem criar nada

Repare que o corpo é idêntico nos dois casos: é o código de status que diz se algo novo nasceu. Se sua integração precisa saber a diferença, olhe o status, não o corpo.

A chave é única por órgão. Duas instituições podem usar a mesma sem se atrapalhar.

O que o protocolo promete

O protocol é o identificador legível do ato: ano de Brasília mais uma sequência. É o número que uma pessoa cita ao telefone.

Ele é monotônico, mas não contíguo.

Não use o protocolo para contar atos

Tanto uma transação abortada quanto a repetição de uma chave já usada consomem um número da sequência sem gerar ato novo. Lacunas são normais e esperadas.

O protocolo identifica um ato; ele não conta atos. Um relatório que deduza volume da diferença entre dois protocolos vai errar.

O id é um UUIDv7 e é o que se usa nas rotas. O protocolo é para humanos.

Campos personalizados

customFields carrega os campos específicos do seu órgão. Cada um traz o rótulo, o tipo e o valor.

Eles são congelados no ato no momento do registro: se o formulário do órgão mudar depois, os atos já criados continuam com o rótulo e o valor que tinham na hora. Isso é deliberado: o ato precisa poder ser lido anos depois como foi cadastrado.

Tipos aceitos: TEXT, DATE, CPF e SELECT.

Campos que o órgão definiu

Cada órgão pode definir campos próprios para o cadastro. GET /custom-field-definitions devolve a lista do órgão do seu token: chave, rótulo, tipo, se é obrigatório (required), se está arquivado (archived) e, no SELECT, as opções, cada uma com value e label. Órgão sem campo definido recebe items: []. Uma mudança na lista vale em até 5 minutos.

Para um campo definido e não arquivado, o registro confere o seguinte:

• o type tem de ser o da definição;
• o valor tem de caber no tipo: TEXT até 500 caracteres, DATE no formato AAAA-MM-DD e numa data que exista, CPF com os 11 dígitos e dígito verificador válido, SELECT igual ao value de uma das opções;
• o campo obrigatório não pode faltar (ausente, nulo ou vazio contam como ausente);
• o label gravado no ato é o da definição, e não o que o pedido mandou;
• no SELECT, o ato ganha também optionLabel, o rótulo da opção escolhida, carimbado pelo emMãos. O optionLabel que o pedido mandar é ignorado.

Um campo arquivado não é exigido, e a chave dele é recusada: o registro responde 400 apontando customFields.<chave>, sem gastar protocolo. Uma chave arquivada não volta a ser usada; os atos antigos que a guardam continuam mostrando o valor.

Uma chave que nenhuma definição lista continua aceita como sempre foi. A integração que manda uma chave própria, como processoOrigem, segue funcionando. Por isso um erro de digitação na chave de um campo definido não é recusado: vira um campo solto no ato. Confira a chave contra a lista do órgão.

Mudar a definição vale só para os atos novos. Os atos já criados guardam o valor e os rótulos que tinham.

O documento

sourceDocument identifica o documento pela chave no armazenamento e pelo digest sha256 em hexadecimal. O upload em si ainda não faz parte desta API.