Siged
Agendar demonstração

API de integração

Seu sistema cria o envelope, envia os documentos, acompanha o andamento e baixa o resultado. Quando algo muda, o Siged avisa por webhook assinado.

URL base: https://api.siged.com.br/api/v1/public/integration/v1

Autenticação

Cada sistema de origem tem uma chave de API, criada pelo administrador da empresa no Siged (tela “Clientes de API”). Envie a chave em um destes cabeçalhos: 

Authorization: Bearer sgd_<id>_<segredo>
X-Api-Key: sgd_<id>_<segredo>

sgd_ + 16 caracteres hexadecimais (id público) + _ + 43 caracteres (segredo). Mostrada uma única vez ao criar ou rotacionar.

  • Use HTTPS sempre; nunca coloque a chave em URL, log ou código-fonte versionado.
  • O tenant (empresa) é o da chave — não existe parâmetro de empresa nas rotas.
  • Cada chave só usa as APIs liberadas para ela e, se houver lista de IPs, só aceita chamadas desses IPs.
  • Toda ação fica na linha do tempo do envelope como "Integração: <nome do sistema>".
  • Respostas de erro: { "status": 400, "code": "bad_request", "message": "..." }.

APIs liberadas por chave (escopos)

EscopoNomeO que permite
documents:send Envio de documentos Consultar os tipos de envelope publicados, criar envelope com participantes e enviar o arquivo de cada exigência.
documents:read Consulta de documentos Listar e consultar os envelopes criados por esta chave: situação, etapa, completude, documentos e pendências (sem PII).
documents:download Download de arquivos Baixar o arquivo de um documento dos envelopes criados por esta chave. Dado pessoal sensível: libere só se necessário. Imagem biométrica nunca sai pela API.

Fluxo básico

  1. Liste os tipos de envelope publicados para a sua chave (documentos exigidos, formatos e papéis dos participantes).
  2. Crie o envelope com os participantes. Com sendInvites, o Siged envia o link do portal por e-mail a cada pessoa.
  3. Envie os arquivos que você já tem. O que faltar o participante envia pelo portal.
  4. Acompanhe pela consulta do envelope ou receba os eventos por webhook.
  5. Na conclusão, baixe os arquivos (escopo próprio, com registro de cada acesso).

Rotas

Tipos de envelope publicados

GET /envelope-types

Fluxos que a chave pode usar na criação: papéis aceitos (mínimo/máximo) e documentos exigidos com formatos e tamanho.

Escopo
documents:send
Resposta
200 · application/json
Erros possíveis
401 unauthorized403 forbidden429 rate_limited
Exemplo de chamada
curl -X GET "https://api.siged.com.br/api/v1/public/integration/v1/envelope-types" \
  -H "X-Api-Key: <sua-chave>"
Exemplo de resposta
[
  {
    "code": "CONTA-PJ",
    "name": "Conta corrente PJ",
    "version": 1,
    "roles": [
      {
        "code": "REPRESENTANTE_LEGAL",
        "min": 1,
        "max": 2
      },
      {
        "code": "SOCIO",
        "min": 0,
        "max": null
      }
    ],
    "requirements": [
      {
        "code": "CONTRATO_SOCIAL",
        "name": "Contrato social",
        "documentTypeCode": "DOC_CONTRATO_SOCIAL",
        "scope": "ENVELOPE",
        "roles": [],
        "required": true,
        "formats": [
          "PDF"
        ],
        "maxSizeMb": 20
      },
      {
        "code": "DOC_IDENTIDADE",
        "name": "Documento de identidade",
        "documentTypeCode": "DOC_IDENTIDADE",
        "scope": "PER_PARTICIPANT",
        "roles": [
          "REPRESENTANTE_LEGAL",
          "SOCIO"
        ],
        "required": true,
        "formats": [
          "PDF",
          "JPG",
          "PNG"
        ],
        "maxSizeMb": 10
      }
    ]
  }
]

Criar envelope

