@assinafy/piece-assinafy 0.1.0

package/README.md

@@ -0,0 +1,267 @@
+# Assinafy for Activepieces
+
+[Português (Brasil)](README.pt-BR.md)
+
+Send documents for legally valid electronic signature with [Assinafy](https://www.assinafy.com.br) and act on the result in [Activepieces](https://www.activepieces.com) flows: upload a PDF, invite signers by email or WhatsApp, wait for the signatures and store the signed PDF wherever you need it.
+
+- Package: `@assinafy/piece-assinafy`
+- Requires Activepieces 0.88.2 or later
+- API reference: <https://api.assinafy.com.br/v1/docs>
+
+## Install
+
+As a platform admin of your Activepieces instance:
+
+1. Open **Platform Admin → Setup → Pieces** and click **Install Piece**.
+2. Choose **NPM Registry**, enter the package name `@assinafy/piece-assinafy` and the version, for example `0.1.0`.
+3. The piece appears as **Assinafy** in the flow builder.
+
+To update, install the new version the same way.
+
+## Connect your Assinafy account
+
+The piece offers two connection types. Use **API Key** to automate your own workspace, and **Assinafy Account (OAuth)** when other people connect their own workspaces.
+
+### API Key
+
+1. Sign in to [Assinafy](https://app.assinafy.com.br) (or the [sandbox](https://app-sandbox.assinafy.com.br) for testing).
+2. Open **My Account → API** and create an API key. A dedicated Assinafy user for automations keeps its access easy to control.
+3. In Activepieces, create an Assinafy connection of type **API Key**:
+   - **API Key**: the key you created.
+   - **Environment**: **Production**, or **Sandbox** for keys created in the sandbox.
+   - **Workspace ID**: only needed when your user belongs to more than one workspace. Copy it from **My Account → Workspaces**.
+
+The connection is checked when you save it, and it is labelled with the workspace name.
+
+### Assinafy Account (OAuth)
+
+An owner of the Assinafy workspace registers an OAuth application once, under **Settings → OAuth applications**:
+
+| Field | Value |
+|---|---|
+| Redirect URI | The redirect URL shown by Activepieces in the connection dialog, for example `https://automations.example.com/redirect` |
+| Type | Confidential |
+| Permissions | `documents:read`, `documents:write`, `templates:read`, `templates:write`, `account:read`, `webhooks:write`, `offline_access` |
+
+Enter the application's Client ID and Client Secret in Activepieces, then sign in and choose the workspace to connect. Each OAuth connection works with exactly one workspace. OAuth always uses the production environment; use an API key for the sandbox.
+
+Assinafy ends OAuth connections 30 days after the user approves them, and refreshing does not extend that. Reconnect monthly, or use an API key for automations that must run unattended.
+
+## Common flows
+
+**Send a PDF for signature**
+
+1. Any trigger that provides a file (a form, an email attachment, a CRM record).
+2. **Upload Document** with that file.
+3. **Request Signatures** on the uploaded document, with each signer's name and email or WhatsApp number.
+
+**Store every signed contract**
+
+1. **Document Signed** trigger.
+2. **Download Document** with **File** set to *Signed PDF*.
+3. Upload the file to your storage (Google Drive, SharePoint, S3…).
+
+**Generate a contract from a template**
+
+1. Any trigger with the customer's details.
+2. **Create Document from Template**: pick the template, fill the signer for each role and the template fields.
+
+## Actions
+
+| Action | What it does | Main inputs | Output |
+|---|---|---|---|
+| Upload Document | Uploads a PDF (up to 25 MB) | File, optional name | Document |
+| Request Signatures | Sends a document for signature; waits up to 30 seconds while the file of a fresh upload is still being received | Document, signers (name, email or WhatsApp, verification, CPF/CNPJ, signing order), message, deadline, copy recipients | Signature request |
+| Create Document from Template | Creates a document from a ready template and sends it | Template, a signer per role, template fields, name, message, deadline, tags | Document |
+| Get Document | Reads a document and its signing progress | Document | Document |
+| Find Documents | Searches documents, newest update first | Search text, status, maximum results (1–100) | List of documents |
+| Download Document | Saves a document file for later steps; waits up to a minute while certification finishes | Document, file (signed PDF, original, certificate page, ZIP bundle, PAdES), file name | File |
+| Resend Signature Request | Sends the invitation to a signer again | Document, signer | Send result |
+| Update Signing Deadline | Sets a new deadline on the signature request | Document, new deadline | Signature request |
+| Delete Document | Permanently deletes a document that is not signed | Document | Confirmation |
+| Find Signers | Searches saved signers | Search text, maximum results (1–100) | List of signers |
+| Create Signer | Saves a signer | Full name, email, WhatsApp, CPF/CNPJ | Signer |
+| Update Signer | Changes a saved signer | Signer, fields to change | Signer |
+| Custom API Call | Calls any endpoint of the Assinafy API with the connection's credentials, which are sent only to the connection's Assinafy address (so **Follow redirects** must stay off) | Method, URL, headers, query, body | Raw API response |
+
+Every document, signer and template input is a dropdown, searchable except for the signer in **Resend Signature Request**, which lists the signers of the chosen document. You can also map an ID from a previous step.
+
+### Signers
+
+**Request Signatures** and **Create Document from Template** take contact details, not Assinafy signer IDs:
+
+- A signer is matched by email, or by name and WhatsApp number when there is no email, so give the full name of a signer who has only a WhatsApp number. WhatsApp numbers match regardless of formatting, and a number without the country code matches the saved international number.
+- If nobody matches, a signer is created, which requires a full name.
+- A missing WhatsApp number is added to an existing signer. A WhatsApp number that differs from the saved one stops the step with an error instead of using the saved value.
+- A CPF/CNPJ is saved only when the signer is created. Assinafy does not show saved CPFs, so the step cannot compare them and never changes the CPF of an existing signer.
+- Change saved details with **Update Signer**; changing a channel invalidates invitations that were already sent.
+- Every signer and copy recipient row is checked, and every one of them is looked up, before any signer is created or changed: a contact for the chosen channel, a valid CPF or CNPJ (including its check digits), no repeated email or WhatsApp number, no person reached twice through different details, and the signing order rules below.
+
+### Verification and costs
+
+| Verification | Invitation | Cost per signer |
+|---|---|---|
+| Email code (default) | Email | Free |
+| WhatsApp code | WhatsApp | 0.45 credit (paid plans) |
+| ICP-Brasil digital certificate | Email | 2 credits |
+| ICP-Brasil digital certificate | WhatsApp | 2.45 credits |
+
+When **Verification** is empty, it is email, or WhatsApp when the signer has only a WhatsApp number. Digital certificate signing needs the Digital Certificate feature on the Assinafy plan, the signer's CPF or CNPJ saved in Assinafy (given in the step when the signer is new, or set with **Update Signer**), and the signer alone in their signing order step. Every signature request also uses one document from the plan, or one credit when the allowance is used up.
+
+Copy recipients may not be available on every Assinafy plan. When Assinafy does not keep a requested copy recipient, **Request Signatures** fails after sending, with the signature request ID; do not run it again for the same document, or the signers are invited twice.
+
+### Signing order
+
+Leave **Signing Order** empty for everyone to sign at the same time. To sign in sequence, set it on every signer: all signers with `1` are invited first, `2` after all of them sign, and so on. The numbers must start at 1 without gaps, and a digital certificate signer cannot share a number with anyone.
+
+In **Create Document from Template**, each signer role of the template has its own email, WhatsApp number, full name, CPF/CNPJ, verification and signing order inputs. Editor roles are not signers: their fields appear under **Template Fields**.
+
+## Triggers
+
+| Trigger | When it fires | Delivery |
+|---|---|---|
+| Document Signed | Every signer has signed and the signed PDF is ready, for signings completed after the flow was turned on | Checked every few minutes. Any number of flows can use it. |
+| New Event (Instant) | The selected Assinafy events happen: document signed by all, signer signed, signer declined, document cancelled, and more | Instant, through the workspace webhook |
+
+**New Event (Instant)** uses the workspace webhook, and Assinafy delivers each workspace's events to a single address:
+
+- Use it in only one active flow per workspace; add a Router step to handle several event types.
+- If the workspace already delivers events to another system, the flow does not start unless **Replace Existing Webhook** is turned on.
+- Turning the flow off stops the webhook, but only while it still points at that flow.
+- **Delivery Notice Email** receives Assinafy's notices about failed deliveries. It is required only when the workspace has no address yet.
+- For document events, the flow receives the current state of the document, read from the API when the event arrives. If it cannot be read (for example after the document was deleted), the copy sent with the event is used.
+- Assinafy retries a failed delivery once. Activepieces drops a repeated event that arrives within 30 seconds; for later repeats, `event_id` identifies the event.
+- Each flow registers its webhook address with a random secret, and requests without it are ignored. The secret stays the same when the flow is republished or turned off and on, so deliveries already on their way still count. Assinafy does not sign its webhook requests, so keep the address private.
+
+The document is signed as soon as the last signer signs, but the signed PDF is available only after certification finishes. **Document Signed** fires after certification; **Download Document** also waits up to a minute while certification is still running.
+
+**Document Signed** fires once per document whose signing completed after the flow was turned on. It reads each new signed document's activity log for the completion time, so documents signed earlier and edited later (for example tagged) do not fire it. Each check looks back ten minutes to tolerate clock differences. After downtime it catches up on the backlog over several checks, without skipping or repeating any.
+
+## Output fields
+
+Outputs are flat and ready for tables and spreadsheets, except `signers`, which lists one record per signer so flows can loop over them.
+
+Document outputs:
+
+| Field | Description |
+|---|---|
+| `id`, `name` | Document ID and name |
+| `account_id`, `signing_url` | The workspace, and the link to the signing page |
+| `status`, `status_label` | Status code (for example `pending_signature`, `certificated`) and its readable label |
+| `is_closed` | Whether the signing process is finished |
+| `available_files` | Files that can be downloaded, for example `original, certificated, certificate-page, bundle` |
+| `signer_count`, `signed_count`, `signer_emails` | Signing progress |
+| `signers` | One entry per signer: name, email, WhatsApp, step, verification, whether they signed, signing link |
+| `assignment_id`, `signature_method`, `expires_at` | The signature request and its deadline |
+| `decline_reason`, `declined_by_name`, `declined_by_email` | Filled when a signer declines |
+| `tags`, `page_count`, `template_id`, `created_at`, `updated_at` | Other document details |
+
+**New Event (Instant)** outputs:
+
+| Field | Description |
+|---|---|
+| `event_id`, `event`, `message`, `occurred_at` | The event, for example `document_ready`, and when it happened |
+| `account_id` | The workspace |
+| `actor_type`, `actor_id`, `actor_name`, `actor_email` | Who caused it: a user, signer or the workspace |
+| `object_type`, `object_id`, `object_name` | What it happened to: a document, signer or template |
+| `detail_*` | Event details, for example `detail_signer_email` or `detail_error_message` |
+| `document_*` | Every document field above, prefixed with `document_`; empty for events about signers or templates |
+
+## Troubleshooting
+
+| Message | What to do |
+|---|---|
+| `HTTP 401 … check the API key` | The key is wrong, was deleted, or belongs to the other environment. Create a new key or change **Environment**. |
+| `This API key can access N workspaces` | Set **Workspace ID** on the connection. |
+| `… is not available for this document yet` | The file does not exist yet, for example the signed PDF before everyone signs. |
+| `This Assinafy workspace already sends its webhooks to …` | Another system receives the workspace events. Turn on **Replace Existing Webhook** only if that system no longer needs them, or use **Document Signed**. |
+| `HTTP 403 … approved permissions` | The OAuth connection lacks a permission. Add it to the OAuth application and reconnect. |
+| `HTTP 401` on an OAuth connection that used to work | OAuth connections end 30 days after approval. Reconnect. |
+| `… is saved in Assinafy with a different WhatsApp number` | Update the signer with **Update Signer**, or leave WhatsApp Number empty to use the saved number. |
+| `… must be the only signer in their signing order step` | Give the digital certificate signer a signing order number of their own. |
+| `Assinafy is still receiving the file of this document` | The upload was still in progress after 30 seconds. Run the step again, or add a Delay step after **Upload Document**. |
+
+## Development
+
+The piece lives in the Activepieces monorepo at `packages/pieces/community/assinafy`. Requirements: Node.js 24 LTS and Bun.
+
+```sh
+bun install
+npx turbo run build --filter=@assinafy/piece-assinafy
+npx turbo run lint --filter=@assinafy/piece-assinafy
+cd packages/pieces/community/assinafy
+npm run typecheck        # source and tests
+npm test                 # unit tests, no network
+npm run test:coverage    # with coverage thresholds
+```
+
+Unit tests mock the HTTP client and block any real network request. One upload test runs the real Activepieces HTTP client against a stubbed `fetch` to check the multipart request on the wire.
+
+### Implementation notes
+
+- Requests made by triggers time out after 15 seconds, well within the time Activepieces gives a trigger run; actions allow 120 seconds.
+- When two runs create the same new signer at the same moment, the run that loses reuses the signer the other one created.
+- Requests do not follow redirects automatically. A redirect is followed only for reads and downloads, and the credentials are left out when it points outside the Assinafy address, for example to file storage.
+- Uploads use the `form-data` package. The Activepieces HTTP client sets the multipart content type and boundary only for `form-data` bodies; a global `FormData` body would be sent as JSON.
+- Assinafy's create-signer endpoint does not accept a CPF/CNPJ, so it is set with a follow-up update.
+- Assinafy returns at most 50 items per list page, and repeats the last page when asked for a page beyond the end. List reads follow the `X-Pagination-Page-Count` header and stop at a short or repeated page.
+- The API reference documents no single-template endpoint, so the template form and action scan up to 500 templates.
+- **Document Signed** keeps its own state and keeps it when a flow is republished: the time it was turned on, the last completed check, the position of an unfinished backlog scan, and a ledger of documents it fired recently.
+  - Signed documents are listed newest first, cannot be deleted, and only move down the list as others are signed or edited. A backlog scan therefore resumes after the last document it examined (by update time and ID), and the time checkpoint advances only when the scan has reached documents older than the previous check.
+  - A document fires when its completion time (the newest `document_ready` activity, else the newest `signer_signed_document`) is after the trigger was turned on and no more than 24 hours before the start of the check window. A document with neither activity does not fire. The ledger remembers the documents fired in that period so later edits do not fire them again, drops entries that can no longer pass the rule, and holds at most 5,000 entries to stay within the Activepieces store limit.
+  - Each check reads at most 10 pages of 50 documents and 40 activity logs, and stops after 30 seconds; the next check continues where it stopped. An error after some documents were examined keeps that progress; an error before any fails the check.
+  - A document whose activity log cannot be read is tried again on the next two checks. After that it fires with its update time as the completion time, so one broken document cannot stop the trigger.
+  - Activepieces saves a polling trigger's progress before it starts the flow runs for the returned items. If starting them fails, those documents are not returned again. This applies to every Activepieces polling trigger; the piece gets no signal to replay them.
+
+### Sandbox tests
+
+`test/live.test.ts` runs against the Assinafy sandbox only and deletes everything it creates:
+
+```sh
+ASSINAFY_API_KEY=<sandbox key> npm run test:live
+```
+
+| Variable | Effect |
+|---|---|
+| `ASSINAFY_ACCOUNT_ID` | Workspace to use when the key has several |
+| `ASSINAFY_LIVE_SEND=1` | Also sends a signature request to an `example.com` address (uses one plan document) |
+| `ASSINAFY_LIVE_WEBHOOK=1` | Also enables and disables the workspace webhook; fails instead of replacing another destination |
+| `ASSINAFY_LIVE_WEBHOOK_EMAIL` | Delivery notice address for the webhook check (defaults to an `example.com` address) |
+
+The suite also reads a document's activity log, which **Document Signed** relies on.
+
+### Try it in a local Activepieces
+
+Add `AP_DEV_PIECES=assinafy` to `packages/server/api/.env`, run `npm start` from the repository root and open <http://localhost:4200>.
+
+### Translations
+
+`src/i18n/translation.json` is generated from the piece and `src/i18n/pt.json` holds the Brazilian Portuguese strings. After changing any display name, description or option label:
+
+```sh
+npm run cli -- pieces generate-translation-file assinafy
+```
+
+If the command stops on a type error outside this piece, run it as `TS_NODE_TRANSPILE_ONLY=true npm run cli -- pieces generate-translation-file assinafy`. Then update `pt.json`. The tests fail while either file is out of date.
+
+Activepieces does not translate the connection dialog of a piece with more than one connection type, so the dialog is shown in English.
+
+### Publishing
+
+1. Bump `version` in `package.json` (patch for new actions, optional inputs and fixes; major for removals, new required inputs or changed behavior) and add the release to `CHANGELOG.md`.
+2. Run `npm run licenses` in this folder. It rewrites `LICENSE` with the license of every package bundled into the published file.
+3. Sign in to npm (`npm login`) with an account that can publish to the `@assinafy` scope.
+4. From the repository root:
+
+   ```sh
+   TS_NODE_TRANSPILE_ONLY=true npm_config_dry_run=true npm run publish-piece assinafy   # check the package, publishes nothing
+   TS_NODE_TRANSPILE_ONLY=true npm run publish-piece assinafy
+   ```
+
+   `TS_NODE_TRANSPILE_ONLY=true` skips an unrelated type error elsewhere in the repository that stops the script. The script builds the piece, bundles it into a single file with the Activepieces libraries inlined, checks that no workspace or `@activepieces/*` dependency is left, and publishes it with public access together with the READMEs, `LICENSE` and `CHANGELOG.md`. It skips a version that is already on npm, so bump the version before publishing changes.
+
+Never rename an action, trigger or input after release: flows reference them by name.
+
+## License
+
+MIT. The published package also bundles the Activepieces libraries and a few npm packages; `LICENSE` lists each one with its license.

package/README.pt-BR.md

@@ -0,0 +1,267 @@
+# Assinafy para Activepieces
+
+[English](README.md)
+
+Envie documentos para assinatura eletrônica com validade jurídica pela [Assinafy](https://www.assinafy.com.br) e use o resultado em fluxos do [Activepieces](https://www.activepieces.com): envie um PDF, convide os signatários por e-mail ou WhatsApp, aguarde as assinaturas e guarde o PDF assinado onde precisar.
+
+- Pacote: `@assinafy/piece-assinafy`
+- Requer Activepieces 0.88.2 ou superior
+- Referência da API: <https://api.assinafy.com.br/v1/docs>
+
+## Instalação
+
+Como administrador da plataforma na sua instância do Activepieces:
+
+1. Abra **Platform Admin → Setup → Pieces** e clique em **Install Piece**.
+2. Escolha **NPM Registry**, informe o nome do pacote `@assinafy/piece-assinafy` e a versão, por exemplo `0.1.0`.
+3. A peça aparece como **Assinafy** no editor de fluxos.
+
+Para atualizar, instale a nova versão da mesma forma.
+
+## Conectar sua conta Assinafy
+
+A peça oferece dois tipos de conexão. Use **API Key** para automatizar o seu próprio espaço de trabalho e **Assinafy Account (OAuth)** quando outras pessoas conectarem os espaços de trabalho delas.
+
+### API Key
+
+1. Entre na [Assinafy](https://app.assinafy.com.br) (ou no [sandbox](https://app-sandbox.assinafy.com.br) para testes).
+2. Abra **Minha Conta → API** e crie uma chave de API. Um usuário da Assinafy dedicado às automações facilita o controle do acesso.
+3. No Activepieces, crie uma conexão Assinafy do tipo **API Key**:
+   - **API Key**: a chave criada.
+   - **Environment**: **Production**, ou **Sandbox** para chaves criadas no sandbox.
+   - **Workspace ID**: necessário apenas quando o seu usuário pertence a mais de um espaço de trabalho. Copie de **Minha Conta → Espaços de trabalho**.
+
+A conexão é verificada ao salvar e recebe o nome do espaço de trabalho.
+
+### Assinafy Account (OAuth)
+
+Um proprietário do espaço de trabalho na Assinafy registra uma aplicação OAuth uma única vez, em **Configurações → Aplicações OAuth**:
+
+| Campo | Valor |
+|---|---|
+| URI de redirecionamento | A URL de redirecionamento exibida pelo Activepieces na janela de conexão, por exemplo `https://automations.example.com/redirect` |
+| Tipo | Confidencial |
+| Permissões | `documents:read`, `documents:write`, `templates:read`, `templates:write`, `account:read`, `webhooks:write`, `offline_access` |
+
+Informe o Client ID e o Client Secret da aplicação no Activepieces, depois entre na Assinafy e escolha o espaço de trabalho a conectar. Cada conexão OAuth funciona com exatamente um espaço de trabalho. O OAuth sempre usa o ambiente de produção; para o sandbox, use uma chave de API.
+
+A Assinafy encerra conexões OAuth 30 dias após a aprovação do usuário, e a renovação do token não estende esse prazo. Conecte novamente todo mês ou use uma chave de API em automações que precisam rodar sem intervenção.
+
+## Fluxos comuns
+
+**Enviar um PDF para assinatura**
+
+1. Qualquer gatilho que forneça um arquivo (um formulário, um anexo de e-mail, um registro de CRM).
+2. **Upload Document** (Enviar Documento) com esse arquivo.
+3. **Request Signatures** (Solicitar Assinaturas) no documento enviado, com o nome e o e-mail ou WhatsApp de cada signatário.
+
+**Guardar todo contrato assinado**
+
+1. Gatilho **Document Signed** (Documento Assinado).
+2. **Download Document** (Baixar Documento) com **File** (Arquivo) definido como *PDF assinado*.
+3. Envie o arquivo para o seu armazenamento (Google Drive, SharePoint, S3…).
+
+**Gerar um contrato a partir de um modelo**
+
+1. Qualquer gatilho com os dados do cliente.
+2. **Create Document from Template** (Criar Documento a partir de Modelo): escolha o modelo, preencha o signatário de cada papel e os campos do modelo.
+
+## Ações
+
+| Ação | O que faz | Principais entradas | Saída |
+|---|---|---|---|
+| Enviar Documento | Envia um PDF (até 25 MB) | Arquivo, nome opcional | Documento |
+| Solicitar Assinaturas | Envia um documento para assinatura; aguarda até 30 segundos enquanto o arquivo de um envio recente ainda está sendo recebido | Documento, signatários (nome, e-mail ou WhatsApp, verificação, CPF/CNPJ, ordem de assinatura), mensagem, prazo, destinatários de cópia | Solicitação de assinatura |
+| Criar Documento a partir de Modelo | Cria um documento a partir de um modelo pronto e o envia | Modelo, um signatário por papel, campos do modelo, nome, mensagem, prazo, etiquetas | Documento |
+| Obter Documento | Lê um documento e o progresso das assinaturas | Documento | Documento |
+| Buscar Documentos | Busca documentos, dos atualizados mais recentemente para os mais antigos | Texto de busca, status, máximo de resultados (1 a 100) | Lista de documentos |
+| Baixar Documento | Salva um arquivo do documento para as próximas etapas; aguarda até um minuto enquanto a certificação termina | Documento, arquivo (PDF assinado, original, página do certificado, pacote ZIP, PAdES), nome do arquivo | Arquivo |
+| Reenviar Solicitação de Assinatura | Envia o convite novamente para um signatário | Documento, signatário | Resultado do envio |
+| Atualizar Prazo de Assinatura | Define um novo prazo para a solicitação de assinatura | Documento, novo prazo | Solicitação de assinatura |
+| Excluir Documento | Exclui permanentemente um documento não assinado | Documento | Confirmação |
+| Buscar Signatários | Busca signatários cadastrados | Texto de busca, máximo de resultados (1 a 100) | Lista de signatários |
+| Criar Signatário | Cadastra um signatário | Nome completo, e-mail, WhatsApp, CPF/CNPJ | Signatário |
+| Atualizar Signatário | Altera um signatário cadastrado | Signatário, campos a alterar | Signatário |
+| Chamada de API Personalizada | Chama qualquer endpoint da API da Assinafy com as credenciais da conexão, que são enviadas apenas ao endereço da Assinafy da conexão (por isso **Follow redirects** (Seguir redirecionamentos) deve ficar desativado) | Método, URL, cabeçalhos, parâmetros, corpo | Resposta da API |
+
+Toda entrada de documento, signatário e modelo é uma lista suspensa, com busca exceto o signatário em **Reenviar Solicitação de Assinatura**, que lista os signatários do documento escolhido. Você também pode mapear um ID de uma etapa anterior.
+
+### Signatários
+
+**Solicitar Assinaturas** e **Criar Documento a partir de Modelo** recebem dados de contato, não IDs de signatários da Assinafy:
+
+- O signatário é identificado pelo e-mail, ou pelo nome e número de WhatsApp quando não há e-mail, então informe o nome completo de um signatário que tem apenas WhatsApp. Números de WhatsApp são comparados sem considerar a formatação, e um número sem o código do país corresponde ao número internacional cadastrado.
+- Se ninguém corresponder, um signatário é criado, o que exige o nome completo.
+- Um número de WhatsApp ausente é adicionado a um signatário existente. Um número de WhatsApp diferente do cadastrado interrompe a etapa com um erro, em vez de usar o valor cadastrado.
+- O CPF/CNPJ só é salvo quando o signatário é criado. A Assinafy não mostra CPFs cadastrados, então a etapa não pode compará-los e nunca altera o CPF de um signatário existente.
+- Altere dados cadastrados com **Atualizar Signatário**; alterar um canal invalida convites já enviados.
+- Todas as linhas de signatários e destinatários de cópia são verificadas e buscadas antes de criar ou alterar qualquer signatário: contato para o canal escolhido, CPF ou CNPJ válido (incluindo os dígitos verificadores), nenhum e-mail ou número de WhatsApp repetido, nenhuma pessoa informada duas vezes com dados diferentes e as regras de ordem de assinatura abaixo.
+
+### Verificação e custos
+
+| Verificação | Convite | Custo por signatário |
+|---|---|---|
+| Código por e-mail (padrão) | E-mail | Gratuito |
+| Código por WhatsApp | WhatsApp | 0,45 crédito (planos pagos) |
+| Certificado digital ICP-Brasil | E-mail | 2 créditos |
+| Certificado digital ICP-Brasil | WhatsApp | 2,45 créditos |
+
+Quando **Verification** (Verificação) fica em branco, é usado o e-mail, ou o WhatsApp quando o signatário tem apenas número de WhatsApp. A assinatura com certificado digital exige o recurso Certificado Digital no plano da Assinafy, o CPF ou CNPJ do signatário cadastrado na Assinafy (informado na etapa quando o signatário é novo, ou definido com **Atualizar Signatário**) e que ele esteja sozinho na sua etapa da ordem de assinatura. Toda solicitação de assinatura também consome um documento do plano, ou um crédito quando a franquia acaba.
+
+Destinatários de cópia podem não estar disponíveis em todos os planos da Assinafy. Quando a Assinafy não mantém um destinatário de cópia pedido, **Solicitar Assinaturas** falha depois do envio, informando o ID da solicitação de assinatura; não execute a etapa de novo para o mesmo documento, senão os signatários são convidados duas vezes.
+
+### Ordem de assinatura
+
+Deixe **Signing Order** (Ordem de Assinatura) em branco para que todos assinem ao mesmo tempo. Para assinar em sequência, preencha em todos os signatários: todos com `1` são convidados primeiro, `2` depois que todos eles assinarem, e assim por diante. Os números devem começar em 1 sem pular valores, e um signatário com certificado digital não pode compartilhar o número com ninguém.
+
+Em **Criar Documento a partir de Modelo**, cada papel de signatário do modelo tem suas próprias entradas de e-mail, número de WhatsApp, nome completo, CPF/CNPJ, verificação e ordem de assinatura. Papéis de editor não são signatários: seus campos aparecem em **Template Fields** (Campos do Modelo).
+
+## Gatilhos
+
+| Gatilho | Quando dispara | Entrega |
+|---|---|---|
+| Documento Assinado | Todos os signatários assinaram e o PDF assinado está pronto, para assinaturas concluídas depois que o fluxo foi ativado | Verificado a cada poucos minutos. Qualquer número de fluxos pode usá-lo. |
+| Novo Evento (Instantâneo) | Os eventos escolhidos da Assinafy acontecem: documento assinado por todos, signatário assinou, signatário recusou, documento cancelado e outros | Instantânea, pelo webhook do espaço de trabalho |
+
+**Novo Evento (Instantâneo)** usa o webhook do espaço de trabalho, e a Assinafy entrega os eventos de cada espaço de trabalho para um único endereço:
+
+- Use-o em apenas um fluxo ativo por espaço de trabalho; adicione uma etapa Router para tratar vários tipos de evento.
+- Se o espaço de trabalho já entrega eventos para outro sistema, o fluxo não é iniciado a menos que **Replace Existing Webhook** (Substituir Webhook Existente) esteja ativado.
+- Desativar o fluxo interrompe o webhook, mas apenas enquanto ele ainda aponta para esse fluxo.
+- **Delivery Notice Email** (E-mail para Avisos de Entrega) recebe os avisos da Assinafy sobre falhas de entrega. É obrigatório apenas quando o espaço de trabalho ainda não tem um endereço.
+- Em eventos de documento, o fluxo recebe o estado atual do documento, lido na API quando o evento chega. Se ele não puder ser lido (por exemplo, depois de excluído), é usada a cópia enviada com o evento.
+- A Assinafy tenta novamente uma única vez quando a entrega falha. O Activepieces descarta um evento repetido que chega em até 30 segundos; para repetições posteriores, `event_id` identifica o evento.
+- Cada fluxo registra seu endereço de webhook com um segredo aleatório, e requisições sem ele são ignoradas. O segredo continua o mesmo quando o fluxo é republicado ou desativado e ativado de novo, então entregas já a caminho continuam valendo. A Assinafy não assina as requisições de webhook, então mantenha o endereço em sigilo.
+
+O documento fica assinado assim que o último signatário assina, mas o PDF assinado só fica disponível depois que a certificação termina. **Documento Assinado** dispara depois da certificação; **Baixar Documento** também aguarda até um minuto enquanto a certificação ainda está em andamento.
+
+**Documento Assinado** dispara uma única vez por documento cuja assinatura foi concluída depois da ativação do fluxo. Ele consulta o histórico de atividades de cada novo documento assinado para obter o momento da conclusão, então documentos assinados antes e alterados depois (por exemplo, com uma etiqueta nova) não o disparam. Cada verificação olha dez minutos para trás para tolerar diferenças de relógio. Depois de uma indisponibilidade, ele processa o acúmulo ao longo de várias verificações, sem pular nem repetir nenhum.
+
+## Campos de saída
+
+As saídas são planas e prontas para tabelas e planilhas, exceto `signers`, que traz um registro por signatário para que os fluxos possam percorrê-los.
+
+Saídas de documento:
+
+| Campo | Descrição |
+|---|---|
+| `id`, `name` | ID e nome do documento |
+| `account_id`, `signing_url` | O espaço de trabalho e o link para a página de assinatura |
+| `status`, `status_label` | Código do status (por exemplo `pending_signature`, `certificated`) e seu rótulo legível |
+| `is_closed` | Se o processo de assinatura terminou |
+| `available_files` | Arquivos que podem ser baixados, por exemplo `original, certificated, certificate-page, bundle` |
+| `signer_count`, `signed_count`, `signer_emails` | Progresso das assinaturas |
+| `signers` | Um item por signatário: nome, e-mail, WhatsApp, etapa, verificação, se assinou, link de assinatura |
+| `assignment_id`, `signature_method`, `expires_at` | A solicitação de assinatura e seu prazo |
+| `decline_reason`, `declined_by_name`, `declined_by_email` | Preenchidos quando um signatário recusa |
+| `tags`, `page_count`, `template_id`, `created_at`, `updated_at` | Outros dados do documento |
+
+Saídas de **Novo Evento (Instantâneo)**:
+
+| Campo | Descrição |
+|---|---|
+| `event_id`, `event`, `message`, `occurred_at` | O evento, por exemplo `document_ready`, e quando aconteceu |
+| `account_id` | O espaço de trabalho |
+| `actor_type`, `actor_id`, `actor_name`, `actor_email` | Quem o causou: um usuário, um signatário ou o espaço de trabalho |
+| `object_type`, `object_id`, `object_name` | Com o que aconteceu: um documento, signatário ou modelo |
+| `detail_*` | Detalhes do evento, por exemplo `detail_signer_email` ou `detail_error_message` |
+| `document_*` | Todos os campos de documento acima, com o prefixo `document_`; vazios em eventos de signatários ou modelos |
+
+## Solução de problemas
+
+| Mensagem | O que fazer |
+|---|---|
+| `HTTP 401 … check the API key` | A chave está errada, foi excluída ou pertence ao outro ambiente. Crie uma nova chave ou altere **Environment**. |
+| `This API key can access N workspaces` | Preencha **Workspace ID** na conexão. |
+| `… is not available for this document yet` | O arquivo ainda não existe, por exemplo o PDF assinado antes de todos assinarem. |
+| `This Assinafy workspace already sends its webhooks to …` | Outro sistema recebe os eventos do espaço de trabalho. Ative **Replace Existing Webhook** apenas se esse sistema não precisar mais deles, ou use **Documento Assinado**. |
+| `HTTP 403 … approved permissions` | Falta uma permissão na conexão OAuth. Adicione-a à aplicação OAuth e conecte novamente. |
+| `HTTP 401` em uma conexão OAuth que funcionava | Conexões OAuth terminam 30 dias após a aprovação. Conecte novamente. |
+| `… is saved in Assinafy with a different WhatsApp number` | Atualize o signatário com **Atualizar Signatário** ou deixe o número de WhatsApp em branco para usar o cadastrado. |
+| `… must be the only signer in their signing order step` | Dê ao signatário com certificado digital um número de ordem de assinatura só dele. |
+| `Assinafy is still receiving the file of this document` | O envio ainda estava em andamento depois de 30 segundos. Execute a etapa de novo ou adicione uma etapa de espera (Delay) depois de **Enviar Documento**. |
+
+## Desenvolvimento
+
+A peça fica no monorepo do Activepieces em `packages/pieces/community/assinafy`. Requisitos: Node.js 24 LTS e Bun.
+
+```sh
+bun install
+npx turbo run build --filter=@assinafy/piece-assinafy
+npx turbo run lint --filter=@assinafy/piece-assinafy
+cd packages/pieces/community/assinafy
+npm run typecheck        # código e testes
+npm test                 # testes unitários, sem rede
+npm run test:coverage    # com limites de cobertura
+```
+
+Os testes unitários simulam o cliente HTTP e bloqueiam qualquer acesso real à rede. Um teste de envio usa o cliente HTTP real do Activepieces com um `fetch` simulado para verificar a requisição multipart enviada.
+
+### Notas de implementação
+
+- As requisições feitas pelos gatilhos expiram depois de 15 segundos, bem dentro do tempo que o Activepieces dá para a execução de um gatilho; as ações permitem 120 segundos.
+- Quando duas execuções criam o mesmo novo signatário ao mesmo tempo, a execução que perde reutiliza o signatário criado pela outra.
+- As requisições não seguem redirecionamentos automaticamente. Um redirecionamento só é seguido em leituras e downloads, e as credenciais ficam de fora quando ele aponta para fora do endereço da Assinafy, por exemplo para o armazenamento de arquivos.
+- O envio de arquivos usa o pacote `form-data`. O cliente HTTP do Activepieces define o tipo de conteúdo multipart e o boundary apenas para corpos `form-data`; um corpo `FormData` global seria enviado como JSON.
+- O endpoint de criação de signatário da Assinafy não aceita CPF/CNPJ, então ele é definido com uma atualização em seguida.
+- A Assinafy retorna no máximo 50 itens por página de lista e repete a última página quando é pedida uma página além do fim. As leituras de listas seguem o cabeçalho `X-Pagination-Page-Count` e param em uma página incompleta ou repetida.
+- A referência da API não documenta um endpoint para um único modelo, então o formulário e a ação de modelo percorrem até 500 modelos.
+- **Documento Assinado** mantém seu próprio estado e o preserva quando o fluxo é republicado: o momento da ativação, a última verificação concluída, a posição de uma varredura de acúmulo em andamento e um registro dos documentos disparados recentemente.
+  - Documentos assinados são listados do mais recente para o mais antigo, não podem ser excluídos e só descem na lista quando outros são assinados ou alterados. Por isso a varredura retoma logo após o último documento examinado (pela data de atualização e pelo ID), e o ponto de controle de tempo só avança quando a varredura alcança documentos anteriores à verificação anterior.
+  - Um documento dispara quando o momento da conclusão (a atividade `document_ready` mais recente, senão a `signer_signed_document` mais recente) é posterior à ativação do gatilho e no máximo 24 horas anterior ao início da janela da verificação. Um documento sem nenhuma dessas atividades não dispara. O registro guarda os documentos disparados nesse período para que alterações posteriores não os disparem de novo, descarta entradas que não podem mais passar na regra e tem no máximo 5.000 entradas para respeitar o limite de armazenamento do Activepieces.
+  - Cada verificação lê no máximo 10 páginas de 50 documentos e 40 históricos de atividades, e para depois de 30 segundos; a verificação seguinte continua de onde parou. Um erro depois de examinar alguns documentos mantém esse progresso; um erro antes disso faz a verificação falhar.
+  - Um documento cujo histórico de atividades não pode ser lido é tentado de novo nas duas verificações seguintes. Depois disso ele dispara usando a data de atualização como momento da conclusão, para que um documento com problema não pare o gatilho.
+  - O Activepieces salva o progresso de um gatilho por verificação antes de iniciar as execuções dos itens retornados. Se iniciá-las falhar, esses documentos não são retornados de novo. Isso vale para todo gatilho por verificação do Activepieces; a peça não recebe nenhum sinal para reenviá-los.
+
+### Testes no sandbox
+
+`test/live.test.ts` roda apenas no sandbox da Assinafy e exclui tudo o que cria:
+
+```sh
+ASSINAFY_API_KEY=<chave do sandbox> npm run test:live
+```
+
+| Variável | Efeito |
+|---|---|
+| `ASSINAFY_ACCOUNT_ID` | Espaço de trabalho a usar quando a chave tem vários |
+| `ASSINAFY_LIVE_SEND=1` | Também envia uma solicitação de assinatura para um endereço `example.com` (consome um documento do plano) |
+| `ASSINAFY_LIVE_WEBHOOK=1` | Também ativa e desativa o webhook do espaço de trabalho; falha em vez de substituir outro destino |
+| `ASSINAFY_LIVE_WEBHOOK_EMAIL` | Endereço de avisos de entrega para o teste do webhook (padrão: um endereço `example.com`) |
+
+O conjunto também lê o histórico de atividades de um documento, do qual **Documento Assinado** depende.
+
+### Testar em um Activepieces local
+
+Adicione `AP_DEV_PIECES=assinafy` em `packages/server/api/.env`, execute `npm start` na raiz do repositório e abra <http://localhost:4200>.
+
+### Traduções
+
+`src/i18n/translation.json` é gerado a partir da peça e `src/i18n/pt.json` contém os textos em português do Brasil. Depois de alterar qualquer nome, descrição ou rótulo de opção:
+
+```sh
+npm run cli -- pieces generate-translation-file assinafy
+```
+
+Se o comando parar em um erro de tipos fora desta peça, execute `TS_NODE_TRANSPILE_ONLY=true npm run cli -- pieces generate-translation-file assinafy`. Depois atualize o `pt.json`. Os testes falham enquanto algum dos dois arquivos estiver desatualizado.
+
+O Activepieces não traduz a janela de conexão de uma peça com mais de um tipo de conexão, então essa janela aparece em inglês.
+
+### Publicação
+
+1. Aumente a `version` no `package.json` (patch para novas ações, entradas opcionais e correções; major para remoções, novas entradas obrigatórias ou mudança de comportamento) e registre a versão no `CHANGELOG.md`.
+2. Execute `npm run licenses` nesta pasta. Ele reescreve o `LICENSE` com a licença de cada pacote embutido no arquivo publicado.
+3. Autentique-se no npm (`npm login`) com uma conta que possa publicar no escopo `@assinafy`.
+4. Na raiz do repositório:
+
+   ```sh
+   TS_NODE_TRANSPILE_ONLY=true npm_config_dry_run=true npm run publish-piece assinafy   # confere o pacote, não publica nada
+   TS_NODE_TRANSPILE_ONLY=true npm run publish-piece assinafy
+   ```
+
+   `TS_NODE_TRANSPILE_ONLY=true` ignora um erro de tipos não relacionado em outra parte do repositório que interrompe o script. O script compila a peça, gera um único arquivo com as bibliotecas do Activepieces embutidas, verifica que não sobrou nenhuma dependência de workspace ou `@activepieces/*` e publica com acesso público junto com os READMEs, o `LICENSE` e o `CHANGELOG.md`. Uma versão que já está no npm é ignorada, então aumente a versão antes de publicar alterações.
+
+Nunca renomeie uma ação, gatilho ou entrada depois de publicada: os fluxos os referenciam pelo nome.
+
+## Licença
+
+MIT. O pacote publicado também embute as bibliotecas do Activepieces e alguns pacotes npm; o `LICENSE` lista cada um com sua licença.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@assinafy/piece-assinafy",
+  "version": "0.1.0",
+  "description": "Activepieces piece for Assinafy electronic signatures.",
+  "license": "MIT",
+  "author": "Assinafy",
+  "homepage": "https://github.com/assinafy/activepieces/tree/main/packages/pieces/community/assinafy#readme",
+  "bugs": {
+    "url": "https://github.com/assinafy/activepieces/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assinafy/activepieces.git",
+    "directory": "packages/pieces/community/assinafy"
+  },
+  "keywords": [
+    "activepieces",
+    "assinafy",
+    "e-signature",
+    "assinatura-eletronica"
+  ],
+  "main": "./src/index.js",
+  "dependencies": {},
+  "files": [
+    "src/index.js",
+    "package.json",
+    "src/i18n",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "README.pt-BR.md"
+  ]
+}