Registrar um ato
const url = 'https://api.emmaos.com.br/notices';const options = { method: 'POST', headers: { 'Idempotency-Key': '7f1c9f2e-2d55-4d0a-9a7f-2f1e6a3c1b04', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"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/019928f4-3c21-7a4b-8f0e-6c2d5b1a9f78.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"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.emmaos.com.br/notices \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: 7f1c9f2e-2d55-4d0a-9a7f-2f1e6a3c1b04' \ --data '{ "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/019928f4-3c21-7a4b-8f0e-6c2d5b1a9f78.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" }'Registra o ato e o evento NOTICE_CREATED na mesma transação, e devolve
o protocolo: o identificador legível do ato, formado pelo ano de
Brasília e uma sequência do banco.
Idempotência
O header Idempotency-Key é obrigatório e é único por tribunal. Repetir
a mesma chave com o mesmo pedido (mesmo destinatário, processo,
tipo, documento, prazo e campos personalizados, pelo mesmo servidor)
devolve o mesmo registro com 200 em vez de 201: é seguro repetir
depois de um timeout de rede. A chave do upload pode mudar entre as
tentativas; o sha256 do documento é que conta.
Repetir a chave com um pedido diferente, ou vindo de outro
servidor, é 409 IDEMPOTENCY_KEY_CONFLICT: a resposta não traz o id nem
o protocolo do ato guardado. Use uma chave nova para o ato novo.
A validação do corpo (tipos, CPF, telefone, tipo de ato) roda antes de
reservar o protocolo: um 400 não consome número. Entra nela a
conferência dos customFields contra a definição do tribunal (ver
GET /custom-field-definitions): a chave de um campo arquivado é
400 em customFields.<chave>.
O protocolo é monotônico, mas não promete contiguidade: tanto uma
transação abortada quanto a repetição de uma chave já usada consomem um
número (um 400 de validação não consome). O protocolo identifica o ato, não conta atos.
Documento selado
Antes de gravar o ato, a API gera o documento selado: o
documento-fonte com uma página de conferência acrescentada,
com o protocolo, o QR do endereço de conferência do tribunal e o
sha256 do fonte. É ele, e não o fonte, que o cidadão recebe. O selado
não aparece na resposta. Por isso esta rota lê o PDF inteiro e pode
levar mais tempo com documentos grandes.
Authorizations
Seção intitulada “Authorizations”Parameters
Seção intitulada “Parameters”Header Parameters
Seção intitulada “Header Parameters”Chave única por tribunal que torna a repetição segura. Gere um valor novo por ato (um UUID serve).
Example
7f1c9f2e-2d55-4d0a-9a7f-2f1e6a3c1b04Request Bodyrequired
Seção intitulada “Request Bodyrequired”object
Natureza do ato a comunicar.
object
Nome do destinatário.
CPF, só dígitos (11), com os dígitos verificadores corretos. Um CPF com dígito errado ou de dígitos repetidos (00000000000) é recusado com INVALID_REQUEST em recipient.cpf.
Telefone em E.164 brasileiro, só dígitos: 55 + DDD existente + número. Celular tem 9 dígitos e começa em 9 (5571999998888); fixo tem 8 dígitos e começa de 2 a 5 (557132345678). Número estrangeiro é recusado. Por compatibilidade, a API aceita o número nacional de 10 ou 11 dígitos, com ou sem máscara e +, e acrescenta o 55; o que não fecha o formato é recusado com INVALID_REQUEST em recipient.phone.
E-mail do destinatário, para a cópia do documento por e-mail.
Opcional. Só é gravado se o tribunal estiver com a cópia ligada;
com ela desligada o campo é aceito e descartado sem conferir, e o
ato nasce com null. Ligada, o endereço é conferido (ASCII, sem
espaço, vírgula, ponto e vírgula nem <>()"\) e um endereço
inválido é recusado com INVALID_REQUEST em recipient.email.
A resposta de GET /notices/{id} devolve o endereço; a listagem
nunca devolve.
object
Número do processo.
Vara. É propriedade do ato, não do usuário.
O documento que o tribunal manda comunicar.
A key não é escolhida pelo cliente: ela vem de
POST /source-documents, que a cunha no servidor. Enviar uma chave que
não veio de lá é recusado com 400.
object
Chave do objeto, na forma tenants/{tenant}/notices/{ano}/{uuidv7}.pdf,
devolvida por POST /source-documents. O tenant na chave tem que
ser o do token.
Digest SHA-256 do arquivo, em hexadecimal minúsculo. Conferido contra o que o armazenamento calculou na gravação: se divergir, o ato não é criado.
Campos personalizados, indexados pelo nome do campo. A chave que o
tribunal definiu (GET /custom-field-definitions) é conferida e leva o
rótulo da definição; a chave que ninguém definiu passa como veio.
object
Campo específico do tribunal, congelado no ato no momento do registro: mudar o formulário depois não altera atos já criados.
object
Tipo de um campo personalizado do tribunal.
Só em campo SELECT definido pelo tribunal: o rótulo da opção cujo
value o ato guardou, carimbado pelo servidor a partir da definição
do dia. Ignorado no pedido. Ato antigo pode não tê-lo; a tela então
mostra o value.
Prazo do ato, se houver.
Example
{ "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/019928f4-3c21-7a4b-8f0e-6c2d5b1a9f78.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"}Responses
Seção intitulada “Responses”Repetição de uma Idempotency-Key já usada. Devolve o registro
original, sem criar nada.
object
UUIDv7 gerado pela aplicação.
Identificador legível do ato: ano de Brasília e sequência do banco.
Progresso operacional do ato.
Example
{ "protocol": "2026.0000.0001", "status": "PENDING"}Ato criado
object
UUIDv7 gerado pela aplicação.
Identificador legível do ato: ano de Brasília e sequência do banco.
Progresso operacional do ato.
Example
{ "id": "019928f4-3c21-7a4b-8f0e-6c2d5b1a9f77", "protocol": "2026.0000.0001", "status": "PENDING"}Requisição inválida
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Examples
Campo obrigatório ausente ou malformado
{ "error": "INVALID_REQUEST", "field": "noticeType", "message": "noticeType é obrigatório"}Corpo não é JSON válido
{ "error": "INVALID_JSON", "message": "corpo JSON inválido"}Sem header Authorization. Recusado pelo API Gateway antes de chegar à
aplicação.
Token inválido, expirado, ou de um emissor que não é tribunal conhecido neste stage. Recusado pelo authorizer.
IDEMPOTENCY_KEY_CONFLICT: a Idempotency-Key já guarda um ato
diferente deste pedido (outro corpo, ou outro servidor). Nada foi
criado e o corpo não revela o ato guardado.
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Example
{ "error": "IDEMPOTENCY_KEY_CONFLICT", "message": "Esta Idempotency-Key já foi usada para um ato diferente. Use outra chave para registrar este ato."}O documento passa de um dos tetos. Nenhum ato foi criado e nada foi gravado, mas um número de protocolo foi consumido (ver acima: o protocolo não promete contiguidade). O código diz qual teto:
SOURCE_DOCUMENT_TOO_MANY_PAGES: o documento-fonte tem mais de 100 páginas. É preciso subir um documento menor.SEALED_DOCUMENT_TOO_LARGE: o documento selado passaria de 20 MB.
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Examples
Fonte acima do teto de páginas
{ "error": "SOURCE_DOCUMENT_TOO_MANY_PAGES", "field": "sourceDocument.key", "message": "documento-fonte tem 101 páginas; o limite é 100"}Selado acima do teto de bytes
{ "error": "SEALED_DOCUMENT_TOO_LARGE", "field": "sourceDocument.key", "message": "documento selado excede o limite de 20971520 bytes"}O pedido está bem formado, mas não pode ser atendido. O código diz por quê:
SOURCE_DOCUMENT_UNREADABLE: o documento-fonte não abre como PDF, ou é criptografado. Nenhum ato foi criado, mas um número de protocolo foi consumido: o selo roda depois de reservar o protocolo (ver acima: o protocolo não promete contiguidade). Repetir dá o mesmo resultado: é preciso subir o documento sem senha, por um novoPOST /source-documents.STORAGE_LIMIT_REACHED: o tribunal atingiu o limite de armazenamento configurado, e o modo dele é recusar atos novos. Nada foi criado nem gravado, e nenhum número de protocolo foi consumido. Repetir não resolve até o limite ser alterado ou o consumo baixar. Só acontece em tribunal que tem limite configurado; o padrão é não ter. Um retry deIdempotency-Keyde um ato que já existe não é recusado: volta200com o ato.
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Examples
Fonte que não abre como PDF
{ "error": "SOURCE_DOCUMENT_UNREADABLE", "field": "sourceDocument.key", "message": "o documento-fonte é criptografado; o tribunal precisa enviá-lo sem senha"}Tribunal no limite de armazenamento, com recusa ligada
{ "error": "STORAGE_LIMIT_REACHED", "message": "O tribunal atingiu o limite de armazenamento configurado."}Erro interno
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Example
{ "error": "INTERNAL_ERROR"}O banco do tribunal estava pausado e não retomou dentro do orçamento da requisição. Repita.
object
Código estável do erro. É por ele que se programa.
Campo que causou a recusa, quando aplicável.
Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.
Só com TENANT_NOT_CONFIGURED: o que falta na configuração do
tribunal.
Example
{ "error": "DATABASE_RESUMING", "message": "Banco de dados está retomando. Tente novamente."}Headers
Seção intitulada “Headers”Segundos a esperar antes de repetir.