Documentação da API

#Antes de começar

A API do Ideia Signer permite colocar documentos em assinatura a partir do seu sistema, acompanhar quem já assinou e baixar o arquivo assinado.

• Endereço da API: https://app.ideiasigner.com.br
• Autenticação: cabeçalho X-Api-Key: sua-app|<chave> em todas as chamadas
• Formato: JSON (o envio de arquivo usa multipart/form-data)
• Referência completa: todas as 45 operações, com parâmetros e modelos

#A chave de acesso

Toda chave está ligada a uma organização do Ideia Signer: ela só enxerga e cria documentos daquela organização. Para receber a sua, fale com o nosso suporte.

X-Api-Key: sua-app|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Atenção: a chave é um segredo. Guarde-a no seu servidor e nunca a coloque em código que roda no navegador ou no celular do usuário.

#Postman e Insomnia

Na seção Arquivos para baixar estão as coleções prontas, com todas as operações e uma pasta "00. Fluxo de assinatura (na ordem)" com o caminho completo, passo a passo.

• Postman: importe a coleção e o ambiente, escolha o ambiente "Ideia Signer — Produção" e preencha só a variável apiKey. Os passos 1, 2 e 4 já guardam uploadId, documentId e actionUrl sozinhos para o passo seguinte.
• Insomnia: importe o arquivo, abra o Base Environment (Ctrl/Cmd + E) e preencha apiKey. O Insomnia não roda os scripts de captura: copie o id do passo 1 para uploadId e o documentId do passo 2 para documentId.

#A sequência em uma tela

 [seu sistema]                          [Ideia Signer]

  arquivo .pdf
      │
      │  (1)  POST /api/uploads              (multipart)
      ├──────────────────────────────────────────────►
      │  ◄────────────────────────── { id, name, contentType, location }
      │                                        │
      │        guarde esse "id" = uploadId     │
      │                                        │
      │  (2)  POST /api/documents             (JSON: files[] + flowActions[])
      ├──────────────────────────────────────────────►
      │  ◄────────────────────────── [ { uploadId, documentId } ]
      │                                        │
      │                          ┌─────────────┴──────────────┐
      │                          │ o Signer envia o e-mail de │
      │                          │ "ação pendente" para os    │
      │                          │ participantes do passo 1   │
      │                          └────────────────────────────┘
      │
      │  (3)  (opcional) POST /api/documents/{id}/action-url
      ├──────────────────────────────────────────────►    ← link direto de assinatura
      │  ◄────────────────────────── { url, embedUrl }       (redirecionar ou iframe)
      │
      │  (4)  webhook DocumentConcluded  (ou GET .../signatures-details)
      │  ◄──────────────────────────────────────────────
      │
      │  (5)  GET /api/documents/{id}/content?type=Signatures
      ├──────────────────────────────────────────────►
      │  ◄────────────────────────── PDF assinado (binário)

Os dois passos obrigatórios são o 1 e o 2. O resto é acompanhar e retirar o resultado. A regra que amarra os dois: o id devolvido pelo upload é exatamente o que vai em files[].id na criação do documento.

#Passo 1: enviar o arquivo

POST /api/uploads envia o arquivo e devolve um identificador temporário. Nada é criado ainda: o upload é só um arquivo guardado no servidor.

curl -X POST "https://app.ideiasigner.com.br/api/uploads" \
  -H "X-Api-Key: $IDEIA_SIGNER_KEY" \
  -F "file=@./Contrato.pdf"

Resposta (FileModel):

{
  "id": "0429c723-a66d-4e55-a912-ff636d1b2745",
  "name": "Contrato.pdf",
  "contentType": "application/pdf",
  "location": "https://app.ideiasigner.com.br/..."
}

#Alternativa: arquivo em Base64

POST /api/uploads/bytes dá o mesmo resultado, mas o arquivo vai em Base64 dentro de um JSON. É mais simples quando o seu sistema já tem os bytes em memória.

