{"openapi":"3.0.3","info":{"title":"Sign Your Own Docs API","version":"1.0.0","description":"Documentação interativa oficial da API REST da plataforma Sign Your Own Docs. Permite criação, acompanhamento, assinatura eletrônica e ICP-Brasil, download de documentos, gestão de webhooks transacionais e credenciais de acesso.","contact":{"name":"Suporte à Integração","url":"https://www.signyourouwndocs.com.br/docs"}},"servers":[{"url":"https://www.signyourouwndocs.com.br","description":"Servidor da Aplicação"}],"tags":[{"name":"Auth","description":"Autenticação de usuários, criação de contas e gerenciamento de sessões web."},{"name":"Requests","description":"Operações de ciclo de vida, consulta e cancelamento de solicitações de assinatura."},{"name":"Documents","description":"Recuperação e download seguro de arquivos PDF assinados."},{"name":"Signers","description":"Geração e recuperação de links individuais de assinatura."},{"name":"Webhooks","description":"Gerenciamento de destinos HTTPS, rotação de segredos HMAC e auditoria de eventos."},{"name":"Credentials","description":"Administração de chaves de API para autenticação Bearer."},{"name":"Deletions","description":"Controle de exclusão ativa de dados e conformidade com retenção de snapshots."}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key (syd_live_*)","description":"Chave de API do integrador gerada no painel de configurações."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR","description":"Código de máquina padronizado do erro."},"message":{"type":"string","example":"Descrição amigável do erro ocorrido."},"details":{"type":"object","description":"Detalhes adicionais de validação por campo."}},"required":["code","message"]}},"required":["error"]},"SignerInput":{"type":"object","properties":{"name":{"type":"string","example":"Alice Silva"},"email":{"type":"string","format":"email","example":"alice@empresa.com"},"position":{"type":"integer","nullable":true,"example":1,"description":"Posição obrigatória e sequencial (1..N) se ordering for sequential."}},"required":["name","email"]},"CreateRequestMetadata":{"type":"object","properties":{"reference":{"type":"string","example":"CONTRATO-2026-001"},"mode":{"type":"string","enum":["electronic","icp_brasil"],"default":"electronic","description":"Modalidade da assinatura."},"ordering":{"type":"string","enum":["any","sequential"],"default":"any","description":"Ordem de assinatura (livre ou sequencial estrita)."},"delivery":{"type":"string","enum":["email","integrator"],"default":"email","description":"Método de entrega do link individual."},"geolocationRequirement":{"type":"string","enum":["optional","required"],"default":"optional","description":"Obrigatoriedade da coleta de geolocalização do dispositivo (FR-005)."},"webhookEndpointId":{"type":"string","format":"uuid","nullable":true,"description":"ID do endpoint de webhook específico desta organização para receber notificações deste envelope."},"webhookUrl":{"type":"string","format":"uri","nullable":true,"description":"URL de webhook HTTPS dinâmica para receber notificações deste envelope."},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerInput"},"description":"Lista de 1 até 20 signatários."}},"required":["signers"]},"SignerResponseItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"position":{"type":"integer","nullable":true},"status":{"type":"string","enum":["pending","signed","declined"]},"access_url":{"type":"string","format":"uri"},"signedAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true},"declineReason":{"type":"string","nullable":true},"evidences":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string"},"ipAddress":{"type":"string","nullable":true},"selfieUrl":{"type":"string","format":"uri","nullable":true},"selfieHash":{"type":"string","nullable":true},"location":{"type":"object","properties":{"provided":{"type":"boolean"},"latitude":{"type":"number","nullable":true},"longitude":{"type":"number","nullable":true},"accuracy":{"type":"number","nullable":true}}},"occurredAt":{"type":"string","format":"date-time"}}}}}},"RequestDetail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"externalReference":{"type":"string","nullable":true},"mode":{"type":"string","enum":["electronic","icp_brasil"]},"ordering":{"type":"string","enum":["any","sequential"]},"geolocationRequirement":{"type":"string","enum":["optional","required"]},"status":{"type":"string","enum":["pending","completed","declined","cancelled"]},"version":{"type":"integer"},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerResponseItem"}},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"cancelledAt":{"type":"string","format":"date-time","nullable":true},"declinedAt":{"type":"string","format":"date-time","nullable":true}}},"WebhookEndpointConfig":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri","example":"https://api.empresa.com/webhooks"},"status":{"type":"string","enum":["active","disabled"]},"secret":{"type":"string","description":"Segredo HMAC gerado (exibido apenas na criação)."},"previousSecretValidUntil":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"CredentialItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"keyPrefix":{"type":"string","example":"syd_live_1234"},"apiKey":{"type":"string","description":"Chave secreta completa gerada (exibida apenas na criação)."},"revokedAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"}}},"DeletionResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"requestId":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","processing","completed","failed"]},"backupRetentionPolicy":{"type":"string","example":"Remoção ativa imediata. Backups em snapshot expiram em 30 dias."},"requestedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true}}}}},"security":[{"BearerAuth":[]}],"paths":{"/api/v1/auth/register":{"post":{"tags":["Auth"],"summary":"Cadastrar novo usuário e conta pessoal","description":"Cria uma conta de usuário com isolamento de tenant próprio e inicia sessão web com cookie assinado.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"example":"Maria Silva"},"email":{"type":"string","format":"email","example":"maria@exemplo.com"},"password":{"type":"string","minLength":8,"example":"SenhaSegura123!"}},"required":["name","email","password"]}}}},"responses":{"201":{"description":"Usuário cadastrado com sucesso e sessão iniciada.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"integratorId":{"type":"string","format":"uuid"},"role":{"type":"string"}}}}}}}},"400":{"description":"E-mail já existente ou erro de validação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/auth/login":{"post":{"tags":["Auth"],"summary":"Autenticar usuário existente","description":"Valida credenciais e inicia sessão com cookie syd_session.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","example":"maria@exemplo.com"},"password":{"type":"string","example":"SenhaSegura123!"}},"required":["email","password"]}}}},"responses":{"200":{"description":"Autenticação bem-sucedida.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"integratorId":{"type":"string","format":"uuid"},"role":{"type":"string"}}}}}}}},"401":{"description":"Credenciais inválidas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/auth/logout":{"post":{"tags":["Auth"],"summary":"Encerrar sessão ativa","description":"Invalida e remove o cookie syd_session da sessão.","responses":{"200":{"description":"Sessão encerrada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}}}}},"/api/v1/auth/me":{"get":{"tags":["Auth"],"summary":"Obter dados do usuário ativo","description":"Retorna informações do usuário autenticado pela sessão web ou pela chave Bearer.","responses":{"200":{"description":"Dados do usuário autenticado.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"integratorId":{"type":"string"},"role":{"type":"string"}}}}}}}},"401":{"description":"Não autenticado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/account":{"get":{"tags":["Auth"],"summary":"Consultar dados consolidados de Minha Conta","description":"Retorna informações completas de perfil, identificação da organização e datas cadastrais do usuário autenticado.","responses":{"200":{"description":"Dados da conta recuperados com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"Maria Silva"},"email":{"type":"string","format":"email","example":"maria@empresa.com"},"role":{"type":"string","enum":["admin","operator"],"example":"operator"},"integratorId":{"type":"string","format":"uuid"},"integratorName":{"type":"string","example":"Acme Ltda"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Não autenticado ou sessão expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/account/profile":{"patch":{"tags":["Auth"],"summary":"Atualizar dados cadastrais do usuário","description":"Permite ao usuário autenticado alterar seu nome de exibição e/ou endereço de e-mail.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":100,"example":"Maria Santos Silva"},"email":{"type":"string","format":"email","example":"maria.santos@empresa.com"}}}}}},"responses":{"200":{"description":"Perfil atualizado com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Perfil atualizado com sucesso."},"user":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"email":{"type":"string","format":"email"},"role":{"type":"string"},"integratorName":{"type":"string"}}}}}}}},"400":{"description":"Dados de entrada inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autenticado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Endereço de e-mail já cadastrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/account/change-password":{"post":{"tags":["Auth"],"summary":"Alterar senha de acesso do usuário","description":"Atualiza com segurança a credencial de senha do usuário autenticado mediante confirmação da senha atual.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"currentPassword":{"type":"string","example":"SenhaAtual123!"},"newPassword":{"type":"string","minLength":8,"example":"NovaSenhaSegura456#"}},"required":["currentPassword","newPassword"]}}}},"responses":{"200":{"description":"Senha alterada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"message":{"type":"string","example":"Senha alterada com sucesso."}}}}}},"400":{"description":"Senha atual incorreta ou nova senha inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Não autenticado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/requests":{"post":{"tags":["Requests"],"summary":"Criar envelope de assinatura","description":"Cria um envelope de assinatura contendo de 1 a 10 documentos PDF acompanhados de metadados JSON. Cada envelope consome estritamente 1 cota de envio.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"},"description":"Chave única de idempotência do integrador para evitar duplicidades."}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Arquivo original para envelopes de documento único (formatos aceitos: PDF, Word .doc/.docx, Imagens .jpg/.jpeg/.png, máx. 20 MiB)."},"files":{"type":"array","items":{"type":"string","format":"binary"},"description":"Múltiplos arquivos do envelope (PDF, Word .doc/.docx, Imagens .jpg/.jpeg/.png - até 10 documentos, máx. 50 MB no total)."},"metadata":{"type":"string","description":"String JSON conforme o esquema CreateRequestMetadata."}},"required":["metadata"]}}}},"responses":{"201":{"description":"Solicitação criada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDetail"}}}},"400":{"description":"Validação falhou (PDF inválido ou metadados incorretos).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Credencial Bearer inválida ou revogada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"Franquia de documentos do plano esgotada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Acesso à API restrito ou limite de 2 envios em sandbox no plano gratuito atingido (API_ACCESS_REQUIRED). Requer Plano Básico / Dev.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflito: Chave de idempotência reutilizada com payload divergente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Arquivo excede o limite máximo configurado de 20 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Requests"],"summary":"Listar solicitações de assinatura","description":"Retorna a lista das solicitações de assinatura do integrador autenticado.","responses":{"200":{"description":"Lista de solicitações retornada com sucesso.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RequestDetail"}}}}}}},"401":{"description":"Não autorizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/requests/{id}":{"get":{"tags":["Requests"],"summary":"Consultar detalhes da solicitação","description":"Obtém dados detalhados da solicitação, seus signatários e status atual.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"UUID da solicitação."}],"responses":{"200":{"description":"Dados da solicitação.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestDetail"}}}},"404":{"description":"Solicitação não encontrada ou pertencente a outro integrador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Requests"],"summary":"Solicitar exclusão definitiva da solicitação","description":"Agenda a exclusão de arquivos e evidências de uma solicitação encerrada (completed, declined ou cancelled). Retorna 409 se ainda estiver pending.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Exclusão agendada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletionResponse"}}}},"409":{"description":"Documento ainda pendente (cancele antes de excluir).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/requests/{id}/cancel":{"post":{"tags":["Requests"],"summary":"Cancelar solicitação pendente","description":"Cancela imediatamente uma solicitação em andamento e invalida os links dos signatários.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Solicitação cancelada.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","example":"cancelled"},"cancelledAt":{"type":"string","format":"date-time"}}}}}},"409":{"description":"Solicitação já finalizada ou em estado terminal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/requests/{id}/document":{"get":{"tags":["Documents"],"summary":"Baixar PDF assinado ou em andamento","description":"Recupera o PDF da solicitação. Se a solicitação estiver concluída, retorna a versão final. Se estiver em andamento (pending), retorna a versão intermediária mais recente contendo as assinaturas acumuladas. Aceita autenticação via Bearer token, cookie de sessão ou parâmetro token na URL.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"token","in":"query","required":false,"schema":{"type":"string"},"description":"Token de acesso público do signatário (permite download direto pelo navegador sem credenciais de integrador)"}],"responses":{"200":{"description":"Fluxo binário do PDF (versão final ou intermediária mais recente).","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"description":"Sessão ou token de acesso não fornecido ou inválido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Solicitação ou arquivo não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/requests/{id}/signers/{signerId}/access":{"get":{"tags":["Signers"],"summary":"Obter link individual de assinatura","description":"Retorna o link seguro para entrega do signatário pelo próprio integrador.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"signerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Link individual gerado.","content":{"application/json":{"schema":{"type":"object","properties":{"signer_id":{"type":"string"},"signer_name":{"type":"string"},"access_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/requests/{id}/signers/{signerId}/selfie":{"get":{"tags":["Signers"],"summary":"Obter imagem da selfie de comprovação de identidade","description":"Recupera o arquivo de imagem da selfie capturada pelo signatário.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"signerId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Imagem da selfie.","content":{"image/jpeg":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"Selfie ou solicitação não encontrada."}}}},"/api/v1/requests/{id}/events":{"get":{"tags":["Webhooks"],"summary":"Consultar histórico de eventos e entregas","description":"Histórico de eventos outbox e tentativas de entrega de webhooks desta solicitação.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Lista de eventos e entregas retornada."}}}},"/api/v1/webhook-endpoints":{"get":{"tags":["Webhooks"],"summary":"Listar endpoints de webhooks (1:N)","description":"Retorna a lista de todos os endpoints de webhook cadastrados para a organização.","responses":{"200":{"description":"Lista de webhooks cadastrados retornada."}}},"post":{"tags":["Webhooks"],"summary":"Cadastrar novo webhook de integração","description":"Cadastra um novo destino HTTPS com nome amigável e gera segredo HMAC individual.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"SAP ERP"},"url":{"type":"string","format":"uri"},"isDefault":{"type":"boolean","default":false}},"required":["url"]}}}},"responses":{"201":{"description":"Webhook cadastrado com sucesso. Retorna o segredo HMAC gerado."}}}},"/api/v1/webhook-endpoint":{"get":{"tags":["Webhooks"],"summary":"Consultar destino de webhook","description":"Retorna a URL e status do destino de webhook cadastrado para o integrador.","responses":{"200":{"description":"Configuração atual do destino.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointConfig"}}}}}},"put":{"tags":["Webhooks"],"summary":"Configurar destino de webhook HTTPS","description":"Cadastra ou atualiza o endpoint HTTPS. Retorna o segredo de assinatura HMAC na criação.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}},"required":["url"]}}}},"responses":{"200":{"description":"Destino configurado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointConfig"}}}}}}},"/api/v1/webhook-endpoint/rotate-secret":{"post":{"tags":["Webhooks"],"summary":"Rotacionar segredo de assinatura do webhook","description":"Gera novo segredo HMAC-SHA256 e mantém o segredo anterior válido por 24 horas para transição segura.","responses":{"200":{"description":"Novo segredo gerado.","content":{"application/json":{"schema":{"type":"object","properties":{"newSecret":{"type":"string"},"previousSecretValidUntil":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/credentials":{"get":{"tags":["Credentials"],"summary":"Listar chaves de API","description":"Lista todas as credenciais do integrador com prefixo e status de revogação.","responses":{"200":{"description":"Lista de credenciais.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CredentialItem"}}}}}}}}},"post":{"tags":["Credentials"],"summary":"Gerar nova chave de API","description":"Cria nova chave Bearer exibida uma única vez.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","example":"Backend Produção"}}}}}},"responses":{"201":{"description":"Chave de API gerada com sucesso.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CredentialItem"}}}}}}},"/api/v1/credentials/{id}/revoke":{"post":{"tags":["Credentials"],"summary":"Revogar chave de API","description":"Revoga imediatamente uma chave de API.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Credencial revogada com sucesso."}}}},"/api/v1/deletions/{id}":{"get":{"tags":["Deletions"],"summary":"Consultar progresso da exclusão","description":"Retorna o estado da exclusão ativa e informa a política de expiração de snapshots e backups.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status da solicitação de exclusão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletionResponse"}}}}}}}}}