API

API

Marque e detecte arquivos com a API do Markedfile. Disponível nos planos Business e Enterprise.

Chaves de API

O proprietário de um espaço de trabalho Business ou Enterprise cria e revoga as chaves nas configurações do espaço. Uma chave é exibida uma única vez. O Markedfile armazena um hash SHA-256, um prefixo curto e o nome. Ele não armazena o segredo.

Uma chave pertence a exatamente um espaço de trabalho. Ela só atua nele, com os limites do plano desse espaço. Espaços pessoais não têm chaves. Um membro que não é o proprietário não pode criá-las nem revogá-las.

Se o espaço de trabalho perder o plano Business ou Enterprise ativo, todas as chaves param de funcionar imediatamente, inclusive durante os 30 dias em que os arquivos existentes ainda podem ser detectados no aplicativo. Ao voltar para o Business ou o Enterprise, as chaves que não foram revogadas voltam a funcionar.

Autenticação

Envie o segredo no cabeçalho Authorization como um token Bearer. Estas rotas não usam cookie de sessão. Um navegador em outro site é recusado.

Auditoria

Criar, revogar, marcar e detectar gravam uma linha de auditoria que o proprietário do espaço de trabalho pode ler. A linha não inclui o arquivo.

Endpoints

POST/api/v1/mark

Marca um arquivo e devolve a cópia marcada. O corpo é multipart/form-data.

Autenticação

Authorization: Bearer mf_…

Envie este cabeçalho. Não há cookie de sessão. O curl e outros clientes de servidor são aceitos. Um navegador em outro site é recusado.

Parâmetros

NomeTipoObrigatórioDescrição
filefileSimO arquivo a ser marcado. Business e Enterprise aceitam até 100 MB, 500 páginas de PDF e vídeo de até 10 minutos. O tamanho do envio, a duração do vídeo e o número de páginas do PDF seguem o plano do espaço de trabalho.
identifierstringSimDe 1 a 32 caracteres, sem caracteres de controle. É o rótulo que você vê se essa cópia for detectada depois. Ele não é gravado no arquivo como texto legível.

Requisição

curl -X POST https://markedfile.com/api/v1/mark \
  -H "Authorization: Bearer mf_…" \
  -F "file=@contract.pdf" \
  -F "identifier=northwind"

Resposta

{
  "file": "JVBERi0xLjQK…",
  "mime": "application/pdf",
  "name": "contract.pdf",
  "kind": "pdf",
  "layers": [
    {
      "name": "Metadata",
      "detail": "Authenticated workspace reference; the identifier stays on the server",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "remaining": 1
}

file são os bytes marcados em base64. mime, name e kind descrevem o download. layers lista as camadas que foram aplicadas. Quando o plano não tem limite de arquivos ativos, remaining é o número de arquivos ativos depois desta marca. Quando tem limite, remaining é quantas marcas novas ainda restam. Business e Enterprise não têm limite de arquivos ativos. É a exclusão de um arquivo que encerra a detecção.

Erros

O texto do campo error no corpo JSON está em inglês.

StatusDescrição
400O arquivo está vazio, ou o identificador está vazio, tem mais de 32 caracteres ou contém um caractere de controle.
401A chave está ausente, foi revogada ou é desconhecida. O corpo JSON inclui "code": "api-key".
403O espaço de trabalho não tem mais um plano Business ou Enterprise ativo (o corpo inclui "code": "enterprise"), ou o navegador enviou uma requisição cross-site ou same-site.
413O arquivo passa do limite de envio do plano, ou o PDF tem mais páginas do que o plano permite.
422Não foi possível processar o arquivo.
429Esta chave marcou mais de 40 arquivos no minuto atual.

Limite de requisições

40 requisições por minuto para esta chave. O contador fica no banco de dados do produto e continua valendo depois de uma reinicialização.

POST/api/v1/detect

Verifica um arquivo no espaço de trabalho desta chave. O corpo é multipart/form-data.

Autenticação

Authorization: Bearer mf_…

Envie este cabeçalho. Não há cookie de sessão. O curl e outros clientes de servidor são aceitos. Um navegador em outro site é recusado.

Parâmetros

NomeTipoObrigatórioDescrição
filefileSimO arquivo a ser verificado. A correspondência é procurada só no espaço de trabalho desta chave. Um arquivo marcado em outro espaço de trabalho não é identificado. Um espaço Business ou Enterprise ativo também pode verificar um arquivo de vídeo. A captura de tela de um único quadro é verificada como imagem.

Requisição

curl -X POST https://markedfile.com/api/v1/detect \
  -H "Authorization: Bearer mf_…" \
  -F "file=@leaked.pdf"

Resposta

{
  "id": "northwind",
  "confidence": 0.95,
  "layers": [
    {
      "name": "Metadata",
      "hit": true,
      "detail": "Authenticated metadata matched this workspace",
      "screenshot": "No",
      "crop": "No",
      "reencode": "No"
    }
  ],
  "notes": [
    "Confidence is 99% for an exact file or when an authenticated mark agrees with another mark. A visual match alone stays lower, and weak bit agreement stays far from a high score."
  ]
}

id é o identificador que você definiu quando essa cópia foi marcada, ou null quando este espaço de trabalho não tem correspondência. confidence é de 99% para um arquivo exato ou quando uma marca autenticada concorda com outra marca. Uma correspondência apenas visual fica mais baixa. layers lista as camadas, e hit é true nas que concordaram. notes descreve o que a verificação fez. Um arquivo excluído não é identificado.

Erros

O texto do campo error no corpo JSON está em inglês.

StatusDescrição
400O arquivo está vazio.
401A chave está ausente, foi revogada ou é desconhecida. O corpo JSON inclui "code": "api-key".
403O espaço de trabalho não tem mais um plano Business ou Enterprise ativo (o corpo inclui "code": "enterprise"), ou o navegador enviou uma requisição cross-site ou same-site.
413O arquivo passa do limite de envio do plano, ou o PDF tem mais páginas do que o plano permite.
422Não foi possível processar o arquivo.
429Esta chave fez mais de 80 detecções no minuto atual.

Limite de requisições

80 requisições por minuto para esta chave. O contador fica no banco de dados do produto e continua valendo depois de uma reinicialização.