Pular para o conteúdo
DocAuto
API REST

Referência da API

O contrato HTTP público da DocAuto. Comece pelo fluxo recomendado e consulte cada endpoint na referência.

Atualizado em junho de 2026

Base e formato

A API cobre todo o fluxo de geração. Base de produção: https://api.docauto.com.br, com prefixo /api/v1. Documentação interativa (Swagger) em /docs e o esquema em /openapi.json. As respostas são JSON, exceto upload (multipart) e download (binário). Cada operação tem um operationId estável (ex.: templates_upload), então dá para gerar um cliente tipado a partir do OpenAPI.

Testar no Swagger

Autenticação

Toda chamada precisa de um token de acesso do Keycloak no cabeçalho Authorization: Bearer <token>. Os tokens são curtos (5 min) — renove pelo refresh token. Não existe API key. Cada token só enxerga os dados da própria empresa.

Na primeira chamada de cada sessão, chame /auth/bootstrap uma vez antes de qualquer rota de produto. Se uma rota responder 409 tenant_not_ready, chame o bootstrap e tente de novo.

curl -X POST https://api.docauto.com.br/api/v1/auth/bootstrap \
  -H "Authorization: Bearer $TOKEN"

Fluxo recomendado

Você pode chamar os endpoints na ordem que quiser, mas o caminho recomendado é: template → dataset → job → download. O field_mapping liga cada variável do template a uma coluna do dataset.

# 1. Template (.docx with Jinja2 variables) -> returns the variables
curl -X POST https://api.docauto.com.br/api/v1/templates \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=Contrato" -F "file=@contrato.docx"

# 2. Dataset (.csv or .xlsx) -> returns the columns
curl -X POST https://api.docauto.com.br/api/v1/datasets \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@clientes.csv"

# 3. Create the generation job
curl -X POST https://api.docauto.com.br/api/v1/generation/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "<TEMPLATE_ID>",
    "dataset_id": "<DATASET_ID>",
    "field_mapping": {"nome_cliente": "nome_cliente", "cpf": "cpf"},
    "output_format": "pdf"
  }'

# 4. Poll until COMPLETED, then download the ZIP
curl https://api.docauto.com.br/api/v1/generation/jobs/<JOB_ID> \
  -H "Authorization: Bearer $TOKEN"
curl -L https://api.docauto.com.br/api/v1/generation/jobs/<JOB_ID>/download \
  -H "Authorization: Bearer $TOKEN" -o documentos.zip

O field_mapping é um objeto JSON: a chave é a variável do template, o valor é a coluna do dataset. output_format é "pdf" (padrão) ou "docx".

Para não duplicar jobs, envie o cabeçalho Idempotency-Key ao criar um job: reenviar a mesma chave retorna o job já criado (janela de 24h).

Limites e erros

ItemLimite
Template (.docx)máx. 10 MB
Dataset (.csv / .xlsx)máx. 50 MB
Linhas por job1000
Avatarmáx. 2 MB
Paginaçãolimit 1–100 (padrão 20)

Os limites de taxa são por token (não pelo IP): 200/min na maioria das rotas, 30/min para enviar template/dataset e para a validação, 10/min para criar job. Em 429, espere e tente de novo.

CódigoSignificado
400 / 422Entrada inválida (tipo de arquivo, tamanho, mapeamento)
401Token ausente, expirado ou inválido
404Não encontrado (ou não pertence à sua empresa)
409tenant_not_ready (chame o bootstrap) ou idempotência em uso
429Limite de taxa excedido
502O provedor de identidade recusou uma escrita

Referência de endpoints

Todas as rotas abaixo ficam sob /api/v1 e exigem o token Bearer (exceto o download por ?dl_token=). {id} é um UUID.

Autenticação

POST/auth/bootstrap

Provisiona sua empresa no primeiro login e atualiza o cache de perfil. Chame uma vez por sessão, antes das demais rotas.

Templates

POST/templates

Envia um template .docx (multipart: name, file) e retorna as variáveis Jinja2 encontradas.

