> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/api-rest/identity-api/identity-api-reference/digital-signatures/signer.md). # Signatário Este serviço executa o Fluxo completo de assinatura digital e retorna uma resposta `202 Accepted` imediatamente. O serviço processa a operação de assinatura de forma **assíncrona**. Implementa Assinatura Eletrônica Básica (AdES - BES), proporcionando uma solução robusta e confiável com vantagens significativas em conformidade regulatória, segurança, interoperabilidade e facilidade de uso. #### Callback assíncrono Ao ser concluída a operação — seja bem-sucedida ou malsucedida — o serviço envia uma solicitação POST para a URL especificada no parâmetro `callbackUrl`. Se forem fornecidos `callbackHeaders`, eles serão incluídos na solicitação de callback. * **Assinatura bem-sucedida**: Content-Type `multipart/form-data`. Retorna o documento PDF assinado como anexo. * **Assinatura malsucedida**: Content-Type `application/json`. Retorna um objeto de erro com `operationId` e mensagem de `error`. {% hint style="warning" %} Somente os formatos de imagem **JPEG** e **PNG** são suportados para a visualização da assinatura. Outros formatos resultarão em um erro. {% endhint %} {% hint style="info" %} **Recomendação de segurança:** Sempre consuma esta API a partir da sua infraestrutura de back-end em vez de aplicações de front-end. Essa abordagem protege dados sensíveis, evita a exposição de credenciais e garante o manuseio seguro de documentos durante todo o processo de assinatura. {% endhint %} ### Endpoint ``` POST /signer ``` ### Cabeçalhos | Nome | Tipo | Obrigatório | Descrição | | ------------- | ------ | ----------- | --------------------------------- | | **x-api-key** | string | **Sim** | API Key de autorização de acesso. | ### Corpo da solicitação **Content-Type:** `application/json` #### Parâmetros | Parâmetro | Tipo | Obrigatório | Descrição | | ----------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `document` | string | **Sim** | Documento PDF a ser assinado digitalmente, codificado no formato **Base64** (RFC4648). | | `images` | string\[] | Não | Array de imagens de visualização de assinatura para incorporar no documento. Cada imagem deve estar codificada em **Base64**. Formatos suportados: **JPEG**, **PNG**. | | `image` | string | Não | **Obsoleto.** Use o array `images` em seu lugar. Imagem única para incorporar como visualização de assinatura, codificada em **Base64**. | | `page` | integer | Não | Número da página de destino para a colocação da assinatura, indexado a partir de zero. **Valor padrão:** `0` (primeira página). | | `position` | string | Não | Coordenadas do retângulo de assinatura em pixels a 72 DPI: X inferior esquerdo, Y inferior esquerdo, X superior direito, Y superior direito. Para páginas A4, faixas válidas: X: 0-595, Y: 0-842. Formato: `x1,y1,x2,y2`. **Valor padrão:** `"135,210,480,300"` | | `timezone` | string | Não | Identificador de fuso horário IANA para o formato de data/hora nos metadados de assinatura. Exemplos: `America/Lima`, `Europe/Madrid`, `Asia/Tokyo`. **Valor padrão:** `"UTC"` | | `signature` | string\[] | Não | Linhas de texto personalizadas para mostrar junto à imagem de assinatura. Suporta placeholders dinâmicos: `$(date)s` é substituído pelo carimbo de data/hora atual formatado conforme `dateFormat` e `timezone`. Cada elemento do array representa uma linha de texto. | | `dateFormat` | string | Não | String de formato de data/hora seguindo o padrão ISO 8601 com diretivas strftime. Suporta `%z` para offset de fuso horário. Exemplo: `%d/%m/%Y %H:%M:%S%z`. **Valor padrão:** `"%Y/%m/%d %H:%M:%S%z"` | | `callbackUrl` | string | **Sim** | URL do webhook para receber o documento assinado ou a notificação de erro. O serviço enviará os resultados por POST para este endpoint de forma assíncrona. | | `callbackHeaders` | string | Não | Headers HTTP opcionais para incluir na solicitação de callback. Formato: pares chave=valor separados por ponto e vírgula. Exemplo: `Authorization=Bearer token;X-Custom=value` | #### Exemplo de solicitação ```json { "document": "JVBERi0xLjUKJbXtrvsKNCAwIG9iag...", "images": ["iVBORw0KGgoAAAANSUhEUgAAAEoAAABK..."], "page": 0, "position": "135,210,480,300", "timezone": "America/Lima", "signature": ["ID - 9999999", "Date - $(date)s"], "dateFormat": "%d/%m/%Y %H:%M:%S%z", "callbackUrl": "https://example.com/callback", "callbackHeaders": "Authorization=Bearer token123;Content-Type=application/json" } ``` ### Respostas #### `202` Accepted A solicitação foi aceita e a operação de assinatura está sendo processada de forma assíncrona. O resultado será enviado para a URL de callback fornecida. #### Callback — Assinatura bem-sucedida Content-Type: `multipart/form-data` O documento PDF assinado é retornado como anexo. #### Callback — Assinatura malsucedida Content-Type: `application/json` ```json { "operationId": "910e181e-305c-4d9b-b42b-f177bf3b06ef", "error": "image: formato desconocido" } ``` #### `400` Requisição inválida ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [] } ``` #### `401` Não autorizado ```json { "message": "Unauthorized" } ``` #### `403` Proibido ```json { "Message": "User is not authorized to access this resource with an explicit deny" } ``` #### `502` Gateway inválido ```json { "status": 502, "title": "Bad Gateway", "detail": "Server got an invalid response.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502" } ``` #### `504` Gateway Timeout ```json { "message": "Endpoint request timed out" } ```