curl -X POST "https://app.ideiasigner.com.br/api/uploads/bytes" \
  -H "X-Api-Key: $IDEIA_SIGNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bytes":"JVBERi0xLjQK..."}'

Devolve { "id", "size", "digest" }. O digest é o MD5 do que chegou, para você conferir a integridade antes de criar o documento.

Um upload por arquivo. Se o documento tem 3 anexos, são 4 uploads (1 principal + 3).

#Passo 2: criar o documento

POST /api/documents cria o documento e o fluxo de assinatura na mesma chamada.

curl -X POST "https://app.ideiasigner.com.br/api/documents" \
  -H "X-Api-Key: $IDEIA_SIGNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "files": [{
      "displayName": "Contrato de prestação de serviços",
      "id": "0429c723-a66d-4e55-a912-ff636d1b2745",
      "name": "Contrato.pdf",
      "contentType": "application/pdf"
    }],
    "description": "Contrato anual — renovação",
    "flowActions": [{
      "type": "Signer",
      "step": 1,
      "title": "Contratante",
      "user": {
        "name": "João da Silva",
        "identifierType": "Cpf",
        "identifier": "81976153069",
        "email": "joao.silva@example.com",
        "phone": "+55 11 91234-5678"
      },
      "allowElectronicSignature": true
    }]
  }'

Resposta (CreateDocumentResult[]). É uma lista, com um item por arquivo enviado:

[{ "uploadId": "0429c723-...", "documentId": "9f2e1c44-..." }]

Guarde o documentId: ele é a chave de todas as chamadas seguintes.

#Campos que importam

#Montando o flowActions[]

Um depois do outro: o segundo só é avisado quando o primeiro termina.

"flowActions": [
  { "type": "Signer",   "step": 1, "user": { "name": "João",  "email": "joao@example.com",  "identifier": "81976153069" } },
  { "type": "Approver", "step": 2, "user": { "name": "Maria", "email": "maria@example.com", "identifier": "12345678909" } }
]

Dois ao mesmo tempo: os dois são avisados na hora e assinam em qualquer ordem.

"flowActions": [
  { "type": "Signer", "step": 1, "user": { "name": "João",  "email": "joao@example.com",  "identifier": "81976153069" } },
  { "type": "Signer", "step": 1, "user": { "name": "Maria", "email": "maria@example.com", "identifier": "12345678909" } }
]

Regra "2 de 4": quatro sócios podem assinar, bastam dois.

"flowActions": [{
  "type": "SignRule",
  "step": 1,
  "ruleName": "Diretoria",
  "numberRequiredActions": 2,
  "ruleUsers": [
    { "name": "Sócio A", "email": "a@example.com", "identifier": "11111111111" },
    { "name": "Sócio B", "email": "b@example.com", "identifier": "22222222222" },
    { "name": "Sócio C", "email": "c@example.com", "identifier": "33333333333" },
    { "name": "Sócio D", "email": "d@example.com", "identifier": "44444444444" }
  ]
}]

#Passo 3 (opcional): levar quem assina direto para a tela

Por padrão o Signer já envia o e-mail de ação pendente. Use este passo quando quiser que a assinatura aconteça dentro do seu sistema, sem passar pelo e-mail: POST /api/documents/{id}/action-url.

curl -X POST "https://app.ideiasigner.com.br/api/documents/$DOC_ID/action-url" \
  -H "X-Api-Key: $IDEIA_SIGNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "identifier": "81976153069", "emailAddress": "joao.silva@example.com", "requireEmailAuthentication": false }'

Resposta: { "url": "...", "embedUrl": "..." }. Use url para redirecionar e embedUrl para mostrar a assinatura dentro da sua página (veja Assinatura dentro do seu sistema).

Se a pessoa tem mais de uma ação pendente no mesmo documento, informe também o flowActionId (ele vem em GET /api/documents/{id}).

Combinação usual: criar o documento com disablePendingActionNotifications: true e gerar a action-url. Assim o Signer não manda e-mail e tudo acontece na sua interface.