POST/templates/upload-url

Gera um token assinado para subir um template por uma página, sem mandar os bytes pela API. Retorna upload_ref.

POST/templates/upload-signed

Recebe o template autorizado pelo token assinado (usado pela página de upload). Uso único.

GET/templates

Lista seus templates (paginado).

GET/templates/{template_id}

Detalha um template, incluindo suas variáveis.

DELETE/templates/{template_id}

Exclui um template.

Datasets

POST/datasets

Envia um dataset .csv/.xlsx (multipart: file) e retorna as colunas e a contagem de linhas.

POST/datasets/upload-url

Gera um token assinado para subir um dataset por uma página. Retorna upload_ref.

POST/datasets/upload-signed

Recebe o dataset autorizado pelo token assinado. Uso único.

GET/datasets

Lista seus datasets (paginado).

GET/datasets/{dataset_id}

Detalha um dataset (colunas e linhas).

DELETE/datasets/{dataset_id}

Exclui um dataset.

GET/datasets/{dataset_id}/preview

Retorna as primeiras linhas, para você montar o mapeamento.

Geração

POST/generation/validate-mapping

Confere o mapeamento template × dataset antes de gerar; aponta variáveis faltando e colunas inválidas.

POST/generation/jobs

Cria o job (template_id, dataset_id, field_mapping, output_format). Aceita o cabeçalho Idempotency-Key. Retorna um job PENDING.

GET/generation/jobs

Lista seus jobs (paginado).

GET/generation/jobs/{job_id}

Consulta o status de um job (PENDING / RUNNING / COMPLETED / FAILED / CANCELLED).

POST/generation/jobs/{job_id}/cancel

Cancela um job em andamento.

DELETE/generation/jobs/{job_id}

Exclui um job e os documentos que ele gerou.

GET/generation/jobs/{job_id}/documents

Lista os documentos gerados por um job.

POST/generation/jobs/{job_id}/download-url

Emite um link assinado de curta duração para baixar o ZIP no navegador (usado pelo MCP hospedado).

GET/generation/jobs/{job_id}/download

Baixa o ZIP com todos os documentos do job. Aceita Bearer ou ?dl_token= (link assinado).

Documentos

GET/documents/{document_id}/download

Baixa um documento individual gerado.

Uploads

GET/uploads/status/{upload_ref}

Consulta o resultado de um upload feito por página assinada (pending / ready / failed).

Perfil

GET/profile

Retorna o perfil do usuário autenticado.

PATCH/profile

Atualiza a preferência de notificação (ex.: avisar quando o job terminar).

POST/profile/avatar

Envia uma nova imagem de avatar (máx. 2 MB).

PATCH/profile/company

Atualiza o nome da empresa.

Empresa

GET/companies/me

Retorna a empresa (tenant) do usuário.

PATCH/companies/me

Atualiza a empresa (ex.: account_type de personal para business).

POST/companies/me/banner-dismiss

Dispensa o banner Pessoal/Empresa por 7 dias.

Privacidade (LGPD)

Rotas dos direitos do titular dos dados (LGPD): acesso, exportação, correção, exclusão e consentimentos.

GET/privacy/summary

Resumo dos dados pessoais que a DocAuto guarda sobre você.

POST/privacy/export

Solicita a exportação dos seus dados (direito de acesso/portabilidade).

POST/privacy/delete-request

Solicita a exclusão da conta e dos dados.

POST/privacy/delete-cancel

Cancela uma solicitação de exclusão pendente.

PATCH/privacy/rectify

Retifica dados do perfil (direito de correção).

GET/privacy/requests

Lista suas solicitações de privacidade e o status de cada uma.

GET/privacy/policy/current

Retorna a política de privacidade vigente.

POST/privacy/consent

Registra um consentimento (ex.: aceite dos termos).

GET/privacy/consents

Lista os consentimentos que você já deu.

GET/privacy/consent/required

Lista os consentimentos obrigatórios ainda pendentes.

← Voltar para a landing