POST /envelopes

Cria o envelope com os participantes (mesmas regras da tela: tipo publicado e ativo, papéis e quantidades, e-mail, CPF/CNPJ). Envie Idempotency-Key (até 120 caracteres) para repetir com segurança: mesma chave e mesmo corpo devolvem o mesmo envelope (cabeçalho Idempotent-Replayed: true); mesma chave com corpo diferente = 409. sendInvites=true faz o Siged enviar o link do portal por e-mail a cada participante.

Escopo
documents:send
Resposta
201 · application/json
Erros possíveis
400 bad_request401 unauthorized403 forbidden409 idempotency_conflict429 rate_limited
Exemplo de chamada
curl -X POST "https://api.siged.com.br/api/v1/public/integration/v1/envelopes" \
  -H "X-Api-Key: <sua-chave>" \
  -H "Idempotency-Key: PROP-2026-000123-v1" \
  -H "Content-Type: application/json" \
  -d '{"typeCode":"CONTA-PJ","title":"Padaria Exemplo LTDA","externalRef":"PROP-2026-000123","dueInDays":30,"sendInvites":true,"participants":[{"name":"Maria Exemplo","email":"[email protected]","documentNumber":"12345678901","roles":["REPRESENTANTE_LEGAL"]}]}'
Corpo da requisição
{
  "typeCode": "CONTA-PJ",
  "title": "Padaria Exemplo LTDA",
  "externalRef": "PROP-2026-000123",
  "dueInDays": 30,
  "sendInvites": true,
  "participants": [
    {
      "name": "Maria Exemplo",
      "email": "[email protected]",
      "documentNumber": "12345678901",
      "roles": [
        "REPRESENTANTE_LEGAL"
      ]
    }
  ]
}
Exemplo de resposta
{
  "id": "7d3c1f0e-2b4a-4c55-9e1f-0a9b8c7d6e5f",
  "protocol": "ENV-20261001-0042",
  "externalRef": "PROP-2026-000123",
  "title": "Padaria Exemplo LTDA",
  "typeCode": "CONTA-PJ",
  "typeVersion": 1,
  "status": "COLLECTING",
  "stage": {
    "key": "COLETA",
    "name": "Coleta de documentos",
    "kind": "COLLECT"
  },
  "completeness": {
    "state": "INCOMPLETE",
    "missing": 1,
    "pendingItems": [
      "Contrato social"
    ]
  },
  "dueAt": "2026-10-31T13:00:00Z",
  "createdAt": "2026-10-01T13:00:00Z",
  "updatedAt": "2026-10-01T13:00:00Z",
  "concludedAt": null,
  "canceledAt": null,
  "participants": [
    {
      "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
      "name": "Maria Exemplo",
      "roles": [
        "REPRESENTANTE_LEGAL"
      ],
      "documentNumberMasked": "***.456.789-**",
      "linkStatus": "SENT"
    }
  ],
  "documents": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "requirementCode": "CONTRATO_SOCIAL",
      "documentTypeCode": "DOC_CONTRATO_SOCIAL",
      "name": "Contrato social",
      "participantId": null,
      "required": true,
      "status": "EXPECTED",
      "version": 0,
      "rejectionReason": null,
      "formats": [
        "PDF"
      ],
      "maxSizeMb": 20,
      "acceptsUpload": true
    }
  ]
}

Enviar arquivo de um documento

POST /envelopes/{envelopeId}/documents/{documentId}/file

multipart/form-data com o campo "file" (PDF, JPG ou PNG conforme o documento; conteúdo conferido pelos bytes, SHA-256 calculado no servidor, arquivo idêntico à versão atual é recusado). Entra como nova versão com origem INTEGRACAO_API e segue para análise/curadoria pelo motor de etapas.

