KivoSign
Referência da API

Migrando para envelopes

Por que a KivoSign unificou documentos e modelos em envelopes, e como migrar dos endpoints descontinuados de criação de documento e modelo.

Resumo

Os itens abaixo estão descontinuados e serão removidos em 1º de março de 2027:

  • API V1
  • Parte dos endpoints da API/SDK V2
  • Documentos e modelos antigos (legados)
  • EmbedCreateDocumentV1
  • EmbedCreateTemplateV1
  • EmbedUpdateDocumentV1
  • EmbedUpdateTemplateV1

O endpoint beta /api/v2-beta também será removido. Use /api/v2, que é um substituto direto.

Nada deixa de funcionar antes de 1º de março de 2027, então você pode migrar no seu ritmo.

O que são documentos e modelos legados

São os documentos e modelos criados pelos endpoints abaixo:

  • POST /api/v2/document/create
  • POST /api/v2/document/create/beta
  • POST /api/v2/template/create
  • POST /api/v2/template/create/beta
  • POST /api/v1/documents
  • POST /api/v1/templates
  • POST /api/v1/templates/create-document
  • POST /api/v1/templates/generate-document

O que substitui documentos e modelos legados

No fim de 2025 foi lançado um sistema unificado para documentos e modelos, chamado envelopes.

Ainda usamos os termos documento e modelo na documentação e no aplicativo para diferenciá-los, mas internamente os dois são envelopes.

Com o sistema de envelopes você ganha:

  • Vários PDFs em um envelope. Envie vários documentos para assinatura em uma única requisição.
  • Uma API para documentos e modelos. Um só conjunto de endpoints, em vez de dois desalinhados.
  • Um editor e uma experiência de assinatura melhores para você e seus destinatários.

Como migrar

Troque para os endpoints de envelope

