{ "openapi": "3.0.4", "info": { "title": "CLP Assinaturas — API de integração", "version": "v1-2026-09-28", "description": "Contratações abertas. Requer conta habilitada, chave, remetente verificado e proteção disponível. Inclui piloto opcional de IA; não inclui administração, sessão do portal ou webhooks internos de PSP.", "contact": { "name": "CLP Sistemas", "email": "contato@clpsistemas.com.br", "url": "https://clpsistemas.com.br/documentacao" } }, "paths": { "/v1/account/subscription": { "get": { "tags": [ "Conta e planos" ], "summary": "Consultar vigência, plano e uso compartilhado de documentos.", "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_account_subscription" } }, "/v1/account/renew": { "post": { "tags": [ "Conta e planos" ], "summary": "Criar ou reutilizar a fatura do ciclo; depende do provedor de pagamento habilitado.", "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "post_v1_account_renew" } }, "/v1/account/invoices": { "get": { "tags": [ "Conta e planos" ], "summary": "Listar até 200 faturas, da mais recente para a mais antiga.", "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_account_invoices" } }, "/v1/account/invoices/{id}": { "get": { "tags": [ "Conta e planos" ], "summary": "Consultar uma fatura da empresa.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_account_invoices_id" } }, "/v1/account/invoices/{id}/check": { "post": { "tags": [ "Conta e planos" ], "summary": "Conferir a fatura no provedor de pagamento.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "post_v1_account_invoices_id_check" } }, "/v1/account/usage": { "get": { "tags": [ "Conta e planos" ], "summary": "Consultar histórico mensal de assinaturas diretas; franquia total em account/subscription.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_account_usage" } }, "/v1/account/webhook": { "put": { "tags": [ "Webhooks" ], "summary": "Configurar URL HTTPS e obter o segredo HMAC.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "Configuração; guardar o segredo. O campo events é uma lista histórica e não exaustiva; os eventos envelope.* estão documentados no guia.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfiguration" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "put_v1_account_webhook" }, "delete": { "tags": [ "Webhooks" ], "summary": "Remover a configuração de webhook.", "responses": { "204": { "description": "No Content" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "delete_v1_account_webhook" } }, "/v1/account/webhook/test": { "post": { "tags": [ "Webhooks" ], "summary": "Enfileirar webhook.test; 202 não comprova entrega.", "responses": { "202": { "description": "Evento enfileirado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" } }, "required": [ "delivery_id", "status" ] } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "post_v1_account_webhook_test" } }, "/v1/account/webhook/deliveries": { "get": { "tags": [ "Webhooks" ], "summary": "Listar as 50 entregas de webhook mais recentes.", "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_account_webhook_deliveries" } }, "/v1/certificates": { "post": { "tags": [ "Certificados" ], "summary": "Importar certificado próprio, com autorização expressa em multipart.", "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDto" } } } }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "post_v1_certificates", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CertificateForm" } } } } }, "get": { "tags": [ "Certificados" ], "summary": "Listar certificados da empresa.", "responses": { "200": { "description": "Metadados, sem PFX nem senha.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CertificateDto" } } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "get_v1_certificates" } }, "/v1/certificates/{id}": { "get": { "tags": [ "Certificados" ], "summary": "Consultar metadados de um certificado.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Metadados, sem PFX nem senha.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateDto" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "get_v1_certificates_id" }, "delete": { "tags": [ "Certificados" ], "summary": "Bloquear o uso e remover o certificado do cofre.", "responses": { "204": { "description": "No Content" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "delete_v1_certificates_id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/public/plans": { "get": { "tags": [ "Conta e planos" ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "summary": "Consultar os planos públicos e suas franquias.", "operationId": "get_public_plans", "security": [] } }, "/v1/envelopes/protection": { "get": { "tags": [ "Envelopes" ], "responses": { "200": { "description": "Disponibilidade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Protection" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Consultar disponibilidade da proteção pelo prestador.", "operationId": "get_v1_envelopes_protection" } }, "/v1/envelopes": { "get": { "tags": [ "Envelopes" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } } ], "responses": { "200": { "description": "Array de até 100 envelopes, sem total ou cursor.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Envelope" } } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Listar envelopes em array, 100 por página.", "operationId": "get_v1_envelopes" }, "post": { "tags": [ "Envelopes" ], "responses": { "201": { "description": "Criado e convites enfileirados.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "200": { "description": "Repetição idempotente.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Criar envelope e enfileirar convites; não retorna links individuais.", "operationId": "post_v1_envelopes", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EnvelopeForm" } } } } } }, "/v1/envelopes/{id}": { "get": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Envelope e destinatários; campos sem valor podem ser omitidos.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Consultar envelope e situação dos destinatários.", "operationId": "get_v1_envelopes_id" } }, "/v1/envelopes/{id}/files/{kind}": { "get": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "original", "final", "evidence" ] } } ], "responses": { "200": { "description": "Bytes de PDF (original/final) ou JSON (evidence).", "headers": { "X-Content-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Baixar original, final ou evidence com autenticação.", "operationId": "get_v1_envelopes_id_files_kind" } }, "/v1/envelopes/{id}/signing-links": { "get": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Links já existentes, sem disparar novos convites. Somente destinatários pendentes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningLinks" } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "enum": [ "private, no-store" ] } } } }, "401": { "description": "Chave ausente ou inválida." }, "404": { "description": "Envelope não encontrado nesta empresa." }, "409": { "description": "Envelope encerrado ou prazo de assinatura expirado." }, "410": { "description": "Prazo de guarda vencido, arquivo removido ou link indisponível." }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Consultar links privados dos destinatários pendentes; exige envelope aberto e não expirado.", "operationId": "get_v1_envelopes_id_signing_links" } }, "/v1/envelopes/{id}/files/{kind}/link": { "get": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "kind", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "original", "final", "evidence" ] } } ], "responses": { "200": { "description": "URL opcional; conferir direct.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivateLink" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Obter link curto quando disponível; direct=false exige download normal.", "operationId": "get_v1_envelopes_id_files_kind_link" } }, "/v1/envelopes/{id}/cancel": { "post": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "summary": "Cancelar envelope em sent.", "operationId": "post_v1_envelopes_id_cancel" } }, "/v1/envelopes/{id}/resend": { "post": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Operação aceita; consulte o estado posteriormente." }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Reenviar convites pendentes, até três operações/hora.", "operationId": "post_v1_envelopes_id_resend" } }, "/v1/envelopes/{id}/delivery-receipts": { "post": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryReceipt" } } }, "required": true }, "responses": { "200": { "description": "Recibo registrado, sem alterar o prazo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArchiveReceipt" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Registrar arquivamento após conferir os hashes dos três arquivos.", "operationId": "post_v1_envelopes_id_delivery_receipts" } }, "/v1/envelopes/{id}/retry": { "post": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Operação aceita; consulte o estado posteriormente." }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Retomar uma finalização em sealing_failed.", "operationId": "post_v1_envelopes_id_retry" } }, "/v1/envelopes/{id}/certificate": { "put": { "tags": [ "Envelopes" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceCertificate" } } }, "required": true }, "responses": { "202": { "description": "Operação aceita; consulte o estado posteriormente." }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "summary": "Retomar falha com certificado válido antes de existir PDF final; {} em platform.", "operationId": "put_v1_envelopes_id_certificate" } }, "/v1/signatures": { "post": { "tags": [ "Assinatura direta" ], "summary": "Assinar diretamente com certificado próprio; sem fluxo de aceites nem guarda do PDF.", "responses": { "200": { "description": "PDF na primeira resposta normal; JSON com response=json ou replay idempotente (sem PDF).", "headers": { "X-Signature-Id": { "schema": { "type": "string", "format": "uuid" } }, "X-Signed-Sha256": { "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "Idempotent-Replay": { "schema": { "type": "string", "enum": [ "true" ] } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } }, "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SignatureResult" }, { "$ref": "#/components/schemas/SignatureReplay" } ] } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "post_v1_signatures", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, { "name": "response", "in": "query", "schema": { "type": "string", "enum": [ "json" ] } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SignatureForm" } } } } }, "get": { "tags": [ "Assinatura direta" ], "summary": "Listar registros de assinaturas diretas, com paginação e filtros.", "parameters": [ { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "certificateId", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "page", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 1 } }, { "name": "pageSize", "in": "query", "schema": { "type": "integer", "format": "int32", "default": 50 } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_signatures" } }, "/v1/signatures/{id}": { "get": { "tags": [ "Assinatura direta" ], "summary": "Consultar auditoria de uma assinatura direta.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK" }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "get_v1_signatures_id" } }, "/v1/verify": { "post": { "tags": [ "Assinatura direta" ], "summary": "Verificar integridade e cadeia das assinaturas do PDF; não é análise jurídica.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationReport" } } } }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "operationId": "post_v1_verify", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pdf": { "type": "string", "format": "binary" } }, "required": [ "pdf" ] } }, "application/json": { "schema": { "type": "object", "properties": { "pdf_base64": { "type": "string", "format": "byte" } }, "required": [ "pdf_base64" ] } } } } } }, "/v1/ai/analyses": { "post": { "responses": { "200": { "description": "Estado e resultado quando concluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAnalysis" } } } }, "202": { "description": "Ainda processando; consultar o mesmo ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAnalysis" } } } }, "410": { "description": "Rascunho expirado ou descartado." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 128 } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "pdf": { "type": "string", "format": "binary" }, "allow_ai_processing": { "type": "string", "enum": [ "true" ] } }, "required": [ "pdf", "allow_ai_processing" ] } } } }, "summary": "Analisar PDF com autorização específica; não envia convites.", "operationId": "post_v1_ai_analyses", "tags": [ "Conferência com IA" ] } }, "/v1/ai/capabilities": { "get": { "responses": { "200": { "description": "Limites atuais da empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCapabilities" } } } }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "summary": "Consultar disponibilidade e franquia do piloto de IA.", "operationId": "get_v1_ai_capabilities", "tags": [ "Conferência com IA" ] } }, "/v1/ai/analyses/{id}/compare": { "post": { "responses": { "200": { "description": "Conferência limitada, sempre sujeita a revisão humana.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiComparison" } } } }, "409": { "description": "Análise não concluída." }, "410": { "description": "Rascunho indisponível." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiCompareInput" } } } }, "summary": "Conferir dados do ERP contra trechos extraídos, sem nova chamada ao modelo.", "operationId": "post_v1_ai_analyses_id_compare", "tags": [ "Conferência com IA" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } }, "/v1/ai/analyses/{id}": { "get": { "responses": { "200": { "description": "Estado e resultado quando concluído.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAnalysis" } } } }, "202": { "description": "Ainda processando; consultar o mesmo ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiAnalysis" } } } }, "410": { "description": "Rascunho expirado ou descartado." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "summary": "Consultar análise da empresa enquanto o rascunho estiver disponível.", "operationId": "get_v1_ai_analyses_id", "tags": [ "Conferência com IA" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] }, "delete": { "responses": { "204": { "description": "Resultado descartado." }, "404": { "description": "Análise não encontrada nesta empresa." }, "default": { "description": "Erro tratado pela API; infraestrutura e rate limit podem responder sem JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Limite de requisições ou reenvios; corpo e Retry-After não são garantidos." } }, "summary": "Descartar o resultado do rascunho; não altera resumo já vinculado a envelope.", "operationId": "delete_v1_ai_analyses_id", "tags": [ "Conferência com IA" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ] } } }, "components": { "schemas": { "AiAnalysis": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "processing", "completed", "failed", "interrupted" ] }, "document_sha256": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "schema": { "type": "string" }, "model": { "type": "string" }, "requires_review": { "type": "boolean" }, "error_code": { "type": "string" }, "result": { "$ref": "#/components/schemas/AiResult" } }, "required": [ "id", "status", "requires_review" ] }, "AiCapabilities": { "type": "object", "properties": { "available": { "type": "boolean" }, "mode": { "type": "string" }, "provider": { "type": "string" }, "text_pdf_only": { "type": "boolean" }, "max_pdf_bytes": { "type": "integer" }, "max_pages": { "type": "integer" }, "monthly_analysis_limit": { "type": "integer" }, "analyses_used": { "type": "integer" }, "analyses_remaining": { "type": "integer" }, "draft_hours": { "type": "integer" }, "period_ends_at": { "type": "string", "format": "date-time" }, "comparison_fields": { "type": "array", "items": { "type": "string" } }, "comparison_schema": { "type": "string" }, "message": { "type": "string" } } }, "AiCompareInput": { "type": "object", "properties": { "monthly_amount_brl": { "type": "number", "minimum": 0.01, "maximum": 999999999999.99, "multipleOf": 0.01 }, "term_months": { "type": "integer", "minimum": 1, "maximum": 1200 }, "party_documents": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" } } }, "additionalProperties": false, "anyOf": [ { "required": [ "monthly_amount_brl" ] }, { "required": [ "term_months" ] }, { "required": [ "party_documents" ] } ] }, "AiComparison": { "type": "object", "properties": { "analysis_id": { "type": "string", "format": "uuid" }, "document_sha256": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "schema": { "type": "string" }, "comparison": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "no_difference_detected", "needs_review", "inconclusive" ] }, "requires_review": { "type": "boolean" }, "notice": { "type": "string" }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/AiWarning" } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "expected": { "type": "string" }, "status": { "type": "string", "enum": [ "matching", "possible_mismatch", "inconclusive" ] }, "observed": { "type": "string" }, "message": { "type": "string" }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/AiSource" } } } } } } } } }, "AiFact": { "type": "object", "properties": { "kind": { "type": "string" }, "value": { "type": "string" }, "source": { "$ref": "#/components/schemas/AiSource" } } }, "AiResult": { "type": "object", "properties": { "title": { "type": "string" }, "pages": { "type": "integer" }, "unreadable_pages": { "type": "array", "items": { "type": "integer" } }, "facts": { "type": "array", "items": { "$ref": "#/components/schemas/AiFact" } }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/AiWarning" } }, "participants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string" }, "role": { "type": "string" }, "document": { "type": "string" }, "source": { "$ref": "#/components/schemas/AiSource" } } } } } }, "AiSource": { "type": "object", "properties": { "page": { "type": "integer" }, "quote": { "type": "string" } }, "required": [ "page", "quote" ] }, "AiWarning": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "page": { "type": "integer" } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "code", "message", "request_id" ] } }, "required": [ "error" ] }, "ArchiveReceipt": { "type": "object", "properties": { "archived_at": { "type": "string", "format": "date-time" }, "retain_until": { "type": "string", "format": "date-time" } }, "required": [ "archived_at" ] }, "CertificateDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "subject": { "type": "string", "nullable": true }, "commonName": { "type": "string", "nullable": true }, "document": { "type": "string", "nullable": true }, "documentType": { "type": "string", "nullable": true }, "issuer": { "type": "string", "nullable": true }, "serialNumber": { "type": "string", "nullable": true }, "notBefore": { "type": "string", "format": "date-time" }, "notAfter": { "type": "string", "format": "date-time" }, "thumbprint": { "type": "string", "nullable": true }, "keySize": { "type": "integer", "format": "int32" }, "icpBrasil": { "type": "boolean" }, "status": { "type": "string", "nullable": true }, "vaultProvider": { "type": "string", "nullable": true }, "authorizationVersion": { "type": "string", "nullable": true }, "authorizationAcceptedAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "deletedAt": { "type": "string", "format": "date-time", "nullable": true } }, "additionalProperties": false }, "CertificateForm": { "type": "object", "properties": { "pfx": { "type": "string", "format": "binary", "description": "PFX/P12 até 256 KB." }, "password": { "type": "string", "format": "password", "writeOnly": true }, "accept_authorization": { "type": "string", "enum": [ "true" ], "description": "Autorização expressa para uso do certificado. Obrigatória em produção." } }, "required": [ "pfx", "accept_authorization" ] }, "DeliveryReceipt": { "type": "object", "properties": { "original_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "final_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidence_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "original_sha256", "final_sha256", "evidence_sha256" ] }, "Envelope": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "external_id": { "type": "string" }, "status": { "type": "string", "enum": [ "sent", "accepted", "completed", "sealing_failed", "declined", "canceled", "expired", "purged" ] }, "sequence": { "type": "integer" }, "certificate_id": { "type": "string", "format": "uuid" }, "protection_mode": { "type": "string", "enum": [ "platform", "customer" ] }, "protection_name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "retain_until": { "type": "string", "format": "date-time" }, "purged_at": { "type": "string", "format": "date-time" }, "archived_at": { "type": "string", "format": "date-time" }, "retention_days": { "type": "integer" }, "storage_years": { "type": "integer" }, "retention_policy": { "type": "string" }, "original_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "final_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "evidence_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "error_code": { "type": "string" } }, "required": [ "id", "status", "sequence", "title" ] }, "EnvelopeDetail": { "type": "object", "properties": { "envelope": { "$ref": "#/components/schemas/Envelope" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientStatus" } } }, "required": [ "envelope", "recipients" ] }, "EnvelopeForm": { "type": "object", "properties": { "pdf": { "type": "string", "format": "binary" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "recipients": { "type": "string", "description": "Array JSON serializado com 1 a 5 objetos name/email, e-mails distintos.", "example": "[{\"name\":\"Ana Exemplo\",\"email\":\"ana@example.com\"}]" }, "external_id": { "type": "string", "maxLength": 128 }, "protection_mode": { "type": "string", "enum": [ "platform", "customer" ], "description": "Sem modo: customer se certificate_id informado; senão platform." }, "certificate_id": { "type": "string", "format": "uuid", "description": "Obrigatório em customer; omitir em platform." }, "ai_analysis_id": { "type": "string", "format": "uuid" }, "ai_reviewed": { "type": "string", "enum": [ "true" ] }, "include_ai_summary": { "type": "string", "enum": [ "true", "false" ], "description": "Opcional. Compartilha os trechos revisados com destinatários; exige análise revisada do mesmo PDF." } }, "required": [ "pdf", "title", "recipients" ] }, "PrivateLink": { "type": "object", "properties": { "direct": { "type": "boolean" }, "expires_at": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" } }, "required": [ "direct", "expires_at" ] }, "Protection": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "available": { "type": "boolean" }, "legal_name": { "type": "string" }, "document": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "enabled", "available", "legal_name" ] }, "RecipientStatus": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "viewed_at": { "type": "string", "format": "date-time" }, "accepted_at": { "type": "string", "format": "date-time" }, "declined_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email" ] }, "ReplaceCertificate": { "type": "object", "properties": { "certificate_id": { "type": "string", "format": "uuid" } } }, "SignatureCheck": { "type": "object", "properties": { "index": { "type": "integer", "format": "int32" }, "integrityOk": { "type": "boolean" }, "coversWholeDocument": { "type": "boolean" }, "subFilter": { "type": "string", "nullable": true }, "signerSubject": { "type": "string", "nullable": true }, "signerName": { "type": "string", "nullable": true }, "signerDocument": { "type": "string", "nullable": true }, "signerDocumentType": { "type": "string", "nullable": true }, "issuer": { "type": "string", "nullable": true }, "serialNumber": { "type": "string", "nullable": true }, "notBefore": { "type": "string", "format": "date-time", "nullable": true }, "notAfter": { "type": "string", "format": "date-time", "nullable": true }, "signingTime": { "type": "string", "format": "date-time", "nullable": true }, "digestAlgorithm": { "type": "string", "nullable": true }, "hasSigningCertificateV2": { "type": "boolean" }, "isIcpBrasil": { "type": "boolean" }, "chainOk": { "type": "boolean" }, "chainStatus": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } }, "additionalProperties": false }, "SignatureDto": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "pending", "completed", "failed" ] }, "certificate_id": { "type": "string", "format": "uuid" }, "idempotency_key": { "type": "string" }, "original_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "signed_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "pages": { "type": "integer" }, "profile": { "type": "string" }, "appearance_mode": { "type": "string" }, "appearance_page": { "type": "integer" }, "reason": { "type": "string" }, "location": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "error_code": { "type": "string" } }, "required": [ "id", "status", "certificate_id" ] }, "SignatureForm": { "type": "object", "properties": { "pdf": { "type": "string", "format": "binary" }, "certificate_id": { "type": "string", "format": "uuid" }, "reason": { "type": "string" }, "location": { "type": "string" }, "contact": { "type": "string" }, "appearance": { "type": "string", "description": "JSON serializado: mode invisible, rect ou anchor; page, x, y, width, height e anchor_text conforme o modo." }, "image": { "type": "string", "format": "binary", "description": "Imagem opcional de aparência, até 2 MB." } }, "required": [ "pdf", "certificate_id" ] }, "SignatureReplay": { "type": "object", "properties": { "replay": { "type": "boolean", "enum": [ true ] }, "signature": { "$ref": "#/components/schemas/SignatureDto" }, "message": { "type": "string" } }, "required": [ "replay", "signature" ] }, "SignatureResult": { "type": "object", "properties": { "signature": { "$ref": "#/components/schemas/SignatureDto" }, "subscription_status": { "type": "string" }, "signed_pdf_base64": { "type": "string", "format": "byte" } } }, "SigningLinks": { "type": "object", "properties": { "envelope_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "recipient_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "signing_url": { "type": "string", "format": "uri", "description": "Link privado com token no fragmento #. Não registrar em logs; entregar somente ao destinatário correspondente. Não substitui a confirmação por e-mail." } }, "required": [ "recipient_id", "name", "email", "signing_url" ] } } }, "required": [ "envelope_id", "expires_at", "recipients" ] }, "VerificationReport": { "type": "object", "properties": { "valid": { "type": "boolean" }, "signatureCount": { "type": "integer", "format": "int32" }, "fileSize": { "type": "integer", "format": "int64" }, "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureCheck" }, "nullable": true }, "warnings": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "additionalProperties": false }, "WebhookConfiguration": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "secret": { "type": "string" }, "signature_header": { "type": "string" }, "signature": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } }, "required": [ "url", "secret" ] }, "WebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "nullable": true }, "rotateSecret": { "type": "boolean", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "ApiKey": { "type": "http", "scheme": "bearer", "description": "Chave CLP da empresa, somente no servidor." } } }, "security": [ { "ApiKey": [] } ], "tags": [ { "name": "AccountEndpoints" }, { "name": "AdminEndpoints" }, { "name": "AiEndpoints" }, { "name": "AsaasWebhook" }, { "name": "CertificateEndpoints" }, { "name": "Clp.Assinatura.Api" }, { "name": "EnvelopeEndpoints" }, { "name": "PortalEndpoints" }, { "name": "PlatformSealEndpoints" }, { "name": "GooglePortalLogin" }, { "name": "PortalAuthEndpoints" }, { "name": "PublicEndpoints" }, { "name": "SignatureEndpoints" }, { "name": "VerifyEndpoints" } ], "servers": [ { "url": "https://api.clpsistemas.com.br", "description": "API publicada — uso sujeito à habilitação da conta" } ], "externalDocs": { "url": "https://clpsistemas.com.br/documentacao" } }