Documentação API

Transforme seus documentos com facilidade e eficiência com nossa API

Arquivo Insomnia e explicação das rotas

Para facilitar a integração e o teste da nossa API, disponibilizamos um arquivo Insomnia que contém todas as rotas necessárias. Esse arquivo permite que você experimente nossas funcionalidades de forma rápida e eficiente.

Download do arquivo Insomnia

Você pode baixar o arquivo Insomnia clicando no link abaixo:

Download Arquivo Insomnia

Explicação das rotas

Abaixo, detalhamos todas as rotas e como utilizá-la:

Versão da API

V1: https://apiia.uxdoc.com.br

Transformar DOCX em Legal Design

PATCH /oneclick/analyze-clause-and-design

Converte um contrato em formato DOCX para um documento com Legal Design e retorna um link temporário para download (PDF, DOCX ou PPTX).

Autenticação

Authorization: Bearer <JWT>

Cabeçalhos obrigatórios

Header	Valor
Authorization	Bearer <seu-token>
Content-Type	multipart/form-data (com boundary gerado automaticamente pela lib/cliente HTTP)

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
ux_writing	boolean	Sim	Otimiza o texto segundo boas práticas de UX Writing.
main_color	string	Sim	Cor predominante do documento em hexadecimal (ex.: #DB003C).
logo_url	string (URL)	Não	URL pública (HTTP/HTTPS) da logo em PNG ou JPG para inserir no cabeçalho.
download_type	string	Sim	Formato de saída: pdf, docx ou pptx.
is_summary	boolean	Sim	Gera sumário clicável (índice) no documento final.
highlights	boolean	Sim	Aplica destaques visuais (cores, caixas, ícones) às cláusulas principais.

Body (multipart/form-data)

Campo	Tipo	Obrigatório	Descrição
docx	Arquivo .docx	Sim	Contrato a ser convertido. • Deve ser salvo a partir do Microsoft Word ou Google Docs. • Outros tipos de documentos não são aceitos.

Estrutura do documento

O arquivo deve conter apenas títulos, cláusulas e partes. Certifique-se de evitar os seguintes elementos no documento:

Partes de assinatura: Não inclua áreas de assinatura.
Capa: Evite adicionar uma capa ao documento.
Quadro resumo: Não use quadros resumos.
Anexos: Não inclua anexos no final do documento.

Exemplo de requisição (cURL)

				
					bash
curl -X PATCH https://api.uxdoc.com.br/oneclick/analyze-clause-and-design \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "docx=@/caminho/para/Contrato_Exemplo.docx" \
  -F "ux_writing=true" \
  -F "main_color=#DB003C" \
  -F "logo_url=https://meusite.com/logo.png" \
  -F "download_type=pdf" \
  -F "is_summary=true" \
  -F "highlights=true"

Resposta da API

				
					json
{
  "document_url": "url"
}

O link expira após 24 h e o arquivo é removido automaticamente de nossos servidores.

Códigos de erro comuns

Código	Quando ocorre	Corpo (message)
400 Bad Request	Falta campo obrigatório ou tipo de arquivo inválido	“Missing field: docx” / “Unsupported file type”
401 Unauthorized	Token ausente ou inválido	“Invalid or expired token”
500 Internal Server Error	Falha inesperada no processamento	“Unexpected error – try again later”

Observações

Aceita apenas contratos; outros tipos de documentos serão recusados.
Tamanho máximo permitido depende do seu plano (padrão: 10 MB). Caso precise de mais, fale com nosso suporte.
Para minimizar problemas com caracteres especiais, salve o DOCX em UTF-8.

Gerar cláusula contratual

POST /create-clause/generate-clause

Caso você precise receber o texto via stream (chunked), utilize o endpoint: /create-clause/generate-clause/stream

Cria uma cláusula pronta para uso a partir de três parâmetros: tipo de contrato, tipo de cláusula e condição desejada.
A cláusula é processada e não fica armazenada em nossos servidores.

Autenticação

Authorization: Bearer <JWT>

Cabeçalhos obrigatórios

Header	Valor
Authorization	Bearer <seu-token>
Content-Type	application/json

Corpo da requisição (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_type	string	Sim	Nome do contrato ao qual a cláusula pertencerá (ex.: “Prestação de serviço”).
clause_type	string	Sim	Tipo de cláusula a ser gerada (ex.: “Objeto”, “Pagamento”, “Prazo”).
clause_condition	string	Sim	Condição ou detalhe específico que a cláusula deve contemplar (ex.: “Venda de carro”).
jurisdiction	string	Sim	Seleciona a jurisdição na qual a cláusula deve ser gerada. Campos disponíveis para escolha: Brasil, México, Colômbia, Equador, Argentina, Chile, Uruguai, Peru, Espanha, EUA – Delaware, EUA – Flórida, EUA – Califórnia, EUA – Nova York, EUA – Texas, Canadá, Inglaterra, Austrália, Holanda, Itália, Portugal, Alemanha, França.
output_language	string	sim	É o a linguagem na qual a cláusula será gerada. Opções disponíveis: Português, Inglês, Espanhol

Dica: Quanto mais claro o texto em clause_condition, mais precisa será a cláusula resultante.

Exemplo de requisição (cURL)

				
					bash
curl -X POST https://api.uxdoc.com.br/create-clause/generate-clause \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "contract_type": "Prestação de serviço",
        "clause_type": "Objeto",
        "clause_condition": "Venda de carro"
      }'

Resposta da API

				
					json
{
  "document": "clausula aqui"
}

O texto acima é apenas um exemplo — a resposta refletirá exatamente os parâmetros enviados.

Códigos de erro comuns

Código	Quando ocorre	Corpo (message)
400 Bad Request	Campo obrigatório ausente ou JSON malformado	“Missing field: clause_type”
401 Unauthorized	Token ausente ou inválido	“Invalid or expired token”
500 Internal Server Error	Falha inesperada na geração da cláusula	“Unexpected error – try again later”

Observações

A cláusula não é armazenada em banco — somente processada e devolvida.
Caso você precise receber o texto via stream (chunked), utilize o endpoint /create-clause/generate-clause/stream
Limite de 4.000 caracteres para cada campo de entrada.

Gerar Perguntas-Guia para Contrato

POST /create-contracts/generate-firts-questions

Sugere um conjunto inicial de perguntas que ajudam a coletar as informações necessárias para, em seguida, gerar um contrato completo.
Opcional: você pode pular esta rota e enviar os dados diretamente para o endpoint de criação de contrato, se preferir.

Autenticação

Authorization: Bearer <JWT>

Cabeçalhos obrigatórios

Header	Valor
Authorization	Bearer <seu-token>
Content-Type	application/json

Corpo da requisição (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_type	string	Sim	Tipo de contrato que será gerado (ex.: “Prestação de serviço”).
parts_number	string	Sim	Número de partes envolvidas (ex.: “2” ou “3”).
object	string	Sim	Objeto principal do contrato (ex.: “Aluguel de cadeiras para festas infantis”).
jurisdiction	string	Sim	Seleciona a jurisdição na qual as perguntas serão geradas. Campos disponíveis para escolha: Brasil, México, Colômbia, Equador, Argentina, Chile, Uruguai, Peru, Espanha, EUA – Delaware, EUA – Flórida, EUA – Califórnia, EUA – Nova York, EUA – Texas, Canadá, Inglaterra, Austrália, Holanda, Itália, Portugal, Alemanha, França.
output_language	string	Sim	É o a linguagem na qual as perguntas serão geradas. Opções disponíveis: Português, Inglês, Espanhol

Exemplo de requisição (cURL)

				
					bash
curl -X POST https://api.uxdoc.com.br/create-contracts/generate-firts-questions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "contract_type": "Prestação de serviço",
        "parts_number": "2",
        "object": "Aluguel de cadeiras de festas de crianças"
      }'

Resposta da API

				
					json
{
  "questions": [
    {
      "question": "Pergunta aqui...."
    }
  ]
}

Códigos de erro comuns

Código	Quando ocorre	Corpo (message)
400 Bad Request	Campo obrigatório ausente ou JSON malformado	“Missing field: object”
401 Unauthorized	Token ausente ou inválido	“Invalid or expired token”
500 Internal Server Error	Falha inesperada durante a geração das perguntas	“Unexpected error – try again later”

Observações

As perguntas retornadas não são salvas em banco; servem apenas como guia para capturar detalhes do contrato.
Use as perguntas como checklist interno ou apresente ao usuário final para coletar respostas.
As respostas obtidas podem ser enviadas ao endpoint de criação de contrato (modo normal ou stream) para gerar o documento final.

Gerar contrato completo

POST /create-contracts/generate-document
POST /create-contracts/generate-document/stream (retorno em stream, parágrafo a parágrafo)

Gera um contrato completo (em português) a partir dos dados fornecidos.
O endpoint padrão entrega o documento final em DOCX (Base64).
A variante /stream devolve o texto em chunks Markdown, permitindo exibir o contrato em tempo real enquanto ele é criado.

⚠️ Aceita apenas contratos. Outros tipos de documentos não são gerados.

Autenticação

Authorization: Bearer <JWT>

Cabeçalhos obrigatórios

Header	Valor
Authorization	Bearer <seu-token>
Content-Type	application/json

Corpo da requisição (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_type	string	Sim	Nome do contrato a ser gerado (ex.: “Prestação de serviço”).
parts_number	string	Sim	Quantidade de partes no contrato (ex.: “2” ou “3 partes”).
object	string	Sim	Objeto do contrato (ex.: “Construção de shopping center”).
docx_base64	String	Não	Enviar contrato modelo caso queira que a IA use seu contrato como base para gerar o novo contrato. O contrato modelo deve ser em .docx e deve ser convertido em base64 para envio.
questions	array<{ question: string; response: string; } >	Sim	Perguntas + respostas que detalham cláusulas. Você pode: • reutilizar as perguntas da rota /generate-firts-questions • ou enviar seu próprio conjunto.
question	string	Sim	Texto da pergunta.
response	string	Sim	Resposta dada (conteúdo será incorporado ao contrato).
jurisdiction	string	Sim	Seleciona a jurisdição na qual o contrato será criado. Campos disponíveis para escolha: Brasil, México, Colômbia, Equador, Argentina, Chile, Uruguai, Peru, Espanha, EUA – Delaware, EUA – Flórida, EUA – Califórnia, EUA – Nova York, EUA – Texas, Canadá, Inglaterra, Austrália, Holanda, Itália, Portugal, Alemanha, França.
output_language	string	Sim	É o a linguagem na qual o contrato será escrito. Opções disponíveis: Português, Inglês, Espanhol

Boas práticas
• Inclua perguntas que cubram prazo, pagamento, responsabilidades, penalidades etc.
• Use linguagem clara para evitar ambiguidades.

Exemplo de requisição (cURL)

				
					bash
curl -X POST https://api.uxdoc.com.br/create-contracts/generate-document \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json      # body.json contém o JSON de exemplo abaixo

Corpo (body.json) resumido

				
					json
{
  "contract_type": "Contrato de Engineering, Procurement and Construction",
  "parts_number": "2",
  "object": "Projeto de engenharia, compras e construção de um shopping center",
  "questions": [
    {
      "question": "Qual o prazo de vigência do contrato e as condições para sua prorrogação ou rescisão antecipada?",
      "response": "Vigência de 24 meses, prorrogável por igual período..."
    },
    {
      "question": "Quais são as obrigações específicas de cada uma das partes?",
      "response": "Contratada: planejar, comprar materiais e construir..."
    },
    {
      "question": "Qual a forma e condições de pagamento?",
      "response": "Pagamentos conforme medições; multa de 10 % por atraso..."
    }
  ]
}

Resposta da API

Modo padrão (/generate-document)

				
					json
{
  "base64_document": "UEsDBAoAAAAAAPpk6loA..."
}

base64_document contém o DOCX completo em Base64.
Para baixar, basta decodificar e salvar com a extensão .docx.

Modo stream (/generate-document/stream)

				
					Fluxo chunked (text/event-stream ou application/x-ndjson):
{ "chunk": "### 1. Partes\n\n**Contratante:** ..." }
{ "chunk": "### 2. Objeto\n\nA contratada realizará ..." }

Cada chunk traz um bloco em Markdown até a conclusão do documento.

Códigos de erro comuns

Código	Quando ocorre	Corpo (message)
400 Bad Request	Campo obrigatório ausente ou JSON malformado	“Missing field: questions”
401 Unauthorized	Token ausente ou inválido	“Invalid or expired token”
500 Internal Server Error	Falha inesperada na geração	“Unexpected error – try again later”

Observações

Armazenamento: o contrato não é salvo em nossos servidores.
Para contratos com mais de 15 páginas, recomenda-se usar a rota /stream para acompanhar o progresso e evitar time-outs.
Se precisar converter o DOCX resultante para PDF ou Legal Design, utilize a rota /oneclick/analyze-clause-and-design.

Análise de risco contratual

POST /risk-analysis
POST /risk-analysis/stream (retorno em stream para exibir progresso em tempo real)

Lê um contrato em DOCX, identifica e qualifica riscos jurídicos, sugerindo cláusulas otimizadas e recomendações de mitigação.
A versão /stream devolve o relatório em blocos JSON — ideal para exibir cada item conforme é processado.

⚠️ Somente contratos em DOCX são aceitos; outros tipos de documento são recusados.

Autenticação

Authorization: Bearer <JWT>

Cabeçalhos obrigatórios

Header	Valor
Authorization	Bearer <seu-token>
Content-Type	application/json

Corpo da requisição (application/json)

Campo	Tipo	Obrigatório	Descrição
contract_position	string	Sim	Sua posição no contrato (ex.: “Contratante”, “Contratada”, “Advogado do contratante”).
specific_organizational_risks	string	Não	Matriz ou lista de riscos específicos da sua organização (ex.: “Pagamentos em 60 dias”).
document_base64	string (Base64)	Sim	Contrato DOCX, convertido para Base64.
jurisdiction	string	Sim	Seleciona a jurisdição na qual o contrato será analisado. Campos disponíveis para escolha: Brasil, México, Colômbia, Equador, Argentina, Chile, Uruguai, Peru, Espanha, EUA – Delaware, EUA – Flórida, EUA – Califórnia, EUA – Nova York, EUA – Texas, Canadá, Inglaterra, Austrália, Holanda, Itália, Portugal, Alemanha, França.
output_language	string	Sim	É o a linguagem na qual as descrições da analise será gerada. Opções disponíveis: Português, Inglês, Espanhol.

Dica: Prefira Base64 puro (sem prefixo data:) para evitar erros de decodificação.

Exemplo de requisição (cURL – rota padrão)

				
					bash
curl -X POST https://api.uxdoc.com.br/risk-analysis \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "contract_position": "Contratante",
        "specific_organizational_risks": "Pagamentos em 60 dias",
        "document_base64": "<SEU_DOCX_EM_BASE64>"
      }'
Para streaming, basta trocar a URL para /risk-analysis/stream e adicionar:
-H "Accept: text/event-stream"

Resposta da API

Rota padrão (/risk-analysis)

				
					jsonc
{
  "risk_analysis": {
    "clauses": [                       // Lista de cláusulas analisadas
      {
        "clause_name": "string",       // Título exato da cláusula no contrato
        "risk_level": "Baixo|Médio|Alto|Essencial",
        "original_text": "string",     // Texto original da cláusula
        "risk_description": "string",  // Por que há risco
        "recommendations": "string",   // Sugestões de mitigação
        "optimized_clause": "string"   // Versão sugerida da cláusula
      }
    ],
    "directions": {                    // Estratégias e próximos passos
      "trading_strategies": [ { "item": "string" } ],
      "compliance_legal_updates": [ { "item": "string" } ],
      "next_steps": [ { "item": "string" } ]
    }
  }
}

Rota stream (/risk-analysis/stream)

Fluxo text/event-stream (ou application/x-ndjson) em que cada linha é um pedaço do JSON:

Implementação sugerida

Abra a conexão via EventSource (front-end) ou fetch com stream: true.
Concatene cada linha recebida para montar o objeto final ou exiba incrementalmente na interface.

Códigos de erro comuns

Código	Quando ocorre	Corpo (message)
400 Bad Request	Campo obrigatório ausente ou JSON malformado	“Missing field: document_base64”
401 Unauthorized	Token ausente ou inválido	“Invalid or expired token”
500 Internal Server Error	Falha inesperada na análise	“Unexpected error – try again later”

Observações

Confidencialidade: o DOCX é processado em memória e apagado imediatamente após a geração do relatório.
Limitações atuais: não analisa anexos em PDF ou imagens embutidas; inclua o texto dessas seções no DOCX, se necessário.

Política de Privacidade e Termo de Uso.

Documentação API

Sumário

Arquivo Insomnia e explicação das rotas

Download do arquivo Insomnia

Explicação das rotas

Versão da API

Transformar DOCX em Legal Design

Resposta da API

Gerar cláusula contratual

Exemplo de requisição (cURL)

Resposta da API

Gerar Perguntas-Guia para Contrato

Exemplo de requisição (cURL)

Resposta da API

Gerar contrato completo

Exemplo de requisição (cURL)

Corpo (body.json) resumido

Resposta da API

Modo padrão (/generate-document)

Modo stream (/generate-document/stream)

Análise de risco contratual

Exemplo de requisição (cURL – rota padrão)

Resposta da API

Rota padrão (/risk-analysis)

Rota stream (/risk-analysis/stream)