Documentação da API

Visão geral

A API recebe arquivos PDF, cria trabalhos assíncronos de tarjamento e fornece uma URL temporária para baixar o resultado. Todas as respostas usam JSON, exceto o envio do PDF, que usa multipart/form-data.

URL base
https://api.tarjadoc.com

Endpoints versionados
https://api.tarjadoc.com/v1/...

O fluxo recomendado é: autenticar, enviar o PDF, guardar o task_id, consultar o status até done e baixar o arquivo por output_url.

Autenticação

Use uma chave de API em uma das formas abaixo. Para integrações de servidor, prefira X-API-Key. Nunca exponha a chave em código do navegador ou em repositórios.

X-API-Key: sk_live_SUA_CHAVE

# ou
Authorization: Bearer sk_live_SUA_CHAVE

O token JWT retornado no login também pode ser enviado como Bearer. Chaves expiradas, revogadas ou inválidas retornam 401.

Conta

POST /v1/auth/register envia um código de confirmação. A conta só é criada após POST /v1/auth/register/verify com o código recebido por e-mail.

curl -X POST https://api.tarjadoc.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria@empresa.com.br",
    "password": "uma-senha-segura",
    "cpf_cnpj": "12345678000190"
  }'

A resposta inclui user_id, email, name, access_token, token_type, expires_in e message. O campo cpf_cnpj é opcional.

POST /v1/auth/login recebe email e password em JSON e retorna um JWT. GET /v1/auth/me retorna os dados da conta autenticada.

curl https://api.tarjadoc.com/v1/auth/me \
  -H "X-API-Key: sk_live_SUA_CHAVE"

Chaves de API

O acesso por chave de API faz parte dos planos pagos, que estão em breve. Entre em contato para conversar sobre uma integração.

GET /v1/keys lista as chaves e seus metadados, sem revelar o segredo. POST /v1/keys cria uma chave e mostra o valor completo somente na resposta de criação.

curl -X POST https://api.tarjadoc.com/v1/keys \
  -H "Authorization: Bearer SEU_TOKEN_OU_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"name":"integração produção","expires_in_days":90}'

expires_in_days é opcional; sem ele, a chave não expira. Para revogar, use DELETE /v1/keys/{key_id}. A revogação retorna 204 No Content.

Enviar um PDF

POST /v1/redact aceita um PDF de até 50 MB e responde com 202 Accepted.

curl -X POST https://api.tarjadoc.com/v1/redact \
  -H "X-API-Key: sk_live_SUA_CHAVE" \
  -F "file=@contrato.pdf" \
  -F "detect=cpf,rg,cnpj,email,phone,cep,cnh,pis,oab,name,address" \
  -F "profile=fast" \
  -F "color=#000000"

file é obrigatório. detect, profile e color são opcionais; a cor deve estar em hexadecimal. O perfil fast (padrão) usa texto pesquisável e regras; complete adiciona OCR e GLiNER; rigorous inclui NuExtract e verificação final.

{
  "task_id": "2c4a73c8-...",
  "status": "queued",
  "message": "Documento recebido e enfileirado para tarjamento.",
  "pages_processed": 0,
  "entities_detected": 0,
  "entities_redacted": 0,
  "output_url": null,
  "output_expires_at": null
}

Listar documentos

GET /v1/redact lista os documentos da conta, do mais recente para o mais antigo.

curl "https://api.tarjadoc.com/v1/redact?page=1&page_size=10&search=contrato" \
  -H "X-API-Key: sk_live_SUA_CHAVE"

page começa em 1, page_size aceita de 1 a 50 e search filtra pelo nome do arquivo. A resposta contém items, page, page_size e total.

Uso mensal

GET /v1/redact/usage informa a franquia do ciclo e também reserva as páginas de trabalhos ainda em processamento.

{
  "period": "2026-08",
  "pages_used": 12,
  "pages_limit": 50,
  "pages_reserved": 8,
  "pages_available": 30
}

Status e download

GET /v1/redact/{task_id} consulta um trabalho da conta. Faça novas consultas com intervalo entre as requisições até o status final.

curl https://api.tarjadoc.com/v1/redact/2c4a73c8-... \
  -H "X-API-Key: sk_live_SUA_CHAVE"

Os estados são queued, redacting, verifying, correcting, done e failed. Em done, output_url traz um link assinado válido por tempo limitado. Em failed, consulte error_message.

Excluir um documento

DELETE /v1/redact/{task_id} remove definitivamente o PDF original, o resultado e os metadados. Trabalhos em processamento retornam 409 e só podem ser excluídos após terminarem.

curl -X DELETE https://api.tarjadoc.com/v1/redact/2c4a73c8-... \
  -H "X-API-Key: sk_live_SUA_CHAVE"

Planos

GET /v1/billing/plans é público e lista franquias, preços e recursos. Os planos pagos estão em breve; para conversar sobre acesso, escreva para contato@tarjadoc.com.br.

Erros e limites

Erros de validação usam o formato JSON do FastAPI, normalmente com o campo detail. Trate o código HTTP antes de ler o corpo.