API Assina Brasil — Documentação Oficial

Introdução

Seja bem-vindo à documentação oficial da API Assina Brasil. Com nossa API você pode integrar sua aplicação, CRM, loja virtual ou qualquer outro sistema ao fluxo de assinatura digital com validade jurídica no Brasil.

A API está disponível em todos os planos pagos — e o plano Ilimitado libera o uso completo sem limites de requisições.

Primeiro passo: crie sua conta

Cadastre-se gratuitamente, não solicitamos cartão de crédito. Criar conta no Assina Brasil.

Segundo passo: identifique seu Token de acesso

Como a API já vem habilitada, geramos automaticamente um token de acesso para a sua conta. Para visualizá-lo, acesse Configurações › Integrações e APIs.

O Token autentica todas as requisições — é o seu login da API.

Autenticação

Todos os endpoints utilizam autenticação Bearer Token. Envie o cabeçalho Authorization em todas as requisições:

HTTP Header

Authorization: Bearer SEU_TOKEN_DE_ACESSO

cURL

curl https://app.assinabrasil.com.br/api/v1/document \
  -H "Authorization: Bearer SEU_TOKEN_DE_ACESSO"

Versão da API

A versão atual é a v1. A base URL para todas as requisições é:

Base URL

https://app.assinabrasil.com.br/api/v1/

As versões da API são mantidas por um período mínimo de 2 anos. Novas versões são anunciadas por e-mail a todos os clientes.

Tratamento de erros

Além do status code HTTP (200 em caso de sucesso e 400 em caso de falha), todas as respostas seguem um envelope JSON padronizado.

Sucesso

{
    "status": "success",
    "title": "Document successfully registered",
    "message": {
        /* Dados de retorno da requisição */
    }
}

Erro

{
    "status": "error",
    "title": "validations",
    "message": {
        "16": "You have reached the subscription limit for your access plan"
    }
}

status — valores possíveis: success ou error.
title — mensagem de sucesso ou indicativo do erro.
message — corpo da resposta com os dados ou os detalhes dos erros.
Todas as mensagens de erro são retornadas em inglês.

Webhooks

Webhooks são opcionais e notificam sua aplicação sobre mudanças de estado no processo de assinatura — por exemplo, quando um signatário assina ou recusa o documento.

Configure a URL de callback em Configurações › Integrações e APIs.

Eventos disponíveis

created

Novo documento criado (via API ou aplicação)

signed

Documento assinado por um dos signatários

unsigned

Assinatura recusada pelo signatário

deleted

Documento deletado da plataforma

Exemplo de notificação

POST · webhook · evento signed

{
    "event": "signed",
    "status": "success",
    "title": "Signatory signed the document",
    "message": {
        "name": "Atestado de Matrícula.pdf",
        "extension": "pdf",
        "size": "11",
        "document_key": "Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J",
        "status": "Unsigned",
        "hash_file_original": "6f088873b84cb8c176d012969977430e3f3a692222d6e26f596644a46e392dc7",
        "signers": [
            {
                "signing_key": "a1oGscl0ZhdpE30LefOylCtW87q1dwrD",
                "status": "Signed",
                "name": "Fulano da Silva",
                "email": "fulano.teste@assinabrasil.com.br",
                "phone": "48984193232",
                "send_time": "2026-01-15 14:25:33",
                "update_time": "2026-01-15 14:30:11",
                "link": "https://app.assinabrasil.com.br/view/Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J?signingKey=a1oGscl0ZhdpE30LefOylCtW87q1dwrD",
                "auth": "Yes"
            }
        ]
    }
}

Referência da API

Todos os endpoints exigem o cabeçalho Authorization: Bearer SEU_TOKEN.

Enviar documento para assinatura

POSThttps://app.assinabrasil.com.br/api/v1/document

Envia um novo documento PDF para assinatura. O PDF pode ser enviado em base64 ou via url pública acessível.

Parâmetros

Nome	Tipo	Descrição
namereq	string	Nome do documento (ex: Arquivo.pdf).
comments	string	Comentários do documento (enviados por e-mail ao signatário).
signersreq	json[]	Lista de signatários (ver tabela abaixo).
base64	string	PDF codificado em base64. Obrigatório se url não for informada.
url	string	URL pública acessível do PDF. Obrigatório se base64 não for informado.
path	string	Opcional. Nome do diretório onde o arquivo será salvo (precisa existir).
email	string	Opcional. E-mail do usuário responsável pelo upload. Padrão: último usuário ativo.

