--- title: "Guia de Integração" description: "Guia de integração do Signer: opções para integrar a aplicação ao portal de documentos, com autenticação por chave de API no header X-Api-Key." canonical: "https://docs.lacunasoftware.com/articles/signer/integration-guide" locale: "pt-BR" product: "Signer" last_updated: "2026-10-12" --- # Guia de Integração O Signer é um portal de documentos que permite a realização de assinaturas digitais e eletrônicas, bem como a criação de fluxos complexos. Este guia apresenta as opções de integração para que sua aplicação aproveite ao máximo o potencial do Signer. > **Dica: Novo por aqui?** > > Se é a sua primeira integração, comece pelos [Primeiros passos](https://docs.lacunasoftware.com/articles/signer/get-started), que levam você do zero ao primeiro documento assinado em cerca de 15 minutos. Este guia serve como referência dos casos de uso. ## Autenticação Todas as chamadas de API exigem uma chave de acesso de API (*API Key*). Essa chave deve ser colocada no cabeçalho de todas as requisições: ```javascript X-Api-Key: sua-aplicacao|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` Toda chave de API está associada a uma Organização previamente cadastrada no Signer. Sendo assim, o escopo dessa chave fica **restrito àquela organização**, isto é, aquela chave só permitirá acessar/criar documentos daquela organização. > **Observação** > > Para obter uma chave de API: se você tem permissão para criar aplicações na organização, crie uma aplicação em **Aplicações** e gere a chave com o botão **Chaves** dela, como mostram os [Primeiros passos](https://docs.lacunasoftware.com/articles/signer/get-started#passo-1-crie-a-aplicação-e-a-chave-de-api). Caso contrário, peça uma chave ao administrador da sua instância. ## Bibliotecas cliente A Lacuna publica uma biblioteca cliente da API para .NET, Java, Node.js e PHP. Você cria o cliente com a URL da sua instância do Signer e a chave de API, e chama as APIs pelos métodos dele. Também é possível chamar a API REST diretamente de qualquer linguagem, como fazem os [Primeiros passos](https://docs.lacunasoftware.com/articles/signer/get-started) com curl. | Linguagem | Pacote | Versão | Instalação | | --- | --- | --- | --- | | .NET (.NET Framework 4.5 ou posterior, .NET Standard 2.0) | [`Lacuna.Signer.Client`](https://www.nuget.org/packages/Lacuna.Signer.Client) | 1.24.0 | `dotnet add package Lacuna.Signer.Client` | | Java | [`com.lacunasoftware.signer:signer-client`](https://central.sonatype.com/artifact/com.lacunasoftware.signer/signer-client) | 2.14.0 | Gradle: `implementation 'com.lacunasoftware.signer:signer-client:2.14.0'` | | Node.js | [`signer-node-client`](https://www.npmjs.com/package/signer-node-client) | 1.1.0 | `npm install signer-node-client` | | PHP | [`lacuna/signer-client`](https://packagist.org/packages/lacuna/signer-client) | 1.4.10 | `composer require lacuna/signer-client` | Os [exemplos no GitHub](https://github.com/LacunaSoftware/SignerSamples) usam essas bibliotecas, com um cenário por caso de uso deste guia. Para embutir a tela de assinatura na sua página web, use a biblioteca JavaScript `lacuna-signer-widget`: veja [Assinatura embutida](https://docs.lacunasoftware.com/articles/signer/embedded-signature). ## Como o fluxo funciona Na prática, uma integração com o Signer segue quatro etapas. Cada etapa tem uma página dedicada neste guia: 1. **[Criar documentos](https://docs.lacunasoftware.com/articles/signer/integration/documents)**: envie o arquivo, monte o fluxo de participantes e (opcionalmente) assine dentro da sua própria aplicação. 2. **[Acompanhar documentos](https://docs.lacunasoftware.com/articles/signer/integration/tracking)**: verifique o status, envie lembretes e receba notificações por webhook. 3. **[Baixar e listar](https://docs.lacunasoftware.com/articles/signer/integration/download-and-list)**: obtenha as versões do documento e liste documentos por diferentes critérios. 4. **[Validar assinaturas](https://docs.lacunasoftware.com/articles/signer/integration/validation)**: valide as assinaturas por chave de validação ou pelo arquivo assinado. E, ao longo da vida do documento, você pode precisar de operações de **[ciclo de vida](https://docs.lacunasoftware.com/articles/signer/integration/lifecycle)**: cancelar, recusar, enviar nova versão ou deletar. ## Casos de uso | Caso de uso | O que você faz | | --- | --- | | [Criar documentos](https://docs.lacunasoftware.com/articles/signer/integration/documents) | Upload, criação do fluxo, assinatura embutida, pré-posicionamento de assinaturas e envelopes (múltiplos arquivos) | | [Acompanhar documentos](https://docs.lacunasoftware.com/articles/signer/integration/tracking) | Verificar status do documento e dos participantes, enviar lembretes e configurar webhooks | | [Baixar e listar](https://docs.lacunasoftware.com/articles/signer/integration/download-and-list) | Baixar as diferentes versões do documento e listar documentos | | [Validar assinaturas](https://docs.lacunasoftware.com/articles/signer/integration/validation) | Validar assinaturas por chave ou por arquivo assinado | | [Ciclo de vida do documento](https://docs.lacunasoftware.com/articles/signer/integration/lifecycle) | Cancelar, recusar, enviar nova versão e deletar | ## Respostas de erro As APIs respondem com estes códigos de status HTTP: | Código | Significado | | --- | --- | | `200` (OK) | Requisição processada. O corpo da resposta depende da API: veja a entrada dela na [referência da API](https://www.dropsigner.com/swagger). | | `400` (Bad Request) | Erro de sintaxe, por exemplo um campo obrigatório que não foi enviado. | | `401` (Unauthorized) | A chave de API não foi enviada ou é inválida. | | `403` (Forbidden) | A chave de API é válida, mas a aplicação dela não tem permissão para a operação pedida. | | `422` (Unprocessable Entity) | Erro da API, por exemplo um ID de entidade que não foi encontrado. O corpo é um `ErrorModel`. | Um `ErrorModel` tem três campos: | Campo | Tipo | Conteúdo | | --- | --- | --- | | `code` | string | O código do erro. Teste este campo no seu código, e não a mensagem. | | `message` | string | Uma descrição do erro. | | `details` | objeto, com valores string | Informações adicionais sobre o erro. Pode ser `null`. | ```json { "code": "DocumentNotFound", "message": "...", "details": null } ``` A referência da API lista os principais códigos de uma resposta `422`: `CertificateNotFound`, `DocumentNotFound`, `FolderNotFound`, `CpfMismatch`, `CpfNotExpected`, `InvalidFlowAction` e `DocumentInvalidKey`. A lista não é completa, e novos códigos podem ser incluídos a qualquer momento sem aviso, então trate também os códigos que você não conhece. Outras páginas descrevem os códigos das suas operações, como `DocumentHasNoSignatures` ao [baixar uma versão](https://docs.lacunasoftware.com/articles/signer/integration/download-and-list#quando-uma-versão-não-pode-ser-baixada) e `MaxWebhooksLimitReached` ao [cadastrar um webhook](https://docs.lacunasoftware.com/articles/signer/webhooks#pela-api). ## Links Úteis * [Referência da API (Swagger)](https://www.dropsigner.com/swagger) * [Exemplos no GitHub](https://github.com/LacunaSoftware/SignerSamples) * [Assinatura embutida (Widget)](https://docs.lacunasoftware.com/articles/signer/embedded-signature) * [Webhooks](https://docs.lacunasoftware.com/articles/signer/webhooks) **Demonstrações e exemplos** - Generate a document from a PDF form template and CSV data: [Java](https://github.com/LacunaSoftware/SignerSamples/blob/master/java/console/src/main/java/com/lacunasoftware/signer/sample/scenarios/GenerateDocumentWithTwoOrMoreSignersScenario.java) · [PHP](https://github.com/LacunaSoftware/SignerSamples/blob/master/php/Scenarios/GenerateDocumentWithTwoOrMoreSignersScenario.php) - List saved document flows: [Node.js](https://github.com/LacunaSoftware/SignerSamples/blob/master/nodejs/scenarios/listDocumentScenario.ts)