{ "openapi": "3.1.0", "info": { "title": "ODSign API", "version": "1.0.0", "summary": "Envie documentos para assinatura eletrônica, acompanhe e baixe o documento assinado a partir dos seus sistemas.", "description": "API REST do ODSign: crie envelopes com documentos e destinatários, escolha como cada pessoa confirma a\nassinatura, envie, acompanhe, anule e baixe o documento assinado, a trilha de assinaturas e as provas\nde integridade. Os eventos chegam ao seu sistema pelos webhooks de saída (seção `webhooks`).\n\n- **Autenticação:** token pessoal no cabeçalho `Authorization: Bearer ods_...`, criado por um\n administrador em Configurações › Conta › Tokens da API.\n- **Formato:** JSON em UTF-8 (envie `Accept: application/json`); a criação de envelope é\n `multipart/form-data` (arquivos); downloads devolvem o próprio arquivo.\n- **Limite de uso:** 120 requisições por minuto por usuário (cabeçalhos `X-RateLimit-*`).\n- **Não há ambiente de testes separado:** as chamadas agem na conta real. Para testar sem enviar\n nada, crie rascunhos (`send` ausente ou `0`): eles não saem para ninguém e não contam no limite\n mensal de envelopes.\n\nGuias, exemplos completos e boas práticas: https://docs.odsign.com.br/integracoes.", "termsOfService": "https://odsign.com.br/termos-de-uso", "contact": { "name": "Suporte ODSign", "url": "https://odsign.com.br/contato" } }, "servers": [ { "url": "https://app.odsign.com.br/api/v1", "description": "Produção" } ], "security": [ { "token": [] } ], "tags": [ { "name": "Envelopes", "description": "Criar, listar e detalhar envelopes (documentos + destinatários)." }, { "name": "Envio", "description": "Enviar um rascunho, reenviar o convite e anular um envelope em curso." }, { "name": "Auditoria", "description": "Trilha de auditoria: cada ação registrada no envelope, com data, IP e origem." }, { "name": "Documentos", "description": "Downloads do envelope concluído: documento assinado, original, trilha completa e provas." } ], "paths": { "/envelopes": { "get": { "operationId": "listEnvelopes", "tags": [ "Envelopes" ], "summary": "Listar envelopes", "description": "Lista os envelopes do mais recentemente alterado para o mais antigo. Com token de administrador,\ntraz os envelopes da conta toda; com os demais perfis, só os que o usuário enviou. Modelos e\nenvelopes eliminados não aparecem. Use `meta.last_page` para percorrer as páginas.\n\nPara sincronizar o seu sistema, combine `from_date` com os webhooks: o webhook avisa na hora e a\nlistagem confere de tempos em tempos o que possa ter se perdido.", "parameters": [ { "name": "status", "in": "query", "description": "Um ou mais estados separados por vírgula (`created`, `sent`, `delivered`, `correct`, `completed`, `declined`, `voided`, `expired`). Estado desconhecido não dá erro: só não traz nada.", "schema": { "type": "string" }, "example": "sent,delivered" }, { "name": "from_date", "in": "query", "description": "Só envelopes alterados a partir desta data (`AAAA-MM-DD`) ou data e hora (ISO 8601).", "schema": { "type": "string", "format": "date" }, "example": "2026-11-01" }, { "name": "per_page", "in": "query", "description": "Itens por página, de 1 a 100 (valores fora da faixa são ajustados).", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "example": 25 }, { "name": "page", "in": "query", "description": "Número da página, a partir de 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 }, "example": 1 } ], "responses": { "200": { "description": "Página de envelopes.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeList" }, "example": { "data": [ { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "delivered", "status_label": "Em curso", "recipients": "Maria Souza, João Lima", "progress": 0, "waiting_for": "Maria Souza", "sender": "Ana Prado", "sender_id": 14, "sender_avatar_url": null, "folder_id": null, "updated_at": "2026-11-11T13:40:02+00:00", "expires_at": "2027-03-11T13:05:12+00:00", "deleted": false } ], "meta": { "page": 1, "per_page": 25, "total": 1, "last_page": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "operationId": "createEnvelope", "tags": [ "Envelopes" ], "summary": "Criar envelope (e enviar)", "description": "Cria o envelope com os documentos e os destinatários. Com `send=1`, envia em seguida: cada\ndestinatário da vez recebe o convite pela forma de envio (`channel`) e confirma a assinatura pela\nforma de autenticação (`auth_method`). Sem `send`, o envelope fica como **rascunho**: não sai\npara ninguém, não conta no limite mensal e pode ser enviado depois com `POST /envelopes/{id}/send`\n(ou completado no app, em Envelopes › Rascunhos).\n\n**Forma de autenticação.** Com `auth_method`, a assinatura vai para a trilha de assinaturas\nanexada ao fim do PDF assinado e não é preciso posicionar campos. Sem `auth_method`, cada\nsignatário (`signer` ou `in_person_signer`) precisa de pelo menos um campo `signature` em\n`fields` (fluxo por campos).\n\n**Pendências no envio.** Se `send=1` e algo impedir o envio (signatário sem forma de\nautenticação nem campo, token pelo celular sem `phone`, forma indisponível no plano, limite\nmensal atingido), a resposta é `422` com as pendências em `errors.envelope` **e o envelope fica\nsalvo como rascunho** (não crie de novo: corrija no app ou anule e recrie).\n\nEnvie booleanos como `1` ou `0` (multipart). O usuário do token precisa poder enviar\nenvelopes (perfil Administrador ou Remetente, com o envio liberado no plano).", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateEnvelopeRequest" }, "encoding": { "files[]": { "contentType": "application/pdf, image/jpeg, image/png, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document" } } } } }, "responses": { "201": { "description": "Envelope criado (e enviado, com `send=1`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "is_template": false, "template_name": null, "template_description": null, "subject": "Contrato de prestação de serviços", "message": "Olá! Segue o contrato para assinatura.", "status": "sent", "status_label": "Em curso", "editable": false, "signing_order_enabled": false, "current_routing_order": 1, "reminder_enabled": true, "reminder_delay_days": 1, "reminder_frequency_days": 2, "expire_enabled": true, "expire_after_days": 120, "expire_warn_days": 3, "allow_reassign": false, "category": null, "sender": { "name": "Ana Prado", "email": "ana@suaempresa.com.br" }, "folder": null, "void_reason": null, "original_sha256": "6298f5337e18894ea1b110664fce01b34bc90a3760673afa99d288f1e6859b3e", "final_sha256": null, "has_final": false, "has_certificate": false, "proofs": { "timestamp": null, "seal": null, "package": false }, "created_at": "2026-11-11T13:05:10+00:00", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "voided_at": null, "declined_at": null, "expires_at": "2027-03-11T13:05:12+00:00", "updated_at": "2026-11-11T13:40:02+00:00", "deleted_at": null, "documents": [ { "id": 812, "name": "contrato.pdf", "order": 1, "pages": 3, "page_sizes": [ { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 } ], "size": 184233, "url": "https://app.odsign.com.br/envelopes/01a1cc92-f28f-73b8-8dcc-f15232d31a3f/documentos/812" } ], "recipients": [ { "id": 2051, "type": "signer", "type_label": "Assinatura obrigatória", "role_name": null, "name": "Maria Souza", "email": "maria@exemplo.com.br", "routing_order": 1, "status": "sent", "status_label": "Enviado", "has_access_code": false, "phone": null, "channel": "email", "whatsapp_auth": false, "sms_auth": false, "auth_method": "email", "auth_label": "Token por e-mail", "private_message": null, "color_index": 0, "sent_at": "2026-11-11T13:05:12+00:00", "delivered_at": null, "signed_at": null, "declined_at": null, "decline_reason": null } ], "fields": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-odsign-effect": "Com send=1, envia convites reais (e-mail, WhatsApp ou SMS) e conta no limite mensal de envelopes do plano.", "x-odsign-sample": { "multipart": [ [ "subject", "Contrato de prestação de serviços" ], [ "message", "Olá! Segue o contrato para assinatura." ], [ "recipients[0][name]", "Maria Souza" ], [ "recipients[0][email]", "maria@exemplo.com.br" ], [ "recipients[0][auth_method]", "email" ], [ "send", "1" ] ], "files": [ "contrato.pdf" ] } } }, "/envelopes/{id}": { "get": { "operationId": "getEnvelope", "tags": [ "Envelopes" ], "summary": "Detalhar envelope", "description": "Devolve o envelope com documentos, destinatários (situação, forma de envio e de autenticação,\ndatas de envio, visualização e assinatura), campos, hashes e provas de integridade. As fotos de\ndocumento pessoal nunca saem pela API. O `url` de cada documento é o do app (exige login): para\nbaixar pela API, use `GET /envelopes/{id}/documents/{kind}`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" } ], "responses": { "200": { "description": "Envelope.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "is_template": false, "template_name": null, "template_description": null, "subject": "Contrato de prestação de serviços", "message": "Olá! Segue o contrato para assinatura.", "status": "delivered", "status_label": "Em curso", "editable": false, "signing_order_enabled": false, "current_routing_order": 1, "reminder_enabled": true, "reminder_delay_days": 1, "reminder_frequency_days": 2, "expire_enabled": true, "expire_after_days": 120, "expire_warn_days": 3, "allow_reassign": false, "category": null, "sender": { "name": "Ana Prado", "email": "ana@suaempresa.com.br" }, "folder": null, "void_reason": null, "original_sha256": "6298f5337e18894ea1b110664fce01b34bc90a3760673afa99d288f1e6859b3e", "final_sha256": null, "has_final": false, "has_certificate": false, "proofs": { "timestamp": null, "seal": null, "package": false }, "created_at": "2026-11-11T13:05:10+00:00", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "voided_at": null, "declined_at": null, "expires_at": "2027-03-11T13:05:12+00:00", "updated_at": "2026-11-11T13:40:02+00:00", "deleted_at": null, "documents": [ { "id": 812, "name": "contrato.pdf", "order": 1, "pages": 3, "page_sizes": [ { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 } ], "size": 184233, "url": "https://app.odsign.com.br/envelopes/01a1cc92-f28f-73b8-8dcc-f15232d31a3f/documentos/812" } ], "recipients": [ { "id": 2051, "type": "signer", "type_label": "Assinatura obrigatória", "role_name": null, "name": "Maria Souza", "email": "maria@exemplo.com.br", "routing_order": 1, "status": "delivered", "status_label": "Visualizado", "has_access_code": false, "phone": null, "channel": "email", "whatsapp_auth": false, "sms_auth": false, "auth_method": "email", "auth_label": "Token por e-mail", "private_message": null, "color_index": 0, "sent_at": "2026-11-11T13:05:12+00:00", "delivered_at": "2026-11-11T13:40:02+00:00", "signed_at": null, "declined_at": null, "decline_reason": null } ], "fields": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/envelopes/{id}/send": { "post": { "operationId": "sendEnvelope", "tags": [ "Envio" ], "summary": "Enviar rascunho", "description": "Envia um envelope em rascunho (`created`). Devolve o envelope atualizado. Se houver pendências,\nresponde `422` com a lista em `errors.envelope` (por exemplo, \"Este envelope já foi enviado.\" ou\no aviso de limite mensal de envelopes do plano atingido).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" } ], "responses": { "200": { "description": "Envelope enviado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "is_template": false, "template_name": null, "template_description": null, "subject": "Contrato de prestação de serviços", "message": "Olá! Segue o contrato para assinatura.", "status": "sent", "status_label": "Em curso", "editable": false, "signing_order_enabled": false, "current_routing_order": 1, "reminder_enabled": true, "reminder_delay_days": 1, "reminder_frequency_days": 2, "expire_enabled": true, "expire_after_days": 120, "expire_warn_days": 3, "allow_reassign": false, "category": null, "sender": { "name": "Ana Prado", "email": "ana@suaempresa.com.br" }, "folder": null, "void_reason": null, "original_sha256": "6298f5337e18894ea1b110664fce01b34bc90a3760673afa99d288f1e6859b3e", "final_sha256": null, "has_final": false, "has_certificate": false, "proofs": { "timestamp": null, "seal": null, "package": false }, "created_at": "2026-11-11T13:05:10+00:00", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "voided_at": null, "declined_at": null, "expires_at": "2027-03-11T13:05:12+00:00", "updated_at": "2026-11-11T13:40:02+00:00", "deleted_at": null, "documents": [ { "id": 812, "name": "contrato.pdf", "order": 1, "pages": 3, "page_sizes": [ { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 } ], "size": 184233, "url": "https://app.odsign.com.br/envelopes/01a1cc92-f28f-73b8-8dcc-f15232d31a3f/documentos/812" } ], "recipients": [ { "id": 2051, "type": "signer", "type_label": "Assinatura obrigatória", "role_name": null, "name": "Maria Souza", "email": "maria@exemplo.com.br", "routing_order": 1, "status": "sent", "status_label": "Enviado", "has_access_code": false, "phone": null, "channel": "email", "whatsapp_auth": false, "sms_auth": false, "auth_method": "email", "auth_label": "Token por e-mail", "private_message": null, "color_index": 0, "sent_at": "2026-11-11T13:05:12+00:00", "delivered_at": null, "signed_at": null, "declined_at": null, "decline_reason": null } ], "fields": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-odsign-effect": "Envia convites reais e conta no limite mensal de envelopes do plano." } }, "/envelopes/{id}/resend": { "post": { "operationId": "resendEnvelope", "tags": [ "Envio" ], "summary": "Reenviar o convite", "description": "Reenvia o convite aos destinatários da vez que ainda não concluíram, pela mesma forma de envio.\n**Cada reenvio gera um novo link pessoal**: o link do convite anterior deixa de funcionar. Só\nvale para envelopes em curso (`sent` ou `delivered`); em correção, envie as correções pelo app.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" } ], "responses": { "200": { "description": "Convite reenviado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" }, "example": { "message": "Reenviado." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-odsign-effect": "Reenvia convites reais e troca o link pessoal de quem está na vez." } }, "/envelopes/{id}/void": { "post": { "operationId": "voidEnvelope", "tags": [ "Envio" ], "summary": "Anular envelope", "description": "Anula um envelope em curso. Os destinatários já avisados recebem a notificação da anulação, com\no motivo, e os links pessoais param de funcionar. Não dá para desfazer: para corrigir algo,\nanule e crie outro envelope.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 200, "description": "Motivo, mostrado aos destinatários e na trilha de auditoria." } } }, "example": { "reason": "Valores revisados; um novo contrato será enviado." } } } }, "responses": { "200": { "description": "Envelope anulado.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "is_template": false, "template_name": null, "template_description": null, "subject": "Contrato de prestação de serviços", "message": "Olá! Segue o contrato para assinatura.", "status": "voided", "status_label": "Anulado", "editable": false, "signing_order_enabled": false, "current_routing_order": 1, "reminder_enabled": true, "reminder_delay_days": 1, "reminder_frequency_days": 2, "expire_enabled": true, "expire_after_days": 120, "expire_warn_days": 3, "allow_reassign": false, "category": null, "sender": { "name": "Ana Prado", "email": "ana@suaempresa.com.br" }, "folder": null, "void_reason": "Valores revisados; um novo contrato será enviado.", "original_sha256": "6298f5337e18894ea1b110664fce01b34bc90a3760673afa99d288f1e6859b3e", "final_sha256": null, "has_final": false, "has_certificate": false, "proofs": { "timestamp": null, "seal": null, "package": false }, "created_at": "2026-11-11T13:05:10+00:00", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "voided_at": "2026-11-11T15:20:03+00:00", "declined_at": null, "expires_at": "2027-03-11T13:05:12+00:00", "updated_at": "2026-11-11T15:20:03+00:00", "deleted_at": null, "documents": [ { "id": 812, "name": "contrato.pdf", "order": 1, "pages": 3, "page_sizes": [ { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 }, { "w": 595.28, "h": 841.89 } ], "size": 184233, "url": "https://app.odsign.com.br/envelopes/01a1cc92-f28f-73b8-8dcc-f15232d31a3f/documentos/812" } ], "recipients": [ { "id": 2051, "type": "signer", "type_label": "Assinatura obrigatória", "role_name": null, "name": "Maria Souza", "email": "maria@exemplo.com.br", "routing_order": 1, "status": "delivered", "status_label": "Visualizado", "has_access_code": false, "phone": null, "channel": "email", "whatsapp_auth": false, "sms_auth": false, "auth_method": "email", "auth_label": "Token por e-mail", "private_message": null, "color_index": 0, "sent_at": "2026-11-11T13:05:12+00:00", "delivered_at": "2026-11-11T13:40:02+00:00", "signed_at": null, "declined_at": null, "decline_reason": null } ], "fields": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-odsign-effect": "Anula o envelope de verdade e avisa os destinatários (não dá para desfazer)." } }, "/envelopes/{id}/audit-events": { "get": { "operationId": "listAuditEvents", "tags": [ "Auditoria" ], "summary": "Trilha de auditoria", "description": "Lista os eventos do envelope em ordem cronológica, os mesmos do histórico do app e do log da\ntrilha de assinaturas: criação, envio, convites, aberturas, aceite do termo, códigos, assinaturas,\nrecusa, anulação, conclusão, downloads e provas. `source` indica a origem (`web` = app ou link\nde assinatura, `api` = esta API, `sistema` = tarefas automáticas, como lembretes e expiração).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" } ], "responses": { "200": { "description": "Eventos da trilha.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } } } }, "example": { "data": [ { "id": 40201, "action": "created", "action_label": "Registrado", "description": "O envelope foi criado por Ana Prado", "actor_name": "Ana Prado", "actor_email": "ana@suaempresa.com.br", "source": "api", "ip": "200.150.10.20", "envelope_status": "created", "document_sha256": null, "created_at": "2026-11-11T13:05:10+00:00" }, { "id": 40202, "action": "sent", "action_label": "Convite enviado", "description": "O envelope foi enviado", "actor_name": "Ana Prado", "actor_email": "ana@suaempresa.com.br", "source": "api", "ip": "200.150.10.20", "envelope_status": "sent", "document_sha256": "6298f5337e18894ea1b110664fce01b34bc90a3760673afa99d288f1e6859b3e", "created_at": "2026-11-11T13:05:12+00:00" }, { "id": 40203, "action": "sent", "action_label": "Convite enviado", "description": "Convite enviado a Maria Souza [maria@exemplo.com.br]", "actor_name": "Ana Prado", "actor_email": "ana@suaempresa.com.br", "source": "api", "ip": "200.150.10.20", "envelope_status": "sent", "document_sha256": null, "created_at": "2026-11-11T13:05:12+00:00" }, { "id": 40207, "action": "opened", "action_label": "Aberto", "description": "Maria Souza abriu o envelope", "actor_name": "Maria Souza", "actor_email": "maria@exemplo.com.br", "source": "web", "ip": "177.32.4.18", "envelope_status": "delivered", "document_sha256": null, "created_at": "2026-11-11T13:40:02+00:00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/envelopes/{id}/documents/{kind}": { "get": { "operationId": "downloadDocument", "tags": [ "Documentos" ], "summary": "Baixar documento", "description": "Baixa um arquivo do envelope **concluído**. A resposta é o próprio arquivo, com o nome em\n`Content-Disposition`. Antes da conclusão, todos os tipos respondem `404` (\"Documento ainda não\nconcluído.\"); o carimbo do tempo responde `404` enquanto não for emitido.\n\n| `kind` | Arquivo |\n|---|---|\n| `signed` | **Documento assinado** (PDF): os documentos com a trilha de assinaturas no fim. É o arquivo do `final_sha256` |\n| `original` | **Documento original** (PDF): os documentos como foram enviados, antes das assinaturas |\n| `package` | **Trilha completa** (ZIP): documento assinado, original, comprovante de conclusão, carimbo do tempo `.tsr` (quando emitido) e `LEIA-ME.txt` |\n| `final` | o contrato final exatamente como gravado na conclusão (bytes do `final_sha256`) |\n| `certificate` | comprovante de conclusão (PDF), selado com o selo eletrônico ICP-Brasil da plataforma quando `proofs.seal.issued` |\n| `timestamp` | carimbo do tempo RFC 3161 da FreeTSA sobre o contrato final (`.tsr`) |\n\nConfira a integridade calculando o SHA-256 do arquivo `signed` (ou `final`) e comparando com\n`final_sha256`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Identificador do envelope (UUID), o `id` devolvido na criação.", "schema": { "type": "string", "format": "uuid" }, "example": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f" }, { "name": "kind", "in": "path", "required": true, "description": "Tipo do arquivo.", "schema": { "type": "string", "enum": [ "signed", "original", "package", "final", "certificate", "timestamp" ] }, "example": "signed" } ], "responses": { "200": { "description": "O arquivo.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Content-Disposition": { "description": "attachment; filename=\"...\" com o nome e a extensão certos.", "schema": { "type": "string" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/zip": { "schema": { "type": "string", "format": "binary" } }, "application/timestamp-reply": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "x-odsign-binary": true } } }, "webhooks": { "envelope.sent": { "post": { "operationId": "webhook_envelope_sent", "summary": "envelope.sent", "description": "O envelope foi enviado (também quando as correções são enviadas).", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.sent" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "envelope.sent", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "sent", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": null } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "envelope.delivered": { "post": { "operationId": "webhook_envelope_delivered", "summary": "envelope.delivered", "description": "O primeiro destinatário abriu o envelope.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.delivered" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "envelope.delivered", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "delivered", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": null } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "envelope.completed": { "post": { "operationId": "webhook_envelope_completed", "summary": "envelope.completed", "description": "Todos concluíram: o documento assinado (com a trilha de assinaturas) está pronto para baixar.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.completed" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "envelope.completed", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "completed", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": "2026-11-11T13:42:11+00:00", "final_sha256": "b7d4c0e1a9f35a2c8e6d1f0b3a7c9e2d4f6a8b0c1d3e5f7a9b2c4d6e8f0a1b3c" }, "recipient": null } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "envelope.declined": { "post": { "operationId": "webhook_envelope_declined", "summary": "envelope.declined", "description": "Um destinatário recusou e o envelope foi encerrado.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.declined" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "envelope.declined", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "declined", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": null } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "envelope.voided": { "post": { "operationId": "webhook_envelope_voided", "summary": "envelope.voided", "description": "O remetente anulou o envelope.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.voided" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "envelope.voided", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "voided", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": null } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "recipient.sent": { "post": { "operationId": "webhook_recipient_sent", "summary": "recipient.sent", "description": "O convite saiu para um destinatário (com ordem de assinatura, quando chega a vez dele).", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.sent" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "recipient.sent", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "sent", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": { "id": 2051, "name": "Maria Souza", "email": "maria@exemplo.com.br", "status": "sent", "routing_order": 1 } } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "recipient.delivered": { "post": { "operationId": "webhook_recipient_delivered", "summary": "recipient.delivered", "description": "Um destinatário abriu o documento pela primeira vez.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.delivered" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "recipient.delivered", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "delivered", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": { "id": 2051, "name": "Maria Souza", "email": "maria@exemplo.com.br", "status": "delivered", "routing_order": 1 } } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "recipient.signed": { "post": { "operationId": "webhook_recipient_signed", "summary": "recipient.signed", "description": "Um destinatário concluiu a parte dele (assinou ou, se viewer, visualizou).", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.signed" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "recipient.signed", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "delivered", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": { "id": 2051, "name": "Maria Souza", "email": "maria@exemplo.com.br", "status": "signed", "routing_order": 1 } } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } }, "recipient.declined": { "post": { "operationId": "webhook_recipient_declined", "summary": "recipient.declined", "description": "Um destinatário recusou a assinatura.", "parameters": [ { "name": "X-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.declined" } }, { "name": "X-Signature", "in": "header", "required": true, "description": "HMAC-SHA256 do corpo bruto com o segredo do webhook, em hexadecimal minúsculo (64 caracteres).", "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "event": "recipient.declined", "sent_at": "2026-11-11T13:42:11+00:00", "envelope": { "id": "01a1cc92-f28f-73b8-8dcc-f15232d31a3f", "subject": "Contrato de prestação de serviços", "status": "declined", "sent_at": "2026-11-11T13:05:12+00:00", "completed_at": null, "final_sha256": null }, "recipient": { "id": 2051, "name": "Maria Souza", "email": "maria@exemplo.com.br", "status": "declined", "routing_order": 1 } } } } }, "responses": { "2XX": { "description": "Recebido. Responda em poucos segundos; qualquer outro código, redirecionamento ou falta de resposta gera nova tentativa (até 3: na hora, ~10 s e ~1 min depois)." } } } } }, "components": { "securitySchemes": { "token": { "type": "http", "scheme": "bearer", "bearerFormat": "ods_ + 48 caracteres", "description": "Token pessoal criado por um administrador em **Configurações › Conta › Tokens da API**\n(exibido uma única vez). Age em nome do usuário que o criou e com o perfil dele: administrador\nalcança todos os envelopes da conta; os demais perfis, só os que enviaram. Usuário bloqueado ou\nexcluído e conta suspensa invalidam o token na hora (`401`)." } }, "headers": { "X-RateLimit-Limit": { "description": "Requisições permitidas por minuto para este usuário (120).", "schema": { "type": "integer", "example": 120 } }, "X-RateLimit-Remaining": { "description": "Requisições que ainda cabem na janela atual de 1 minuto.", "schema": { "type": "integer", "example": 118 } }, "Retry-After": { "description": "Segundos até a janela liberar (só no 429).", "schema": { "type": "integer", "example": 42 } }, "X-RateLimit-Reset": { "description": "Momento (Unix, em segundos) em que a janela libera (só no 429).", "schema": { "type": "integer", "example": 1794432000 } } }, "responses": { "Unauthorized": { "description": "Token ausente, inválido, de usuário bloqueado ou excluído, ou de conta suspensa.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Não autenticado." } } } }, "Forbidden": { "description": "O token é válido, mas o usuário não pode fazer esta operação (envelope de outro remetente sem ser administrador, ou perfil sem envio).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Este token não tem acesso a este envelope: só o remetente e os administradores da conta o gerenciam." } } } }, "NotFound": { "description": "Envelope inexistente ou de outra conta, endpoint errado, tipo de documento inválido ou documento ainda não concluído.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Envelope não encontrado." } } } }, "ValidationError": { "description": "Dados inválidos (`errors` traz a lista por campo) ou pendências que impedem a operação (`errors.envelope`).", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Escolha a forma de autenticação de Maria Souza.", "errors": { "envelope": [ "Escolha a forma de autenticação de Maria Souza." ] } } } } }, "TooManyRequests": { "description": "Limite de 120 requisições por minuto atingido. Espere `Retry-After` segundos.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Limite de requisições atingido. Tente de novo em 42 s." } } } } }, "schemas": { "Error": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Resumo do problema, para exibir ou registrar." }, "errors": { "type": "object", "description": "Só no 422: lista de mensagens por campo. A chave é o caminho do campo (`subject`, `files.0`, `recipients.1.email`) ou `envelope` (pendências do envio). As mensagens de validação de formato vêm em inglês; as pendências do envio, em português.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "Message": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string" } } }, "EnvelopeStatus": { "type": "string", "enum": [ "created", "sent", "delivered", "correct", "completed", "declined", "voided", "expired" ], "description": "Estado do envelope: `created` = rascunho; `sent` = em curso, ninguém abriu ainda; `delivered` = em curso, alguém já abriu; `correct` = em correção pelo remetente; `completed` = concluído; `declined` = recusado; `voided` = anulado; `expired` = expirado." }, "RecipientStatus": { "type": "string", "enum": [ "created", "sent", "delivered", "signed", "completed", "declined" ], "description": "Estado do destinatário: `created` = aguardando a vez; `sent` = convite enviado; `delivered` = abriu o documento; `signed` = assinou (ou visualizou, se viewer); `completed` = cópia entregue na conclusão (cc); `declined` = recusou." }, "RecipientType": { "type": "string", "enum": [ "signer", "in_person_signer", "cc", "viewer" ], "description": "Papel: `signer` = assinatura obrigatória; `in_person_signer` = assinatura presencial; `cc` = apenas cópia (recebe o documento na conclusão); `viewer` = apenas visualização (precisa abrir, não assina)." }, "AuthMethod": { "type": "string", "enum": [ "link", "signature", "email", "sms", "whatsapp", "document" ], "description": "Forma de autenticação de quem assina: `link` = só o acesso pelo link pessoal e a confirmação na tela; `signature` = assinatura manuscrita desenhada na tela; `email` = token de 6 dígitos enviado ao e-mail na hora de assinar (exige `channel=email`); `sms` = token de 6 dígitos por SMS (exige `phone`); `whatsapp` = token de 6 dígitos pelo WhatsApp (exige `phone`); `document` = fotos da frente e do verso de um documento oficial com foto, pela câmera do navegador (conforme o plano)." }, "Channel": { "type": "string", "enum": [ "email", "whatsapp", "sms" ], "description": "Forma de envio do convite e dos lembretes. Com `whatsapp` ou `sms` (exige `phone`), a mensagem sai pelo número da plataforma e conta na cota do plano." }, "EnvelopeSummary": { "type": "object", "description": "Item da listagem (resumo).", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "status_label": { "type": "string", "description": "Nome do estado no app (Rascunho, Em curso, Concluído...)." }, "recipients": { "type": "string", "description": "Nomes dos destinatários, separados por vírgula." }, "progress": { "type": "integer", "minimum": 0, "maximum": 100, "description": "Porcentagem de quem precisa agir e já concluiu." }, "waiting_for": { "type": [ "string", "null" ], "description": "Nome de quem está na vez (ou `me`, quando é o próprio dono do token); `null` fora de curso." }, "sender": { "type": [ "string", "null" ], "description": "Nome do remetente." }, "sender_id": { "type": [ "integer", "null" ] }, "sender_avatar_url": { "type": [ "string", "null" ] }, "folder_id": { "type": [ "integer", "null" ], "description": "Pasta do app (organização interna)." }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando expira, se a validade estiver ligada." }, "deleted": { "type": "boolean", "description": "Sempre `false` na API (eliminados não são listados)." } } }, "EnvelopeList": { "type": "object", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeSummary" } }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "PageMeta": { "type": "object", "properties": { "page": { "type": "integer", "description": "Página atual." }, "per_page": { "type": "integer" }, "total": { "type": "integer", "description": "Total de envelopes no filtro." }, "last_page": { "type": "integer", "description": "Última página (1 quando não há resultados)." } } }, "Envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Identificador do envelope." }, "is_template": { "type": "boolean", "description": "Sempre `false` na API (modelos não são expostos)." }, "template_name": { "type": [ "string", "null" ] }, "template_description": { "type": [ "string", "null" ] }, "subject": { "type": "string", "description": "Assunto (vai no convite)." }, "message": { "type": [ "string", "null" ], "description": "Mensagem para todos os destinatários." }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "status_label": { "type": "string" }, "editable": { "type": "boolean", "description": "`true` só no rascunho." }, "signing_order_enabled": { "type": "boolean", "description": "Segue a ordem de assinatura (`routing_order`)." }, "current_routing_order": { "type": "integer", "description": "Ordem que está na vez." }, "reminder_enabled": { "type": "boolean", "description": "Lembretes automáticos (padrão da conta em Configurações › Conta)." }, "reminder_delay_days": { "type": "integer" }, "reminder_frequency_days": { "type": "integer" }, "expire_enabled": { "type": "boolean", "description": "Validade (padrão da conta)." }, "expire_after_days": { "type": "integer" }, "expire_warn_days": { "type": "integer" }, "allow_reassign": { "type": "boolean" }, "category": { "type": [ "string", "null" ] }, "sender": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "folder": { "type": [ "string", "null" ], "description": "Nome da pasta no app." }, "void_reason": { "type": [ "string", "null" ] }, "original_sha256": { "type": [ "string", "null" ], "description": "SHA-256 dos documentos como foram enviados (definido no envio)." }, "final_sha256": { "type": [ "string", "null" ], "description": "SHA-256 do documento assinado (definido na conclusão)." }, "has_final": { "type": "boolean", "description": "O documento assinado está pronto para baixar." }, "has_certificate": { "type": "boolean" }, "proofs": { "$ref": "#/components/schemas/Proofs" }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Primeiro envio." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Conclusão." }, "voided_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Anulação." }, "declined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Recusa." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiração prevista." }, "updated_at": { "type": "string", "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Sempre `null` na API." }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" }, "description": "Campos posicionados (vazio quando todos assinam pela forma de autenticação)." } } }, "Document": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string", "description": "Nome do arquivo enviado." }, "order": { "type": "integer", "description": "Posição no envelope, a partir de 1." }, "pages": { "type": "integer" }, "page_sizes": { "type": "array", "description": "Tamanho de cada página em pontos PDF (A4 = 595 × 842).", "items": { "type": "object", "properties": { "w": { "type": "number" }, "h": { "type": "number" } } } }, "size": { "type": "integer", "description": "Tamanho do PDF em bytes." }, "url": { "type": "string", "description": "Endereço no app (exige login). Para baixar pela API, use os downloads." } } }, "Recipient": { "type": "object", "properties": { "id": { "type": "integer", "description": "Identificador do destinatário (o mesmo dos webhooks)." }, "type": { "$ref": "#/components/schemas/RecipientType" }, "type_label": { "type": "string" }, "role_name": { "type": [ "string", "null" ], "description": "Só em envelopes criados de modelo, no app." }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "routing_order": { "type": "integer", "description": "Ordem de assinatura (vale com `signing_order_enabled`)." }, "status": { "$ref": "#/components/schemas/RecipientStatus" }, "status_label": { "type": "string" }, "has_access_code": { "type": "boolean", "description": "Exige código de acesso combinado (definido no app)." }, "phone": { "type": [ "string", "null" ], "description": "Celular só com dígitos e o código do país (5511987654321)." }, "channel": { "$ref": "#/components/schemas/Channel" }, "whatsapp_auth": { "type": "boolean", "description": "Código pelo WhatsApp para **abrir** o documento (opção antiga; prefira `auth_method`)." }, "sms_auth": { "type": "boolean", "description": "Código por SMS para **abrir** o documento (opção antiga; prefira `auth_method`)." }, "auth_method": { "oneOf": [ { "$ref": "#/components/schemas/AuthMethod" }, { "type": "null" } ], "description": "`null` para quem não assina (cc, viewer) e para quem assina pelos campos." }, "auth_label": { "type": [ "string", "null" ], "description": "Nome da forma de autenticação (Link pessoal, Assinatura manuscrita, Token por e-mail, Token por SMS, Token pelo WhatsApp, Documento pessoal)." }, "private_message": { "type": [ "string", "null" ] }, "color_index": { "type": [ "integer", "null" ], "description": "Cor do destinatário no app." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Convite enviado." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Primeira abertura." }, "signed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Assinatura (ou visualização registrada)." }, "declined_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Recusa." }, "decline_reason": { "type": [ "string", "null" ] } } }, "Field": { "type": "object", "description": "Campo posicionado no documento. Coordenadas em pontos PDF (72 por polegada), origem no canto **superior** esquerdo da página.", "properties": { "id": { "type": "integer" }, "document_id": { "type": "integer" }, "recipient_id": { "type": "integer" }, "type": { "type": "string", "enum": [ "signature", "initials", "date_signed", "name", "email", "company", "title", "text", "number", "checkbox", "dropdown", "radio", "approve", "decline", "note", "attachment" ] }, "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "required": { "type": "boolean" }, "read_only": { "type": "boolean" }, "label": { "type": [ "string", "null" ] }, "tooltip": { "type": [ "string", "null" ] }, "default_value": { "type": [ "string", "null" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "validation": { "type": [ "string", "null" ] }, "max_length": { "type": [ "integer", "null" ] }, "font": { "type": [ "string", "null" ] }, "font_size": { "type": [ "integer", "null" ] }, "font_color": { "type": [ "string", "null" ] } } }, "Proofs": { "type": "object", "description": "Provas de integridade do envelope concluído. `timestamp` e `seal` são `null` quando a integração não estava ativa na conclusão.", "properties": { "timestamp": { "oneOf": [ { "$ref": "#/components/schemas/Proof" }, { "type": "null" } ], "description": "Carimbo do tempo RFC 3161 (FreeTSA) sobre o documento assinado." }, "seal": { "oneOf": [ { "$ref": "#/components/schemas/Proof" }, { "type": "null" } ], "description": "Selo eletrônico ICP-Brasil da plataforma sobre o comprovante de conclusão." }, "package": { "type": "boolean", "description": "Há prova emitida (a trilha completa em ZIP inclui as provas)." } } }, "Proof": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "issued", "failed" ], "description": "`pending` = na fila (novas tentativas automáticas); `issued` = emitida; `failed` = não emitida." }, "issued": { "type": "boolean", "description": "Emitida e verificada." }, "issued_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Hora da emissão (genTime do carimbo ou hora do selo)." }, "verified_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Hora da verificação." }, "attempts": { "type": "integer" }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Última tentativa." }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Próxima tentativa (pendente)." }, "last_error": { "type": [ "string", "null" ] }, "sha256": { "type": [ "string", "null" ], "description": "SHA-256 do `.tsr` ou do comprovante selado." }, "serial": { "type": [ "string", "null" ] }, "policy": { "type": [ "string", "null" ] }, "authority": { "type": [ "string", "null" ], "description": "Quem emitiu (TSA ou titular do certificado do selo)." }, "cnpj": { "type": [ "string", "null" ], "description": "CNPJ do titular do selo." }, "issuer_name": { "type": [ "string", "null" ], "description": "Autoridade certificadora do selo." }, "development": { "type": "boolean", "description": "`true` só fora de produção (credencial de desenvolvimento)." } } }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "integer" }, "action": { "type": "string", "enum": [ "created", "sent", "resent", "reminder_sent", "opened", "consented", "viewed", "signed", "completed", "declined", "voided", "corrected", "expired", "deleted", "restored", "downloaded", "copy_sent", "access_code_failed", "access_code_verified", "whatsapp_sent", "whatsapp_code_sent", "whatsapp_verified", "whatsapp_code_failed", "sms_sent", "sms_code_sent", "sms_verified", "sms_code_failed", "email_code_sent", "email_code_failed", "signature_token_verified", "identity_document_captured", "identity_document_viewed", "timestamped", "sealed", "document_sealed" ], "description": "Ação registrada (veja `action_label`)." }, "action_label": { "type": "string" }, "description": { "type": "string", "description": "Frase completa, como aparece no histórico." }, "actor_name": { "type": "string", "description": "Quem fez (usuário, destinatário ou \"Sistema\")." }, "actor_email": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "web", "api", "sistema" ] }, "ip": { "type": [ "string", "null" ] }, "envelope_status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "document_sha256": { "type": [ "string", "null" ], "description": "Hash relacionado ao evento (envio, conclusão, foto do documento pessoal)." }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateEnvelopeRequest": { "type": "object", "required": [ "subject", "files[]", "recipients" ], "properties": { "subject": { "type": "string", "maxLength": 100, "description": "Assunto do envelope (vai no convite)." }, "message": { "type": "string", "maxLength": 10000, "description": "Mensagem para todos os destinatários." }, "signing_order": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` segue a ordem de `routing_order` (um de cada vez); `0` envia a todos ao mesmo tempo." }, "files[]": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "format": "binary" }, "description": "De 1 a 10 arquivos PDF, JPG, PNG, DOC ou DOCX, até 25 MB cada. Imagens viram páginas em PDF; Word é convertido para PDF quando a conversão está disponível." }, "recipients": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/RecipientInput" }, "description": "De 1 a 50 destinatários, como `recipients[0][name]`, `recipients[0][email]`..." }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldInput" }, "description": "Campos posicionados (opcional com `auth_method`), como `fields[0][type]`..." }, "send": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "`1` envia logo depois de criar; `0` deixa como rascunho." } } }, "RecipientInput": { "type": "object", "required": [ "name", "email" ], "properties": { "name": { "type": "string", "maxLength": 150 }, "email": { "type": "string", "format": "email", "description": "Obrigatório na API, mesmo para quem recebe pelo celular." }, "type": { "$ref": "#/components/schemas/RecipientType" }, "routing_order": { "type": "integer", "minimum": 1, "description": "Ordem de assinatura (padrão: a posição na lista). Vale com `signing_order=1`." }, "phone": { "type": "string", "maxLength": 30, "description": "Celular com DDD (`11987654321`); fora do Brasil, `+` e o código do país." }, "channel": { "$ref": "#/components/schemas/Channel" }, "auth_method": { "$ref": "#/components/schemas/AuthMethod" }, "whatsapp_auth": { "type": "integer", "enum": [ 0, 1 ], "description": "Opção antiga: código pelo WhatsApp para abrir (precisa de `phone`)." }, "sms_auth": { "type": "integer", "enum": [ 0, 1 ], "description": "Opção antiga: código por SMS para abrir (precisa de `phone`)." } } }, "FieldInput": { "type": "object", "required": [ "recipient_index", "type", "page", "x", "y" ], "properties": { "recipient_index": { "type": "integer", "minimum": 0, "description": "Posição do destinatário em `recipients`, a partir de 0." }, "document_index": { "type": "integer", "minimum": 0, "default": 0, "description": "Posição do arquivo em `files[]`, a partir de 0." }, "type": { "type": "string", "enum": [ "signature", "initials", "date_signed", "name", "email", "company", "title", "text", "number", "checkbox", "note" ], "description": "Tipo do campo. Tamanhos padrão (pontos): `signature` 120×40, `initials` 60×36, `date_signed` 110×18, `name` 150×18, `email` 170×18, `company` 150×18, `title` 120×18, `text` 140×20, `number` 90×20, `checkbox` 14×14, `note` 160×40." }, "page": { "type": "integer", "minimum": 1 }, "x": { "type": "number", "minimum": 0, "description": "Distância da borda esquerda da página, em pontos." }, "y": { "type": "number", "minimum": 0, "description": "Distância da borda **superior** da página, em pontos." }, "width": { "type": "number", "minimum": 8 }, "height": { "type": "number", "minimum": 8 }, "required": { "type": "integer", "enum": [ 0, 1 ], "default": 1 } } }, "WebhookEvent": { "type": "object", "required": [ "event", "sent_at", "envelope", "recipient" ], "description": "Corpo de cada entrega de webhook (POST, JSON). Assinado em `X-Signature` = HMAC-SHA256 do corpo bruto com o segredo `whsec_...`, em hexadecimal minúsculo.", "properties": { "event": { "type": "string", "enum": [ "envelope.sent", "envelope.delivered", "envelope.completed", "envelope.declined", "envelope.voided", "recipient.sent", "recipient.delivered", "recipient.signed", "recipient.declined" ] }, "sent_at": { "type": "string", "format": "date-time", "description": "Quando o evento foi gerado." }, "envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "final_sha256": { "type": [ "string", "null" ] } } }, "recipient": { "type": [ "object", "null" ], "description": "`null` nos eventos `envelope.*`.", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/RecipientStatus" }, "routing_order": { "type": "integer" } } } } }, "WebhookPing": { "type": "object", "description": "Corpo do botão Testar (Configurações › Webhooks), assinado da mesma forma.", "properties": { "event": { "type": "string", "const": "test.ping" }, "sent_at": { "type": "string", "format": "date-time" } } } } } }