Lista de signatários

Nome	Tipo	Descrição
name	string	Nome do signatário.
email	string	E-mail do signatário.
phone	string	Telefone, ex.: (48) 90419-5050.
auth	boolean	Solicita autenticação via Token (padrão false).
send_email	boolean	Envia o convite por e-mail (padrão true).
send_sms	boolean	Envia o convite por SMS (padrão false).
positions	json[]	Posicionamento da assinatura no PDF (page, xPos, yPos, width, height).

Requisição

json · request body

{
    "name": "Atestado de Matrícula.pdf",
    "comments": "Testando o envio via api",
    "signers": [
        {
            "name": "Fulano da Silva",
            "email": "fulano.teste@assinabrasil.com.br",
            "phone": "(48) 98419-3232",
            "auth": true,
            "send_email": true,
            "send_sms": true,
            "positions": [
                {
                    "page": "1",
                    "xPos": "129.82",
                    "yPos": "117",
                    "width": "139",
                    "height": "23"
                }
            ]
        },
        {
            "name": "Beltrano da Silva",
            "email": "beltrano.teste@assinabrasil.com.br",
            "phone": "(49) 98419-5050",
            "auth": true,
            "send_email": true,
            "send_sms": false,
            "positions": []
        }
    ],
    "base64": "JVBERi0xLjQNJeLjz9MNCjY... <PDF em base64>"
}

Resposta

json · response

{
    "status": "success",
    "title": "Document successfully registered",
    "message": {
        "document_key": "Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J",
        "status": "Unsigned",
        "signers": [
            {
                "signing_key": "a1oGscl0ZhdpE30LefOylCtW87q1dwrD",
                "status": "Pending",
                "link": "https://app.assinabrasil.com.br/view/Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J?signingKey=a1oGscl0ZhdpE30LefOylCtW87q1dwrD"
            }
        ]
    }
}

Consultar documento

GEThttps://app.assinabrasil.com.br/api/v1/document/{document_key}

Retorna as informações de um documento específico. Informe o document_key recebido na criação.

Resposta

json · response

{
    "status": "success",
    "title": "Document found",
    "message": {
        "name": "Atestado de Matrícula.pdf",
        "extension": "pdf",
        "document_key": "Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J",
        "status": "Unsigned",
        "hash_file_original": "6f088873b84cb8c176d012969977430e3f3a692222d6e26f596644a46e392dc7",
        "signers": [
            {
                "signing_key": "a1oGscl0ZhdpE30LefOylCtW87q1dwrD",
                "status": "Pending",
                "name": "Fulano da Silva",
                "email": "fulano.teste@assinabrasil.com.br",
                "phone": "48984193232",
                "auth": "Yes"
            }
        ]
    }
}

Listar documentos

GEThttps://app.assinabrasil.com.br/api/v1/document

Lista todos os documentos já enviados na sua conta.

Resposta

json · response

{
    "status": "success",
    "title": "Documents found",
    "message": [
        {
            "document_key": "Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J",
            "name": "Atestado de Matrícula.pdf",
            "status": "Signed",
            "created_at": "2026-01-15 14:25:33"
        }
    ]
}

Remover documento

DELETEhttps://app.assinabrasil.com.br/api/v1/document/{document_key}

Remove um documento da plataforma. Basta informar o document_key.

Resposta

json · response

{
    "status": "success",
    "title": "Document successfully deleted",
    "message": {}
}

Criar modelo (template)

POSThttps://app.assinabrasil.com.br/api/v1/template

Envia um PDF para ser utilizado como modelo. Após o upload, o envio para assinatura é feito apenas pela aplicação.

Parâmetros

Nome	Tipo	Descrição
namereq	string	Nome do modelo (ex: Modelo.pdf).
template_fields	json[]	Campos a serem preenchidos no documento (type, page, xPos, yPos, width, height, text).
base64	string	PDF em base64. Obrigatório se url não for enviada.
url	string	URL pública do PDF. Obrigatório se base64 não for enviado.
path	string	Diretório de destino (precisa existir).
email	string	E-mail do usuário responsável.

Requisição

json · request body