Escopo
documents:send
Resposta
200 · application/json
Erros possíveis
400 bad_request401 unauthorized403 forbidden404 not_found413 payload_too_large429 rate_limited
Exemplo de chamada
curl -X POST "https://api.siged.com.br/api/v1/public/integration/v1/envelopes/{envelopeId}/documents/{documentId}/file" \
  -H "X-Api-Key: <sua-chave>" \
  -F "[email protected]"
Exemplo de resposta
{
  "id": "7d3c1f0e-2b4a-4c55-9e1f-0a9b8c7d6e5f",
  "protocol": "ENV-20261001-0042",
  "externalRef": "PROP-2026-000123",
  "title": "Padaria Exemplo LTDA",
  "typeCode": "CONTA-PJ",
  "typeVersion": 1,
  "status": "IN_REVIEW",
  "stage": {
    "key": "CURADORIA",
    "name": "Curadoria",
    "kind": "PROCESS"
  },
  "completeness": {
    "state": "DOCS_COMPLETE",
    "missing": 0,
    "pendingItems": []
  },
  "dueAt": "2026-10-31T13:00:00Z",
  "createdAt": "2026-10-01T13:00:00Z",
  "updatedAt": "2026-10-01T13:05:00Z",
  "concludedAt": null,
  "canceledAt": null,
  "participants": [
    {
      "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
      "name": "Maria Exemplo",
      "roles": [
        "REPRESENTANTE_LEGAL"
      ],
      "documentNumberMasked": "***.456.789-**",
      "linkStatus": "SENT"
    }
  ],
  "documents": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "requirementCode": "CONTRATO_SOCIAL",
      "documentTypeCode": "DOC_CONTRATO_SOCIAL",
      "name": "Contrato social",
      "participantId": null,
      "required": true,
      "status": "IN_CURATION",
      "version": 1,
      "rejectionReason": null,
      "formats": [
        "PDF"
      ],
      "maxSizeMb": 20,
      "acceptsUpload": true
    }
  ]
}

Listar envelopes

GET /envelopes

Envelopes criados por esta chave, mais novos primeiro. Filtros: externalRef, status; page e pageSize (até 100).

Escopo
documents:read
Parâmetros de consulta
externalRefstatuspagepageSize
Resposta
200 · application/json
Erros possíveis
400 bad_request401 unauthorized403 forbidden429 rate_limited
Exemplo de chamada
curl -X GET "https://api.siged.com.br/api/v1/public/integration/v1/envelopes" \
  -H "X-Api-Key: <sua-chave>"
