# Criando um Documento A criação de documentos difere um pouco das outras *mutations* por ter o **upload de um arquivo**. Primeiramente, vamos precisar escrever a *mutation:* 
mutation CreateDocumentMutation(
  $document: DocumentInput!, # Definição das variáveis $document,
  $signers: [SignerInput!]!, # $signers e $file, com seus respectivos
  $file: Upload!             # tipos. (Os "!" indicam que são
) {                          # parâmetros obrigatórios)      
  createDocument(
    document: $document,     # Passa para os parâmetros da mutation o 
    signers: $signers,       # valor das variáveis.
    file: $file,             #
    organization_id: 123,    # OPCIONAL: Cria em outras organizações do usuário, senão usa a atual
    folder_id: "a1b2c3"      # OPCIONAL: Cria arquivado em uma pasta
  ) {
    id
    name
    refusable
    sortable
    created_at
    signatures {
      public_id
      name
      email
      created_at
      action { name }
      link { short_link }
      user { id name email }
    }
  }
}
Após, precisamos dos valores das variáveis definidas na *mutation* em um JSON: ```json /* Abaixo, um signatário receberá o link de assinatura por email, por ter sido passado o "email" e, para o que passou "name", será retornado o atributo "link" no documento com o link de assinatura. Quando usado "phone", existirão duas possíveis formas de envio, especificadas no uso do atributo "delivery_method". Este atributo possui as opções "DELIVERY_METHOD_WHATSAPP" para enviar por Whatsapp e "DELIVERY_METHOD_SMS" para enviar por SMS. */ { "document": { "name": "Contrato de marketing" }, "signers": [{ "email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com", "action": "SIGN" }, { "name": "Ronaldo Fuzinato", "action": "SIGN" }, { "phone": "+5554999999999", "delivery_method": "DELIVERY_METHOD_WHATSAPP", "action": "SIGN" }, { "phone": "+5554999999998", "delivery_method": "DELIVERY_METHOD_SMS", "action": "SIGN" }, /* Também há como gerar links de assinatura vinculado a um numero de celular ou para um email. Assim o link gerado só pode ser assinado pelo endereço associado. */ { "name": "João Maria", "phone": "+5554999999998", "delivery_method": "DELIVERY_METHOD_LINK", "action": "SIGN" },{ "name": "Maria João", "email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com", "delivery_method": "DELIVERY_METHOD_LINK", "action": "SIGN" } ] } ``` Percebeu que não foi colocado nenhum valor para a variável *$file*? Pois é, como é realizado o *upload* desse arquivo, a requisição precisa ser enviada como *multipart/form-data*, dessa forma o arquivo precisa ser um pouco diferente. Você pode fazer isso direto no [Altair](https://altair.autentique.com.br): ![](/files/-LzJ8_DMjvVWNNW2rfQ3) {% hint style="warning" %} Caso você esteja em dúvida de como funciona o envio do documento para usar na sua integração, este repositório fornece mais informações e exemplos de como fazer o upload: {% endhint %} ### Criando documento em Sandbox Nossa API também suporta o envio de documento de teste, que não consomem créditos de documentos, assim facilitando a integração para quem ainda não adquiriu um plano com documentos ilimitados. Para saber como faz acesse nossa [página de sandbox](/api/2/integracao/sandbox-testes.md). ### Mais opções ```json // IMPORTANTE: // - Se você copiar esse JSON, remova os comentários antes de usar // - Alguns dos atributos abaixo não irão funcionar sem possuir um plano corporativo // - Alguns dos atributos abaixo irão consumir créditos de verificação adicional { "document": { "name": "Contrato de marketing", "message": "Mensagem customizada enviada para os emails dos signatários", "reminder": "WEEKLY", // Lembrete de assinatura semanal. DAILY para diário "whatsapp_template": "STANDARD", //Seleciona o template de WhatsApp. Aceita também os valores FORMAL, CASUAL e DIRECT "sortable": true, // Signatários assinam na ordem do array "signers" "footer": "BOTTOM", // Adiciona rodapé. Aceita também os valores LEFT e RIGHT "refusable": true, // Permite recusa do documento "qualified": true, // Ativa assinatura qualificada, usando certificados "scrolling_required": true, // Só permite a assinatura do documento caso o signatário tiver rolado toda a página "stop_on_rejected": true, // Impede que outras pessoas assinem quando recusado "new_signature_style": true, // Ativa novos campos de assinatura "show_audit_page": false, // Evita criar a última página de auditoria em documentos com "new_signature_style": true "ignore_cpf": true, // Remove obrigatoriedade de preencher CPF para assinar e removere qualquer referência a CPF na interface da plataforma "ignore_birthdate": true // Remove obrigatoriedade de preencher a data de nascimento e remove qualquer referencia da data de nascimento na interface da plataforma "email_template_id": 1234, // Usa modelo de email específico, pelo ID do mesmo "deadline_at": "2023-11-24T02:59:59.999Z", // Bloqueia assinaturas após data "reply_to": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com", //Define o endereço de e-mail para o qual as respostas devem ser enviadas. "cc": [ // Envia emails quando o documento for assinado por todos os signatários { "email": "email-cc-1@tuamaeaquelaursa.com" }, { "email": "email-cc-2@tuamaeaquelaursa.com" } ], "expiration": { // Envia um lembrete em uma quantidade de dias "days_before antes do // vencimento do documento informada no "notify_at" "days_before": 7, "notify_at": "20/01/2026" }, "configs": { "notification_finished": true, // Envia um email notificando todos os signatários que o documento foi assinado por todas as partes "notification_signed": true, // Envia um email ao signatário notificando que ele assinou o documento "signature_appearance": "ELETRONIC", // Força a aparência da assinatura, pode ser: DRAW, HANDWRITING, ELETRONIC, IMAGE "keep_metadata": true, // Mantém os metadados do PDF em assinatura qualificada "lock_user_data": true, // Mantém os dados do usuário desatualizados, mostrando os que foram usados ao assinar "pdfa": true // Mantem a versão e o tipo do PDF/A anexado. // Quanto "pdfa" ativo, modifica o parâmetro new_signature_style para true. // Obs.: Não converte um documento para PDF/A. }, "locale": { "country": "BR", // Qualquer país no formato ISO3166, se não informado, assume-se `BR` // *IMPORTANTE* A criação de documentos não brasileiros possui os seguintes pontos: // - Signatários com método de envio SMS não são suportados. Nesses casos, // a requisição retorna o erro: `sms_delivery_not_allowed_on_foreign_documents`; // - Os campos `new_signature_style` e `ignore_cpf` são marcados como `true`; // - Elementos de CPF posicionados nas páginas do documento são ignorados; // - Verificações adicionais do SERPRO e via SMS são ignoradas. "language": "pt-BR", // Pode ser: `pt-BR` ou `en-US`, se não informado, assume-se `pt-BR` "timezone": "America/Sao_Paulo", // DateTimeZone com todas as timezones, se não informado, assume-se `America/Sao_Paulo` // Uma lista completa pode ser encontrada em: https://www.php.net/manual/en/datetimezone.listidentifiers.php "date_format": "DD_MM_YYYY", // Enum, pode ser: DD_MM_YYYY ou MM_DD_YYYY, se não informado, assume-se `DD_MM_YYYY` } }, "signers": [{ "email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com", // Envia email "action": "SIGN", // Assinar "configs": { "cpf": "12345678900" }, // Valida o CPF do signatário "security_verifications": [ // Exigir validação por SMS ("verify_phone" é opcional): { "type": "SMS", "verify_phone": "+5554999999999" }, // Exigir documento com foto (Aprovação manual): { "type": "MANUAL" } ], // Posiciona campos de assinatura: "positions": [{"x": "5.0", "y": "90.0", "z": 1, "element": "SIGNATURE"}] }, { "name": "Ronaldo Fuzinato", // Recebe link de assinatura para enviar "action": "SIGN_AS_A_WITNESS", // Assinar como testemunha // Exigir documento com foto (Documento com foto): "security_verifications": [{ "type": "UPLOAD" }], // Posiciona campos para nome do signatário: "positions": [{"x": "75.0", "y": "90.0", "z": 1, "element": "NAME"}] }, { "email": "troque-esse-email-que-e-publico-2@tuamaeaquelaursa.com", // Envia email "action": "APPROVE", // Aprovar // Exigir documento com foto (Documento, selfie e prova de vida): "security_verifications": [{ "type": "LIVE" }], // Posiciona campos de rúbrica: "positions": [{"x": "25.0", "y": "90.0", "z": 1, "element": "INITIALS"}] }, { "phone": "+5521999999999", "delivery_method": "DELIVERY_METHOD_SMS", // Envia SMS para "phone" "action": "RECOGNIZE", // Reconhecer // Exigir documento com foto (Biometria SERPRO): "security_verifications": [{ "type": "PF_FACIAL" }], // Posiciona campos de data de assinatura: "positions": [{"x": "55.0", "y": "90.0", "z": 1, "element": "DATE"}] }, { "phone": "+5521999999998", "delivery_method": "DELIVERY_METHOD_WHATSAPP", // Envia Whatsapp para "phone" "action": "SIGN", // Assinar // Posiciona campos de CPF: "positions": [{"x": "55.0", "y": "90.0", "z": 1, "element": "CPF"}] }] } ``` ### Validações adicionais Você pode implementar validações adicionais em seus documentos. Estas configurações devem ser inseridas na lista `security_verifications` do objeto do signatário, utilizando o campo `type` para definir a modalidade de desafio desejada. Além dos tipos, campos como `verify_phone` e `cpf` auxiliam na entrega dos códigos de segurança e na identificação precisa da parte. | Campo / Tipo de Verificação | Como funciona | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `verify_phone` | O signatário precisará validar um número de celular através de um código enviado por SMS. Você pode preencher o número ou deixar em branco para que o próprio signatário informe | | `cpf` | Configuração que garante que apenas o signatário com o CPF especificado possa assinar o documento. Se definido, o sistema obriga o preenchimento ou validação desse dado na conta do signatário. | | `MANUAL` | O signatário anexará um documento de identificação com foto, e tirará uma selfie. Você ou algum membro da sua organização poderão aprovar ou rejeitar os documentos e selfie enviados. | | `UPLOAD` | O signatário precisará anexar frente e verso de um documento de identificação com foto, com seu smartphone ou computador. | | `LIVE` | O signatário precisará anexar um documento de identificação com foto, tirar uma selfie com seu smartphone e realizar uma prova de vida. A foto do documento será automaticamente comparada com a selfie para verificar o grau de semelhança | | `PF_FACIAL` | O signatário tira uma selfie que é validada pelo SERPRO, comparando-a com as fotos de registro do governo brasileiro vinculadas ao CPF informado | | `BIOMETRIC_AND_TEXT_EXTRACTION` | O signatário precisará fotografar um documento de identificação e tirar uma selfie, a foto do documento será comparada com a selfie para determinar o grau de semelhança. | | `LIVENESS_AND_TEXT_EXTRACTION` | O signatário precisará realizar uma prova de vida e fotografar um documento de identificação com foto. As informações do documento serão extraídas automaticamente e comparadas para verificar o grau de semelhança. |
Posicionar campos de assinatura "positions" Como mostrado no exemplo acima, para adicionar campos de assinatura ao criar o documento você precisa adicionar o atributo "positions". ```json { ... "signers": [ { ... "positions": [ { "x": "100.0", "y": "100.0", "z": 1, "element": "SIGNATURE" } ] } ] } ``` O `"x"` é posição horizontal de 0 a 100%\ O `"y"` é posição vertical de 0 a 100%\ O `"z"` é o número da página começando no 1 \ O `"element"` é o tipo de assinatura:\ `"SIGNATURE"`: Assinatura\ `"NAME"`: Nome do signatário\ `"INITIALS"`: Rúbrica\ `"DATE"`: Data de assinatura\ `"CPF"`: CPF do signatário Pra saber quais posições passar no x e y, você pode criar um documento de exemplo no painel do Autentique e buscar as posições ao resgatar o documento usando "positions": ```graphql query { document(id: "ID_DO_DOCUMENTO") { id signatures { public_id positions { element x y z } } } } ```
Exigir verificação por SMS e/ou documento com foto "security_verifications" Para exigir dos signatários a verificação por SMS e/ou documento com foto, é preciso adicionar o atributo `"security_verifications"` no signatário que você deseja que essas verificações sejam necessárias. Lembrando que você deve consultar no painel o custo de créditos de verificação adicionais necessários. ```json { ... "signers": [ { ... "security_verifications": [ { "type": "SMS", "verify_phone": "+5554999999999" }, { "type": "MANUAL" } ] }, { ... "security_verifications": [ { "type": "BIOMETRIC_AND_TEXT_EXTRACTION" } ] }, { ... "security_verifications": [ { "type": "BIOMETRIC_AND_TEXT_EXTRACTION", "fallback_behavior": "DISABLE_FALLBACK" } ] } ] } ``` \ O `"type"` é o tipo de verificação:\ `"SMS"`: Validação por SMS (`"verify_phone"` é opcional e exige celular especificado)\ `"MANUAL"`: Exigir documento com foto (Aprovação manual)\ `"UPLOAD"`: Exigir documento com foto (Documento com foto)\ `"LIVE"`: Exigir documento com foto (Documento, selfie e prova de vida)\ `"PF_FACIAL"`: Exigir documento com foto (Biometria SERPRO)\ "`BIOMETRIC_AND_TEXT_EXTRACTION"`: Exigir documento com foto (Documento com foto e facematch) Apesar de ser possível ter múltiplas verificações para o mesmo signatário, dentre as seguintes opções somente é possível escolher uma delas por signatário: `MANUAL`, `UPLOAD`, `LIVE` e `PF_FACIAL`. Quando utilizar os tipos `UPLOAD`, `LIVE`, `PF_FACIAL` e `BIOMETRIC_AND_TEXT_EXTRACTION` , há o comportamento padrão de serem alterados para `MANUAL` quando o signatário exceder a quantidade máxima de tentativas no processo de validação documental.\ Para desativar esse comportamento é necessário utilizar o parâmetro `fallback_behavior`, que acusará falha no documento e o rejeitará automaticamente.
Criar documento a partir de modelo Não há uma forma na API de você conseguir usar os modelos do painel para criar documentos, porém você consegue fazer algo parecido à partir do seu código: 1. Criar um modelo fixo em HTML na máquina, demarcando os lugares com variáveis para substituir por valores. (Ex: "Eu, $NomeSignatario$ aceito esse contrato") 2. Por código, duplicar esse HTML e nessa duplicata, substituir os campos de variáveis pelos valores reais. ( Ex: $NomeSignatario$ => Jorge Silva ) 3. Enviar esse arquivo HTML com os valores substituídos para a nossa API, através da mutation *createDocument*, igual como já funciona para outros tipos de arquivos
Exemplo de criação de documento com NodeJS Se você usa o Postman, você pode gerar esses exemplos à partir da collection para o Postman disponibilizada aqui na [documentação](/api/2/master.md). ```javascript var axios = require('axios'); var FormData = require('form-data'); var fs = require('fs'); var data = new FormData(); data.append('operations', '{"query":"mutation CreateDocumentMutation($document: DocumentInput!, $signers: [SignerInput!]!, $file: Upload!) {createDocument(document: $document, signers: $signers, file: $file) {id name refusable sortable created_at signatures { public_id name email created_at action { name } link { short_link } user { id name email }}}}", "variables":{"document": {"name": "Contrato de teste"},"signers": [{"email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com","action": "SIGN"}],"file":null}}'); data.append('map', '{"file": ["variables.file"]}'); data.append('file', fs.createReadStream('/path/to/file')); var config = { method: 'post', url: 'https://api.autentique.com.br/v2/graphql', headers: { 'Authorization': 'Bearer TOKEN_DE_API', ...data.getHeaders() }, data : data }; axios(config) .then(function(response) { console.log(JSON.stringify(response.data)); }) .catch(function(error) { console.log(error); }); ``` Desse exemplo é só substituir o **token de API**, **email do signatário** e **caminho para o arquivo**.
Exemplo de criação de documento com PHP Se você usa o Postman, você pode gerar esses exemplos à partir da collection para o Postman disponibilizada aqui na [documentação](/api/2/master.md). ```php 'https://api.autentique.com.br/v2/graphql', CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => array('operations' => '{"query":"mutation CreateDocumentMutation($document: DocumentInput!, $signers: [SignerInput!]!, $file: Upload!) {createDocument(document: $document, signers: $signers, file: $file) {id name refusable sortable created_at signatures { public_id name email created_at action { name } link { short_link } user { id name email }}}}", "variables":{"document": {"name": "Contrato de teste"},"signers": [{"email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com","action": "SIGN"}],"file":null}}','map' => '{"file": ["variables.file"]}','file'=> new CURLFILE('/path/to/file')), CURLOPT_HTTPHEADER => array('Authorization: Bearer TOKEN_DE_API'), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` Desse exemplo é só substituir o **token de API**, **email do signatário** e **caminho para o arquivo**.
Exemplo de criação de documento com Python3 Se você usa o Postman, você pode gerar esses exemplos à partir da collection para o Postman disponibilizada aqui na [documentação](/api/2/master.md). ```python import requests url = "https://api.autentique.com.br/v2/graphql" payload = { 'operations': '{"query":"mutation CreateDocumentMutation($document: DocumentInput!, $signers: [SignerInput!]!, $file: Upload!) {createDocument(document: $document, signers: $signers, file: $file) {id name refusable sortable created_at signatures { public_id name email created_at action { name } link { short_link } user { id name email }}}}", "variables":{"document": {"name": "Contrato de teste"},"signers": [{"email": "troque-esse-email-que-e-publico@tuamaeaquelaursa.com","action": "SIGN"}],"file":null}}', 'map': '{"file": ["variables.file"]}' } files = [ ('file',open('/path/to/file.pdf','rb')) ] headers = { 'Authorization': 'Bearer TOKEN_DE_API' } response = requests.request("POST", url, headers=headers, data=payload, files=files) print(response.text) ``` Desse exemplo é só substituir o **token de API**, **email do signatário** e **caminho para o arquivo**.
Exemplo de criação de documento com C# Se você usa o Postman, você pode gerar esses exemplos à partir da collection para o Postman disponibilizada aqui na [documentação](/api/2/master.md). ```csharp var client = new RestClient("https://api.autentique.com.br/v2/graphql"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer TOKEN_DE_API"); request.AddParameter("operations", "{\"query\":\"mutation CreateDocumentMutation($document: DocumentInput!, $signers: [SignerInput!]!, $file: Upload!) {createDocument(document: $document, signers: $signers, file: $file) {id name refusable sortable created_at signatures { public_id name email created_at action { name } link { short_link } user { id name email }}}}\", \"variables\":{\"document\": {\"name\": \"Contrato de teste\"},\"signers\": [{\"email\": \"troque-esse-email-que-e-publico@tuamaeaquelaursa.com\",\"action\": \"SIGN\"}],\"file\":null}}"); request.AddParameter("map", "{\"file\": [\"variables.file\"]}"); request.AddFile("file", "/path/to/file"); IRestResponse response = client.Execute(request); Console.WriteLine(response.Content); ``` Desse exemplo é só substituir o **token de API**, **email do signatário** e **caminho para o arquivo**.
{% hint style="info" %} Você pode conferir o que é cada um desses parâmetros direto na documentação completa da API GraphQL, no menu Docs do [Altair](https://altair.autentique.com.br). Se você não sabe como fazer isso, confira o nosso tutorial em [Usando o Altair](/api/2/integracao/altair.md). {% endhint %} {% file src="/files/-M03o9cE5QB3vLoPUlzJ" %} Para importar e usar no Postman {% endfile %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.autentique.com.br/api/2/mutations/criando-um-documento.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.