{
    "name": "Atestado de Matrícula.pdf",
    "template_fields": [
        {
            "type": "text",
            "page": "1",
            "xPos": "129.82",
            "yPos": "117",
            "width": "139",
            "height": "23",
            "text": "Nome completo"
        }
    ],
    "base64": "JVBERi0xLjQNJeLjz9MNCjY... <PDF em base64>"
}

Resposta

json · response

{
    "status": "success",
    "title": "Template successfully registered",
    "message": {
        "template_key": "Tpl8vHxTToq8RPkob7dFb9JYpx1Oac9J"
    }
}

Adicionar signatário

POSThttps://app.assinabrasil.com.br/api/v1/signatory/new

Adiciona um novo signatário a um documento existente. É necessário informar o document_key.

Parâmetros

Nome	Tipo	Descrição
document_keyreq	string	Código do documento.
namereq	string	Nome do signatário.
emailreq	string	E-mail do signatário.
phone	string	Telefone, ex.: (48) 90419-5050.
auth	boolean	Solicita autenticação via Token (padrão false).
positions	json[]	Posições de assinatura no PDF (page, xPos, yPos, width, height).

Sobre as posições: A folha A4 vertical possui 2480 × 3508 px. Informe a posição inicial nos eixos X (horizontal) e Y (vertical), além de width e height. A posição em Y deve desconsiderar o tamanho final da assinatura.

Requisição

json · request body

{
    "document_key": "UdHhu7q9aDnBaQUJDYABzzyVaspslIrs",
    "name": "Fulano da Silva",
    "email": "fulano.teste@assinabrasil.com.br",
    "phone": "(48) 98419-3232",
    "auth": true,
    "positions": [
        { "page": "1", "xPos": "129.82", "yPos": "117", "width": "139", "height": "23" }
    ]
}

Resposta

json · response

{
    "status": "success",
    "title": "Signatory successfully added",
    "message": {
        "signing_key": "a1oGscl0ZhdpE30LefOylCtW87q1dwrD",
        "link": "https://app.assinabrasil.com.br/view/UdHhu7q9aDnBaQUJDYABzzyVaspslIrs?signingKey=a1oGscl0ZhdpE30LefOylCtW87q1dwrD"
    }
}

Consultar signatário

GEThttps://app.assinabrasil.com.br/api/v1/signatory/{signing_key}

Retorna as informações de um signatário específico. O signing_key é entregue ao criar o documento ou ao listar seus signatários.

Resposta

json · response

{
    "status": "success",
    "title": "Signatory found",
    "message": {
        "signing_key": "KX3sr3MzXtoR08EuytUwkYGDyChPqtDn",
        "name": "Fulano da Silva",
        "email": "fulano.teste@assinabrasil.com.br",
        "phone": "48984193232",
        "status": "Pending",
        "auth": "Yes",
        "link": "https://app.assinabrasil.com.br/view/Ee05vHxTToq8RPkob7dFb9JYpx1Oac9J?signingKey=KX3sr3MzXtoR08EuytUwkYGDyChPqtDn"
    }
}

Atualizar signatário

POSThttps://app.assinabrasil.com.br/api/v1/signatory/{signing_key}

Atualiza os dados de um signatário. Útil para corrigir e-mail, telefone ou reenviar a notificação. Não é possível atualizar signatários que já assinaram.

Parâmetros

Nome	Tipo	Descrição
name	string	Novo nome do signatário.
email	string	Novo e-mail.
phone	string	Novo telefone.
auth	boolean	Habilita ou desabilita autenticação via Token.

Requisição

json · request body

{
    "name": "Fulano da Silva",
    "email": "novo.email@assinabrasil.com.br",
    "phone": "(48) 98419-3232",
    "auth": true
}

Resposta

json · response

{
    "status": "success",
    "title": "Signatory successfully updated",
    "message": {
        "signing_key": "aEIt90LOoFi0bCx4azPnTTpsBYZYpN1x"
    }
}

Remover signatário

DELETEhttps://app.assinabrasil.com.br/api/v1/signatory/{signing_key}

Remove um signatário específico de um documento. Importante: caso o signatário já tenha assinado, a remoção não será permitida.

Resposta

json · response

{
    "status": "success",
    "title": "Signatory successfully deleted",
    "message": {}
}