Substitua cada endpoint descontinuado pelo equivalente em /api/v2/envelope/*, conforme as tabelas de correspondência abaixo.

Informe o type do envelope na criação

Um único endpoint, POST /api/v2/envelope/create, cria documentos e modelos. Defina type como DOCUMENT ou TEMPLATE. Agora é possível enviar mais de um PDF pelo campo files.

Ajuste como você guarda os IDs

IDs de envelope são strings (por exemplo envelope_abc123), não números. Atualize todo código que guarda, converte ou compara IDs.

Teste e remova as chamadas antigas

Valide o novo fluxo na sua conta e depois apague as chamadas descontinuadas.

As principais diferenças nos dados são:

  • O formato do ID mudou de número para string (ex.: 42 para envelope_abc123)
  • pageNumber passa a ser page
  • pageX passa a ser positionX
  • pageY passa a ser positionY

Veja a API de documentos e a API de modelos para a referência completa dos envelopes.

Tabelas de correspondência

Endpoints descontinuados da API V1

Endpoint descontinuadoSubstituto
GET /api/v1/documentsGET /api/v2/envelope
GET /api/v1/documents/{id}GET /api/v2/envelope/{envelopeId}
POST /api/v1/documentsPOST /api/v2/envelope/create
POST /api/v1/documents/{id}/sendPOST /api/v2/envelope/distribute
POST /api/v1/documents/{id}/resendPOST /api/v2/envelope/redistribute
DELETE /api/v1/documents/{id}POST /api/v2/envelope/delete
GET /api/v1/documents/{id}/downloadGET /api/v2/envelope/item/{envelopeItemId}/download
POST /api/v1/documents/{id}/recipientsPOST /api/v2/envelope/recipient/create-many
PATCH /api/v1/documents/{id}/recipients/{recipientId}POST /api/v2/envelope/recipient/update-many
DELETE /api/v1/documents/{id}/recipients/{recipientId}POST /api/v2/envelope/recipient/delete
POST /api/v1/documents/{id}/fieldsPOST /api/v2/envelope/field/create-many
PATCH /api/v1/documents/{id}/fields/{fieldId}POST /api/v2/envelope/field/update-many
DELETE /api/v1/documents/{id}/fields/{fieldId}POST /api/v2/envelope/field/delete
GET /api/v1/templatesGET /api/v2/envelope (com type=TEMPLATE)
GET /api/v1/templates/{id}GET /api/v2/envelope/{envelopeId}
POST /api/v1/templatesPOST /api/v2/envelope/create (type=TEMPLATE)
DELETE /api/v1/templates/{id}POST /api/v2/envelope/delete
POST /api/v1/templates/{templateId}/create-documentPOST /api/v2/envelope/use
POST /api/v1/templates/{templateId}/generate-documentPOST /api/v2/envelope/use

Endpoints descontinuados da API V2

Referência completa na especificação OpenAPI V2.

Documentos

Endpoint descontinuadoSubstituto
GET /api/v2/documentGET /api/v2/envelope
GET /api/v2/document/{documentId}GET /api/v2/envelope/{envelopeId}
POST /api/v2/document/get-manyPOST /api/v2/envelope/get-many (o corpo muda de documentIds: number[] para ids: { type: "documentId"; ids: number[] })
POST /api/v2/document/createPOST /api/v2/envelope/create
POST /api/v2/document/create/betaPOST /api/v2/envelope/create
POST /api/v2/document/updatePOST /api/v2/envelope/update
POST /api/v2/document/deletePOST /api/v2/envelope/delete
POST /api/v2/document/duplicatePOST /api/v2/envelope/duplicate
POST /api/v2/document/distributePOST /api/v2/envelope/distribute
POST /api/v2/document/redistributePOST /api/v2/envelope/redistribute
GET /api/v2/document/attachmentGET /api/v2/envelope/attachment
POST /api/v2/document/attachment/createPOST /api/v2/envelope/attachment/create
POST /api/v2/document/attachment/updatePOST /api/v2/envelope/attachment/update
POST /api/v2/document/attachment/deletePOST /api/v2/envelope/attachment/delete
GET /api/v2/document/{documentId}/downloadGET /api/v2/envelope/item/{envelopeItemId}/download
GET /api/v2/document/{documentId}/download-betaGET /api/v2/envelope/item/{envelopeItemId}/download

Modelos

Endpoint descontinuadoSubstituto
GET /api/v2/templateGET /api/v2/envelope (com type=TEMPLATE)
GET /api/v2/template/{templateId}GET /api/v2/envelope/{envelopeId}
POST /api/v2/template/get-manyPOST /api/v2/envelope/get-many (o corpo muda de templateIds: number[] para ids: { type: "templateId"; ids: number[] })
POST /api/v2/template/createPOST /api/v2/envelope/create (type=TEMPLATE)
POST /api/v2/template/create/betaPOST /api/v2/envelope/create (type=TEMPLATE)
POST /api/v2/template/updatePOST /api/v2/envelope/update
POST /api/v2/template/duplicatePOST /api/v2/envelope/duplicate
POST /api/v2/template/deletePOST /api/v2/envelope/delete
POST /api/v2/template/usePOST /api/v2/envelope/use
POST /api/v2/template/direct/createSubstituto ainda não disponível
POST /api/v2/template/direct/deleteSubstituto ainda não disponível
POST /api/v2/template/direct/toggleSubstituto ainda não disponível

Campos de documento

Endpoint descontinuadoSubstituto
GET /api/v2/document/field/{fieldId}GET /api/v2/envelope/field/{fieldId}
POST /api/v2/document/field/createPOST /api/v2/envelope/field/create-many
POST /api/v2/document/field/create-manyPOST /api/v2/envelope/field/create-many
POST /api/v2/document/field/updatePOST /api/v2/envelope/field/update-many
POST /api/v2/document/field/update-manyPOST /api/v2/envelope/field/update-many
POST /api/v2/document/field/deletePOST /api/v2/envelope/field/delete

Campos de modelo

Endpoint descontinuadoSubstituto
GET /api/v2/template/field/{fieldId}GET /api/v2/envelope/field/{fieldId}
POST /api/v2/template/field/createPOST /api/v2/envelope/field/create-many
POST /api/v2/template/field/create-manyPOST /api/v2/envelope/field/create-many
POST /api/v2/template/field/updatePOST /api/v2/envelope/field/update-many
POST /api/v2/template/field/update-manyPOST /api/v2/envelope/field/update-many
POST /api/v2/template/field/deletePOST /api/v2/envelope/field/delete

Destinatários de documento

Endpoint descontinuadoSubstituto
GET /api/v2/document/recipient/{recipientId}GET /api/v2/envelope/recipient/{recipientId}
POST /api/v2/document/recipient/createPOST /api/v2/envelope/recipient/create-many
POST /api/v2/document/recipient/create-manyPOST /api/v2/envelope/recipient/create-many
POST /api/v2/document/recipient/updatePOST /api/v2/envelope/recipient/update-many
POST /api/v2/document/recipient/update-manyPOST /api/v2/envelope/recipient/update-many
POST /api/v2/document/recipient/deletePOST /api/v2/envelope/recipient/delete

Destinatários de modelo

Endpoint descontinuadoSubstituto
GET /api/v2/template/recipient/{recipientId}GET /api/v2/envelope/recipient/{recipientId}
POST /api/v2/template/recipient/createPOST /api/v2/envelope/recipient/create-many
POST /api/v2/template/recipient/create-manyPOST /api/v2/envelope/recipient/create-many
POST /api/v2/template/recipient/updatePOST /api/v2/envelope/recipient/update-many
POST /api/v2/template/recipient/update-manyPOST /api/v2/envelope/recipient/update-many
POST /api/v2/template/recipient/deletePOST /api/v2/envelope/recipient/delete

Componentes de incorporação

Componente descontinuadoSubstituto
EmbedCreateDocumentV1EmbedCreateEnvelope
EmbedCreateTemplateV1EmbedCreateEnvelope
EmbedUpdateDocumentV1EmbedUpdateEnvelope
EmbedUpdateTemplateV1EmbedUpdateEnvelope

Veja o guia de incorporação para os componentes de envelope.

Perguntas frequentes

Ajuda

Veja também

Versionamento da API

Como funciona o versionamento da API pública da KivoSign.

Modo desenvolvedor

Ferramentas para depurar IDs de campos, IDs de destinatários e coordenadas ao integrar com a API da KivoSign.

Nesta página

ResumoO que são documentos e modelos legadosO que substitui documentos e modelos legadosComo migrarTroque para os endpoints de envelopeInforme o type do envelope na criaçãoAjuste como você guarda os IDsTeste e remova as chamadas antigasTabelas de correspondênciaEndpoints descontinuados da API V1Endpoints descontinuados da API V2DocumentosModelosCampos de documentoCampos de modeloDestinatários de documentoDestinatários de modeloComponentes de incorporaçãoPerguntas frequentesAjudaVeja também