Reservar o destino do documento-fonte

POST

/source-documents

curl --request POST \
  --url https://api.emmaos.com.br/source-documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "byteSize": 184320 }'

• Produção
• Staging
• Desenvolvimento

Reserva um documento-fonte e devolve uma URL assinada para o painel escrever o PDF direto no armazenamento do tribunal. O arquivo não passa pela API.

O rito

1. O painel calcula o sha256 do arquivo e chama esta rota.
2. Faz PUT na url, repetindo os headers exatamente.
3. Chama POST /notices com a key recebida aqui e o mesmo sha256.

A chave é cunhada pelo servidor: o cliente não escolhe onde escrever.

O que acontece se o ato não for criado

O objeto nasce marcado como pendente e é removido automaticamente se nenhum ato o reivindicar. Subir e desistir não deixa lixo permanente, e também não cria ato nenhum.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

O que o painel declara sobre o arquivo que vai subir.

object

sha256

required

Digest SHA-256 do arquivo, em hexadecimal minúsculo, calculado pelo painel antes de subir. Entra na URL assinada: o armazenamento recusa a gravação de um corpo que não o produza.

string

/^[0-9a-f]{64}$/

byteSize

required

Tamanho exato do arquivo. Também entra na assinatura, então a mesma URL não serve para subir outro arquivo.

integer

>= 1 <= 52428800

Example

{
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "byteSize": 184320
}

Responses

201

Destino reservado

Media typeapplication/json

O destino de escrita. Vale por minutos.

object

key

required

Cunhada pelo servidor. É esta chave que vai no POST /notices.

string

url

required

URL assinada, para um PUT direto no armazenamento.

string format: uri

expiresAt

required

Quando a URL deixa de valer. Vencida é caso normal, não erro: peça outra.

string format: date-time

headers

required

Os cabeçalhos que o PUT tem que repetir exatamente. Eles estão na assinatura; mudar qualquer um invalida a URL.

object

key

additional properties

string

Example

{
  "key": "tenants/demo/notices/2026/019928f4-3c21-7a4b-8f0e-6c2d5b1a9f78.pdf",
  "url": "https://sid-prod-demo-documents.s3.sa-east-1.amazonaws.com/tenants/demo/notices/2026/019928f4-3c21-7a4b-8f0e-6c2d5b1a9f78.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expiresAt": "2026-09-19T12:10:00.000Z",
  "headers": {
    "content-type": "application/pdf",
    "content-length": "184320",
    "x-amz-checksum-sha256": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
    "x-amz-tagging": "state=pending"
  }
}

400

Requisição inválida

Media typeapplication/json

object

error

required

Código estável do erro. É por ele que se programa.

string

Allowed values: INVALID_REQUEST INVALID_JSON NOT_FOUND NOT_IMPLEMENTED TIMELINE_TOO_LONG DATABASE_RESUMING INTERNAL_ERROR SEALED_DOCUMENT_MISSING DISPATCH_IN_PROGRESS IDEMPOTENCY_KEY_CONFLICT SEALED_DOCUMENT_TOO_LARGE SOURCE_DOCUMENT_TOO_MANY_PAGES SOURCE_DOCUMENT_UNREADABLE STORAGE_LIMIT_REACHED TENANT_NOT_CONFIGURED

field

Campo que causou a recusa, quando aplicável.

string

message

Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.

string

missing

Só com TENANT_NOT_CONFIGURED: o que falta na configuração do tribunal.

Array<string>

Allowed values: displayName publicPhone whatsappSender

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"
}

401

Sem header Authorization. Recusado pelo API Gateway antes de chegar à aplicação.

403

Token inválido, expirado, ou de um emissor que não é tribunal conhecido neste stage. Recusado pelo authorizer.

413

Arquivo acima do limite de 19 MB (o teto de 20 MB do documento selado, menos a sobra da página de conferência). Nada foi reservado.

Media typeapplication/json

object

error

required

Código estável do erro. É por ele que se programa.

string

Allowed values: INVALID_REQUEST INVALID_JSON NOT_FOUND NOT_IMPLEMENTED TIMELINE_TOO_LONG DATABASE_RESUMING INTERNAL_ERROR SEALED_DOCUMENT_MISSING DISPATCH_IN_PROGRESS IDEMPOTENCY_KEY_CONFLICT SEALED_DOCUMENT_TOO_LARGE SOURCE_DOCUMENT_TOO_MANY_PAGES SOURCE_DOCUMENT_UNREADABLE STORAGE_LIMIT_REACHED TENANT_NOT_CONFIGURED

field

Campo que causou a recusa, quando aplicável.

string

message

Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.

string

missing

Só com TENANT_NOT_CONFIGURED: o que falta na configuração do tribunal.

Array<string>

Allowed values: displayName publicPhone whatsappSender

Example

{
  "error": "INVALID_REQUEST",
  "missing": [
    "displayName"
  ]
}

500

Erro interno

Media typeapplication/json

object

error

required

Código estável do erro. É por ele que se programa.

string

Allowed values: INVALID_REQUEST INVALID_JSON NOT_FOUND NOT_IMPLEMENTED TIMELINE_TOO_LONG DATABASE_RESUMING INTERNAL_ERROR SEALED_DOCUMENT_MISSING DISPATCH_IN_PROGRESS IDEMPOTENCY_KEY_CONFLICT SEALED_DOCUMENT_TOO_LARGE SOURCE_DOCUMENT_TOO_MANY_PAGES SOURCE_DOCUMENT_UNREADABLE STORAGE_LIMIT_REACHED TENANT_NOT_CONFIGURED

field

Campo que causou a recusa, quando aplicável.

string

message

Texto em português para diagnóstico. Não programe contra ele: pode mudar sem aviso.

string

missing

Só com TENANT_NOT_CONFIGURED: o que falta na configuração do tribunal.

Array<string>

Allowed values: displayName publicPhone whatsappSender

Example

{
  "error": "INTERNAL_ERROR"
}