Exemplo de resposta
{
  "items": [
    {
      "id": "7d3c1f0e-2b4a-4c55-9e1f-0a9b8c7d6e5f",
      "protocol": "ENV-20261001-0042",
      "externalRef": "PROP-2026-000123",
      "title": "Padaria Exemplo LTDA",
      "typeCode": "CONTA-PJ",
      "typeVersion": 1,
      "status": "COLLECTING",
      "stage": {
        "key": "COLETA",
        "name": "Coleta de documentos",
        "kind": "COLLECT"
      },
      "completeness": {
        "state": "INCOMPLETE",
        "missing": 1,
        "pendingItems": [
          "Contrato social"
        ]
      },
      "dueAt": "2026-10-31T13:00:00Z",
      "createdAt": "2026-10-01T13:00:00Z",
      "updatedAt": "2026-10-01T13:00:00Z",
      "concludedAt": null,
      "canceledAt": null,
      "participants": [
        {
          "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
          "name": "Maria Exemplo",
          "roles": [
            "REPRESENTANTE_LEGAL"
          ],
          "documentNumberMasked": "***.456.789-**",
          "linkStatus": "SENT"
        }
      ],
      "documents": [
        {
          "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
          "requirementCode": "CONTRATO_SOCIAL",
          "documentTypeCode": "DOC_CONTRATO_SOCIAL",
          "name": "Contrato social",
          "participantId": null,
          "required": true,
          "status": "EXPECTED",
          "version": 0,
          "rejectionReason": null,
          "formats": [
            "PDF"
          ],
          "maxSizeMb": 20,
          "acceptsUpload": true
        }
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

Consultar envelope

GET /envelopes/{envelopeId}

Situação, etapa, completude (o que falta), participantes (CPF/CNPJ mascarado) e situação de cada documento, com o motivo da reprovação quando houver.

Escopo
documents:read
Resposta
200 · application/json
Erros possíveis
401 unauthorized403 forbidden404 not_found429 rate_limited
Exemplo de chamada
curl -X GET "https://api.siged.com.br/api/v1/public/integration/v1/envelopes/{envelopeId}" \
  -H "X-Api-Key: <sua-chave>"
Exemplo de resposta
{
  "id": "7d3c1f0e-2b4a-4c55-9e1f-0a9b8c7d6e5f",
  "protocol": "ENV-20261001-0042",
  "externalRef": "PROP-2026-000123",
  "title": "Padaria Exemplo LTDA",
  "typeCode": "CONTA-PJ",
  "typeVersion": 1,
  "status": "COLLECTING",
  "stage": {
    "key": "COLETA",
    "name": "Coleta de documentos",
    "kind": "COLLECT"
  },
  "completeness": {
    "state": "INCOMPLETE",
    "missing": 1,
    "pendingItems": [
      "Contrato social"
    ]
  },
  "dueAt": "2026-10-31T13:00:00Z",
  "createdAt": "2026-10-01T13:00:00Z",
  "updatedAt": "2026-10-01T13:00:00Z",
  "concludedAt": null,
  "canceledAt": null,
  "participants": [
    {
      "id": "9f8e7d6c-5b4a-4392-8170-6f5e4d3c2b1a",
      "name": "Maria Exemplo",
      "roles": [
        "REPRESENTANTE_LEGAL"
      ],
      "documentNumberMasked": "***.456.789-**",
      "linkStatus": "SENT"
    }
  ],
  "documents": [
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "requirementCode": "CONTRATO_SOCIAL",
      "documentTypeCode": "DOC_CONTRATO_SOCIAL",
      "name": "Contrato social",
      "participantId": null,
      "required": true,
      "status": "EXPECTED",
      "version": 0,
      "rejectionReason": null,
      "formats": [
        "PDF"
      ],
      "maxSizeMb": 20,
      "acceptsUpload": true
    }
  ]
}

Baixar arquivo de um documento

GET /envelopes/{envelopeId}/documents/{documentId}/file

Devolve o arquivo da versão atual (ou de ?version=N). Escopo próprio por ser dado pessoal; cada download fica registrado na linha do tempo do envelope. Imagem biométrica (selfie) nunca sai pela API.

Escopo
documents:download
Parâmetros de consulta
version
Resposta
200 · application/pdf | image/jpeg | image/png
Erros possíveis
401 unauthorized403 forbidden404 not_found410 gone429 rate_limited
Exemplo de chamada
curl -X GET "https://api.siged.com.br/api/v1/public/integration/v1/envelopes/{envelopeId}/documents/{documentId}/file" \
  -H "X-Api-Key: <sua-chave>"

Erros e limites

As respostas de erro seguem { "status": 400, "code": "bad_request", "message": "..." }.

StatusCódigoQuando
400 bad_request Corpo/arquivo inválido ou regra de negócio recusada (a mensagem diz o motivo; nada é gravado).
401 unauthorized Chave ausente, inválida, revogada ou expirada (resposta sempre igual — não revela se a chave existe).
403 forbidden A chave não tem a API liberada (escopo) ou o IP de origem não está na lista permitida.
404 not_found Envelope/documento inexistente ou não criado por esta chave.
409 idempotency_conflict A mesma Idempotency-Key foi usada com um corpo diferente.
410 gone O arquivo da versão foi descartado pela política de retenção ou eliminado a pedido do titular (LGPD).
413 payload_too_large Requisição acima do limite (30 MB).
429 rate_limited Limite de requisições da chave (ou de tentativas inválidas do IP) excedido; respeite o Retry-After.