#Passos 4 e 5: acompanhar e baixar

#Acompanhar

Situações possíveis: Pending, Refused, FlowConcluded, Concluded, Canceled, Expired.

Não fique consultando GET /api/documents/{id} em repetição para saber se já assinaram: é para isso que existe o webhook.

#Webhooks

Para ativar, cadastre o endereço do seu sistema na seção de integrações da página da sua organização. A cada evento, o Signer faz um POST nesse endereço com o corpo { "type": "...", "data": { ... } }. O conteúdo de data muda conforme o evento; os formatos estão na referência, na seção de modelos (Webhooks.*).

Sempre confira o documento pela API antes de tomar uma decisão importante (por exemplo, liberar um pagamento) com base num webhook.

#Baixar

# arquivo direto
curl -L "https://app.ideiasigner.com.br/api/documents/$DOC_ID/content?type=Signatures" \
  -H "X-Api-Key: $IDEIA_SIGNER_KEY" -o assinado.pdf

Valores de type: Original, Signatures (o assinado), PrinterFriendlyVersion, OriginalWithMarks, SigningTags, SignatureMarks, SignaturesManifest.

#Posicionar a assinatura no PDF

Se a rubrica precisa cair num lugar exato da página, entra um passo entre o upload e a criação do documento.

POST /api/uploads  →  POST /api/marks-sessions/documents  →  [a pessoa posiciona no iframe]
                                                                        │
                                          devolve o MESMO corpo, agora  │
                                          com prePositionedMarks[]      │
                                                                        ▼
                                                             POST /api/documents

1. POST /api/marks-sessions/documents: mande o mesmo corpo que mandaria para POST /api/documents. Resposta: { id, embedUrl }.
2. Abra o embedUrl num iframe (veja Assinatura dentro do seu sistema). A pessoa arrasta as marcas sobre o PDF.
3. Pegue o resultado pelo evento do iframe ou por GET /api/marks-sessions/{id}.
4. Mande esse corpo, agora com flowActions[].prePositionedMarks[] preenchido, para POST /api/documents.

Se você só quer criar a sessão com os dados mínimos (sem e-mail ou CPF de quem assina), use POST /api/marks-sessions. A sessão vale por 1 hora depois de criada.

Se você já sabe as coordenadas, pule a sessão e mande direto em prePositionedMarks[]:

"prePositionedMarks": [{
  "type": "SignatureVisualRepresentation",
  "pageNumber": 1,
  "topLeftX": 100, "topLeftY": 600,
  "width": 200, "height": 60,
  "uploadId": "0429c723-..."
}]

topLeftX/topLeftY marcam o canto superior esquerdo da marca, em pontos do PDF (1 pt = 1/72 de polegada). uploadId prende a marca a um arquivo; se ficar vazio, a marca vale para todos os arquivos enviados. Tipos de marca: SignatureVisualRepresentation, SignatureInitials, AuthenticationStamp.

Se você não tem as coordenadas medidas, use a sessão de marcas: acertar a posição por tentativa e erro sai mais caro que integrar o iframe.

#Assinatura dentro do seu sistema

O componente IdeiaSignerWidget mostra a tela de assinatura (ou de posicionamento de marcas) dentro da sua página, num iframe. Inclua o script:

<script src="https://statics.redeideia.com.br/signer/doc/signer-widget-0.7.0.min.js"
    crossorigin="anonymous"></script>

Crie o componente e escute os eventos:

var widget = new IdeiaSignerWidget();

widget.on(widget.events.documentSigned, function (e) {
  // documento e.id assinado
});

widget.on(widget.events.documentApproved, function (e) {
  // documento e.id aprovado
});

Ou um único callback para todos os eventos:

widget.listen(function (e) {
  if (e.type === widget.events.documentSigned) {
    // ...
  } else if (e.type === widget.events.documentApproved) {
    // ...
  }
});

Por fim, mostre o iframe com render():

