POST/v1/uploads/{upload_id}/complete

Concluir um upload

complete_upload

Quando todas as partes foram recebidas, o Sursa monta o arquivo, compara o SHA-256 do arquivo inteiro com o sha256 do corpo e executa as mesmas conferências do upload em uma única requisição: o formato pela assinatura do conteúdo e a varredura antivírus. O resultado é ready, ou rejected com reject_reason (checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content). Cada rejeição pela conferência de formato ou pelo antivírus é gravada no registro de auditoria como file.rejected.

Uma resposta 200 significa que o resultado está pronto; 202 significa que o arquivo ainda está sendo conferido (processing), e o resultado vem de GET /v1/uploads/{upload_id}. Se o status voltar para pending (o reinício de uma instância da API interrompeu a conferência), envie complete de novo. Repetir complete depois do resultado retorna o mesmo resultado. Partes faltando retornam 409 uploads.incomplete (details.missing). Um sha256 diferente do declarado na criação, ou um parts[].etag diferente de uma parte recebida, retorna 422 uploads.checksum_mismatch. Um upload pronto que não é usado fica disponível por 24 horas. Adicionado na versão 1.62.0.

Autenticação

Envie uma chave de API no cabeçalho Authorization: Authorization: Bearer <chave>.

Parâmetros de caminho

upload_idstringobrigatório
O ID do upload (upl_ seguido de 32 caracteres hexadecimais).
length ≤ 64

Parâmetros de cabeçalho

Idempotency-Keystring
Chave para uma nova tentativa segura de uma gravação: de 1 a 255 caracteres ASCII imprimíveis; recomenda-se um UUID v4 por operação lógica. Uma nova tentativa com a mesma chave dentro de 24 horas não executa a operação de novo: retorna a resposta salva (status, cabeçalhos e corpo) com o cabeçalho Idempotency-Replayed: true. A mesma chave com outro método, caminho, Content-Type ou corpo retorna 409 api.idempotency_mismatch; enquanto a primeira requisição ainda está em execução, 409 api.idempotency_in_progress com Retry-After: 1. Depois de uma resposta 5xx ou 429, a chave é liberada, e uma nova tentativa executa a operação de novo. A chave vale para a organização e para quem faz a chamada (chave de API, usuário ou chave de fonte personalizada).
length ≥ 1, length ≤ 255

Corpo da requisição

application/json

Objeto: UploadComplete

sha256stringobrigatório
O SHA-256 do arquivo inteiro.
partsarray of UploadPartRef
Conferência opcional das partes: o ETag de cada parte, como retornado por PUT …/parts/{n}.
items ≤ 1000

Respostas

200O resultado está pronto: `ready` ou `rejected`.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.
Idempotency-Replayed
true significa que a resposta foi reproduzida a partir da resposta salva para esta Idempotency-Key: a operação não foi executada de novo.

application/json

Objeto: Upload