// embedUrl: vem do passo 3 (action-url) ou da sessão de marcas
// 'embed-container': id do elemento que vai receber o iframe
widget.render(embedUrl, 'embed-container', page, scale);

// ou passando o elemento direto
widget.renderElement(embedUrl, document.getElementById('embed-container'), page, scale);

• page (opcional): página em que o documento abre. Use '-1' para abrir sempre na última.
• scale (opcional): zoom inicial, como texto ('100') ou widget.scaleOptions.S100.

Sempre confira no seu servidor, pela API, se o documento foi mesmo concluído: os callbacks do navegador podem ser disparados por outros scripts da página.

#Configurações do componente

Passe um objeto ao criar o IdeiaSignerWidget, por exemplo new IdeiaSignerWidget({ disableDocumentPreview: true }):

#Posicionamento de marcas no iframe

Com o embedUrl da sessão de marcas, escute o evento marksPositioned:

widget.on(widget.events.marksPositioned, function (e) {
  // e.data traz o corpo da criação de documento já com as posições
});

widget.render(embedUrl, 'embed-container');

Ao concluir, cada item de flowActions do corpo enviado na criação da sessão volta com prePositionedMarks preenchido. O mesmo corpo também pode ser lido em GET /api/marks-sessions/{id}.

#Depois de criado

#Fluxo reutilizável

Quando o mesmo grupo de pessoas assina sempre, cadastre o fluxo uma vez em POST /api/document-flows e reaproveite.

Atenção: POST /api/documents não tem um campo que aponte para o fluxo. O reaproveitamento é feito no seu código: você lê o fluxo e copia os flowActions dele para o corpo da criação.

POST /api/document-flows        (uma vez, cadastra o modelo)
        │
        ▼
GET /api/document-flows/{id}    → devolve flowActions[] no mesmo formato do POST /api/documents
        │
        ├──────────► copie esse flowActions[] para o corpo
        ▼
POST /api/uploads  →  POST /api/documents

Gestão: GET /api/document-flows (lista) e GET/PUT/DELETE em /api/document-flows/{id}. O campo areActionsOrdered do fluxo diz se as ações são uma depois da outra ou ao mesmo tempo.

#Criação em lote

Para muitos documentos, divida em lotes: 100 documentos = 10 requisições de 10, e não 1 de 100.

1. Envie cada lote com disablePendingActionNotifications: true.
2. Quando todos os lotes terminarem, chame POST /api/users/notify-pending uma única vez.

Assim ninguém recebe e-mail no meio de um lote que ainda pode falhar.

#Códigos de erro

O corpo do 422 segue o modelo ErrorModel (code, message, details). Alguns códigos: DocumentNotFound, FolderNotFound, CertificateNotFound, CpfMismatch, CpfNotExpected, InvalidFlowAction, DocumentInvalidKey. A lista não é completa e pode crescer.

#Erros comuns na integração

• 422 no passo 2: o files[].id não é o id que o upload devolveu, ou esse upload não é da organização da sua chave. Refaça o passo 1 e use o id novo.
• Ninguém recebeu e-mail: disableNotifications ou disablePendingActionNotifications ficaram true.
• O segundo participante não foi avisado: ele está num step maior e o primeiro ainda não assinou. Confira o step.
• Criou 3 documentos em vez de 1: 3 itens em files[] sem isEnvelope: true.
• A assinatura caiu no lugar errado: confira pageNumber e se as coordenadas estão em pontos do PDF (e não em pixels da sua tela de pré-visualização).

#Valores aceitos

#Lista de conferência

• A chave da API está guardada como segredo no servidor, nunca no navegador ou no aplicativo.
• O upload e a criação do documento são feitos no servidor.
• O uploadId é descartável: usou no POST /api/documents, pode esquecer.
• O documentId está salvo no seu banco, ligado ao registro de origem.
• O webhook está configurado, em vez de consultas repetidas.
• O 422 no passo 2 é tratado com um novo upload.
• Lotes grandes são divididos, com notify-pending no final.