idstringobrigatório
O ID do upload (upl_ seguido de 32 caracteres hexadecimais).
purposeUploadPurposeobrigatório
filenamestringobrigatório
O nome do arquivo (sem pastas).
content_typestringobrigatório
O tipo de conteúdo declarado; vazio se não foi declarado.
sizeinteger (int64)obrigatório
O tamanho do arquivo em bytes.
sha256string | nullobrigatório
O SHA-256 do arquivo, declarado na criação ou em complete; null se ainda não for conhecido.
statusUploadStatusobrigatório
part_sizeinteger (int64)obrigatório
O tamanho de cada parte, exceto a última (de 5 a 100 MiB).
part_countintegerobrigatório
O número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobrigatório
O número de partes recebidas.
≥ 0
partsarray of UploadPartobrigatório
As partes recebidas, por número (vazio na resposta de POST /v1/uploads).
reject_reasonstring | nullobrigatório
O motivo da rejeição (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. A enumeração pode crescer; null se não houve rejeição.
reject_detailsobject | nullobrigatório
Detalhes da rejeição (a extensão, o formato declarado e o detectado, as somas de verificação); null se não houve rejeição.
created_atstring (date-time)obrigatório
Quando o upload foi criado.
expires_atstring (date-time)obrigatório
O prazo para concluir o upload e, depois que ele estiver pronto, para usá-lo.
completed_atstring (date-time) | nullobrigatório
Quando a conferência terminou (ready ou rejected).
consumed_atstring (date-time) | nullobrigatório
Quando o upload foi usado (por um cartão, um arquivo compactado ou uma importação).

202O arquivo ainda está sendo conferido (`processing`).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.
Idempotency-Replayed
true significa que a resposta foi reproduzida a partir da resposta salva para esta Idempotency-Key: a operação não foi executada de novo.

application/json

Objeto: Upload

idstringobrigatório
O ID do upload (upl_ seguido de 32 caracteres hexadecimais).
purposeUploadPurposeobrigatório
filenamestringobrigatório
O nome do arquivo (sem pastas).
content_typestringobrigatório
O tipo de conteúdo declarado; vazio se não foi declarado.
sizeinteger (int64)obrigatório
O tamanho do arquivo em bytes.
sha256string | nullobrigatório
O SHA-256 do arquivo, declarado na criação ou em complete; null se ainda não for conhecido.
statusUploadStatusobrigatório
part_sizeinteger (int64)obrigatório
O tamanho de cada parte, exceto a última (de 5 a 100 MiB).
part_countintegerobrigatório
O número de partes.
≥ 1, ≤ 1000
parts_receivedintegerobrigatório
O número de partes recebidas.
≥ 0
partsarray of UploadPartobrigatório
As partes recebidas, por número (vazio na resposta de POST /v1/uploads).
reject_reasonstring | nullobrigatório
O motivo da rejeição (rejected): checksum_mismatch, type_mismatch, unsupported_format, infected, scan_unavailable, unsafe_content. A enumeração pode crescer; null se não houve rejeição.
reject_detailsobject | nullobrigatório
Detalhes da rejeição (a extensão, o formato declarado e o detectado, as somas de verificação); null se não houve rejeição.
created_atstring (date-time)obrigatório
Quando o upload foi criado.
expires_atstring (date-time)obrigatório
O prazo para concluir o upload e, depois que ele estiver pronto, para usá-lo.
completed_atstring (date-time) | nullobrigatório
Quando a conferência terminou (ready ou rejected).
consumed_atstring (date-time) | nullobrigatório
Quando o upload foi usado (por um cartão, um arquivo compactado ou uma importação).

401Nenhuma credencial foi enviada (nem cookie de sessão nem chave de API), ou a chave não foi encontrada.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

403A ação não é permitida: a função é insuficiente, não há acesso à coleção ou ao cartão, a requisição é executada no modo “View as” ou a organização está suspensa ou excluída (`detail` é um objeto com `code: org_suspended | org_deleted`).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

404O objeto não existe ou não está disponível para você. A API não confirma que um objeto restrito existe.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

409O estado do objeto não permite a ação, por exemplo, uma duplicata, uma indexação em andamento ou um job já processado.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

410O objeto existiu, mas não está mais disponível: o link foi usado ou expirou, ou o arquivo foi excluído no fim do período de retenção.

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

422Erro de validação: o corpo ou os parâmetros não correspondem ao esquema (`detail` é uma lista de erros de validação), ou o valor de um parâmetro está fora do intervalo (`detail` é uma mensagem).

Cabeçalhos da resposta

RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

429Requisições demais (`api.rate_limited`), a cota da organização para o minuto, o dia ou o mês se esgotou (`api.quota_exceeded`; `error.details` contém `quota`, `limit` e `reset_at`), o limite da organização foi atingido ou o serviço de respostas está ocupado (`answers.engine_busy`). Aguarde o tempo indicado no cabeçalho `Retry-After`.

Cabeçalhos da resposta

Retry-After
Número de segundos a esperar antes de tentar a requisição novamente.
RateLimit-Policy
Limites em vigor, no formato do rascunho da IETF draft-ietf-httpapi-ratelimit-headers: itens separados por vírgula "<name>";q=<quota>;w=<window in seconds>. key é a taxa de requisições da chave de API (a cota é a rajada, a janela é o tempo para reabastecê-la por completo; para uma sessão é user, sem credenciais é ip); minute, day e month são as cotas da organização para o minuto, o dia e o mês do calendário em UTC.
RateLimit
O que resta de cada limite de RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite da entrada mais restritiva de RateLimit-Policy (a que tem menos requisições restantes).
X-RateLimit-Remaining
Requisições restantes no limite mais restritivo.
X-RateLimit-Reset
Segundos até o limite mais restritivo ser reiniciado.

application/json

Objeto: Error

Códigos de erro

Códigos que este endpoint pode retornar em error.code, além dos códigos gerais de qualquer requisição.

Novas tentativas seguras

Envie um cabeçalho Idempotency-Key (por exemplo, um UUID) em cada POST e PATCH. Uma nova tentativa com a mesma chave em até 24 horas retorna a resposta salva, em vez de executar a requisição de novo.

Limites de taxa

As respostas trazem os cabeçalhos RateLimit e RateLimit-Policy e os anteriores X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Uma resposta 429 traz Retry-After em segundos: aguarde e tente de novo.

← uploads · Referência da API

curl -X POST 'https://api.sursa.com/v1/uploads/UPLOAD_ID/complete' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"sha256":"0123456789abcdefABCDEF0123456789abcdefABCDEF0123456789abcdefABCD"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Testar

Chave de API

A chave fica na memória desta aba e é enviada só para https://api.sursa.com.

As requisições atuam sobre os dados reais da sua organização.

Idempotency-Key header

upload_id path *

Idempotency-Key

Com o campo vazio, uma nova chave é gerada para cada requisição.

Corpo da requisição (JSON)