Endpoints da API

Esta seção detalha os endpoints principais da API Rubrix, organizados por módulo.

Autenticação

Login

POST /auth/login

Autentica um usuário e retorna um token JWT.

Corpo da Requisição (JSON):

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail do usuário.
password	string	Sim	Senha do usuário.
tenant_id	uuid	Não	ID do tenant. Necessário se o usuário pertence a mais de um tenant.

Exemplo de Request:

{
  "email": "usuario@empresa.com",
  "password": "minha-senha"
}

Resposta (200 OK):

{
  "token": "eyJ0eXAiOiJKV1Qi...",
  "user": {
    "id": 42,
    "name": "Fulano de Tal",
    "email": "usuario@empresa.com"
  },
  "tenants": [
    {
      "id": "27192214-56d9-46f0-96f4-868c49b8cf4e",
      "company_name": "Empresa X",
      "role": "OWNER"
    }
  ],
  "selected_tenant_id": "27192214-56d9-46f0-96f4-868c49b8cf4e",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOi...",
  "refresh_expires_in": 2592000,
  "upload_limits": {
    "file_size_limit_bytes": 52428800,
    "tenant_unlimited": false
  }
}

Campo	Tipo	Descrição
token	string	JWT de autenticação. Enviar em Authorization: Bearer {token}.
user	object	Dados do usuário autenticado (id, name, email).
tenants	array	Tenants aos quais o usuário pertence (id, company_name, role).
selected_tenant_id	uuid	Tenant ativo do token. Use POST /auth/switch-tenant para alternar.
expires_in	integer	Tempo de expiração do token em segundos.
refresh_token	string	Refresh token para renovação silenciosa do JWT.
refresh_expires_in	integer	Tempo de expiração do refresh token em segundos.
upload_limits	object	Limites de upload do plano do tenant: file_size_limit_bytes (nullable) e tenant_unlimited. file_size_limit_bytes nulo com tenant_unlimited=false significa “usar o limite global”.

Códigos de Erro:

• 400 Bad Request — Credenciais inválidas.

Informações do Usuário Autenticado

GET /auth/me

Retorna informações do usuário autenticado, a lista de tenants aos quais pertence e, quando a chamada é feita com API Key, metadados da credencial utilizada.

Autenticação: Bearer Token ou API Key.

Resposta (200 OK):

{
  "user": {
    "id": 42,
    "name": "Fulano de Tal",
    "email": "usuario@empresa.com"
  },
  "tenants": [
    {
      "id": "27192214-56d9-46f0-96f4-868c49b8cf4e",
      "company_name": "Empresa X",
      "role": "OWNER"
    }
  ],
  "current_tenant_id": "27192214-56d9-46f0-96f4-868c49b8cf4e",
  "credential": {
    "api_key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "BACKEND",
    "scopes": ["SIGN", "VERIFY"]
  },
  "upload_limits": {
    "file_size_limit_bytes": 52428800,
    "tenant_unlimited": false
  }
}

Campo	Tipo	Descrição
user	object	Dados do usuário autenticado (id, name, email).
tenants	array	Tenants aos quais o usuário pertence (id, company_name, role).
current_tenant_id	uuid	Tenant ativo no token/credencial da chamada.
credential	object	Presente apenas em chamadas via API Key: api_key_id, platform e scopes.
upload_limits	object	Limites de upload do plano do tenant (ver /auth/login).

Trocar Tenant Ativo

POST /auth/switch-tenant

Troca o tenant ativo e retorna um novo JWT vinculado ao tenant selecionado.

Autenticação: Bearer Token ou API Key.

Corpo da Requisição (JSON):

Campo	Tipo	Obrigatório	Descrição
tenant_id	uuid	Sim	ID do tenant para o qual deseja trocar.

Exemplo de Request:

{
  "tenant_id": "27192214-56d9-46f0-96f4-868c49b8cf4e"
}

Respostas:

• 200 OK — Novo JWT retornado.

• 400 Bad Request — Tenant inválido ou sem acesso.

API Keys

Criar API Key

POST /api-keys

Cria uma nova API Key para o tenant autenticado. API Keys são ideais para integrações de aplicação.

Autenticação: Bearer Token ou API Key.

Corpo da Requisição (JSON):

Campo	Tipo	Obrigatório	Descrição
name	string	Sim	Nome identificador da API Key.
expires_at	datetime	Não	Data de expiração (formato ISO 8601). Se omitido, a chave não expira.

Exemplo de Request:

{
  "name": "integracao-erp",
  "expires_at": "2027-12-31T23:59:59Z"
}

Resposta (201 Created):

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "integracao-erp",
  "raw_key": "rbx_live_...",
  "key_prefix": "rbx_live_abc",
  "role": "CLIENT",
  "platform": "BACKEND",
  "scopes": ["SIGN", "VERIFY"],
  "expires_at": "2027-12-31T23:59:59Z",
  "created_at": "2026-10-08T14:30:00Z"
}

Campo	Tipo	Descrição
id	uuid	Identificador da API Key.
name	string	Nome informado na criação.
raw_key	string	Valor completo da API Key. Enviado em X-Api-Key ou Authorization: Bearer.
key_prefix	string	Prefixo exibível para identificar a chave em listagens.
role	string	Papel associado à chave.
platform	string	Plataforma da integração.
scopes	array	Escopos autorizados.
expires_at	datetime	Data de expiração (nulo se não expira).
created_at	datetime	Data de criação.

Códigos de Erro:

• 400 Bad Request — Dados inválidos.

Warning

Guarde o valor de raw_key retornado. Ele não será exibido novamente.

Listar API Keys

GET /api-keys

Sem parâmetros, lista todas as API Keys do tenant autenticado no formato legado. Quando ao menos um dos parâmetros page, pageSize ou search é enviado, ativa o modo paginado.

Autenticação: Bearer Token ou API Key.

Parâmetros de Query (modo paginado):

• page (inteiro, opcional) — Índice da página, começando em 0. Padrão: 0.

• pageSize (inteiro, opcional) — Itens por página, entre 1 e 100. Padrão: 20.

• search (string, opcional) — Busca por nome, prefixo, papel, plataforma, escopo ou status derivado (ACTIVE, EXPIRED e REVOKED).

A ordenação é estável por criação e ID, ambos decrescentes. Se page estiver acima da última página disponível, a resposta usa o último índice válido.

Respostas:

• 200 OK — Lista de API Keys no formato correspondente ao modo solicitado.

Resposta legada (sem parâmetros):

{
  "items": []
}

Resposta paginada:

{
  "items": [],
  "total": 137,
  "page": 0,
  "pageSize": 20,
  "summary": {
    "total": 184,
    "active": 120,
    "expiringSoon": 7
  }
}

total considera a busca atual. summary sempre representa todas as chaves do tenant; expiringSoon considera chaves ativas que expiram nos próximos sete dias.

Revogar API Key

DELETE /api-keys/{id}

Revoga uma API Key existente.

Autenticação: Bearer Token ou API Key.

Parâmetros de Path:

• id (uuid, obrigatório) — ID da API Key a ser revogada.

Respostas:

• 204 No Content — API Key revogada.

Fluxo de Assinatura (Flow)

Iniciar Fluxo

POST /flow/init

Inicia um novo fluxo de assinatura. A requisição é enviada como multipart/form-data: o PDF é enviado como arquivo binário no campo file e a lista de pools é serializada como JSON no campo pools (texto). A API realiza o upload seguro para o storage, persiste a estrutura do fluxo e dispara automaticamente o convite por e-mail para os signatários do primeiro pool.

Autenticação: Bearer Token ou API Key.

Content-Type: multipart/form-data.

Campos do Multipart Form:

Campo	Tipo	Obrigatório	Descrição
file	binary	Sim	Arquivo PDF a ser assinado (upload binário).
pools	string (JSON)	Sim	Lista de pools de signatários serializada como JSON. Veja a estrutura abaixo. Usa nomes em snake_case.
webhook	string	Não	URL para callback de finalização. Ao concluir todas as assinaturas, a API envia o documento final via POST para esta URL.
fileName	string	Não	Nome customizado do arquivo. Quando omitido, usa o nome original do upload.
expiresAt	string (ISO-8601)	Não	Data/hora de expiração do fluxo (ex.: 2026-12-31T23:59:59Z).
signaturePackaging	string	Não	Modo de assinatura do fluxo: ATTACHED (padrão, pode ser omitido) ou DETACHED. Em DETACHED o documento original nunca é alterado e as assinaturas de todos os signatários se acumulam num único CAdES (.p7s), co-assinado a cada passo. O modo vale para o fluxo inteiro e não pode ser alterado depois — /flow/sign não aceita este campo. Arquivos XML são recusados com 400 neste modo.

Estrutura de um Pool:

Campo	Tipo	Obrigatório	Descrição
priority	integer	Não	Ordem de assinatura. Pools com menor valor assinam primeiro. Pools com mesmo priority assinam em paralelo.
quorum_required	integer	Não	Número mínimo de assinaturas necessárias neste pool. Se omitido, todos devem assinar.
alias	string	Não	Nome descritivo para o pool (ex: "Jurídico").
config	object	Não	Restrições de assinatura aplicadas a todo o pool. Veja SignatureConfig.
signers	array	Sim	Lista de signatários do pool (mínimo 1).

Estrutura de um Signer:

Campo	Tipo	Obrigatório	Descrição
email	string	Sim	E-mail para notificação do signatário.
document	string	Sim	CPF ou CNPJ do signatário.
phone	string	Não	Telefone do signatário.
config	object	Não	Restrições de assinatura específicas deste signatário. Sobrescreve o config do pool. Veja SignatureConfig.

Estrutura de SignatureConfig:

Campo	Tipo	Descrição
allowed_signatures	array	Tipos de assinatura permitidos: QUALIFIED, ADVANCED, SIMPLE.
allowed_profile_types	array	Perfis de política permitidos: B-B, B-T, B-LT, B-LTA.
allowed_providers	array	Provedores permitidos. Valores aceitos (enum ProviderName): INTEGRAICP, PIXSIGN, GOLDID, SAFEWEB, SERPRO, SOCIALID, MOCKPROVIDERQUALIFICADO, MOCKPROVIDERAVANCADO.

Exemplo de Request (multipart/form-data):

POST /flow/init HTTP/1.1
Content-Type: multipart/form-data; boundary=----BOUNDARY
Authorization: Bearer {token}

------BOUNDARY
Content-Disposition: form-data; name="file"; filename="contrato_servicos.pdf"
Content-Type: application/pdf

<binário do PDF>
------BOUNDARY
Content-Disposition: form-data; name="pools"

[
  {
    "alias": "Jurídico",
    "priority": 1,
    "signers": [
      { "email": "advogado@empresa.com", "document": "12345678900" }
    ]
  },
  {
    "alias": "Diretoria",
    "priority": 2,
    "signers": [
      { "email": "diretor@empresa.com", "document": "98765432100" }
    ]
  }
]
------BOUNDARY
Content-Disposition: form-data; name="webhook"

https://api.suaempresa.com/callback
------BOUNDARY
Content-Disposition: form-data; name="signaturePackaging"

ATTACHED
------BOUNDARY--

Resposta (201 Created):

{
  "flowId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "WAITING",
  "currentSigners": [
    {
      "identifier": "12345678900",
      "email": "advogado@empresa.com",
      "signUrl": "https://rubrix.lat/sign/..."
    }
  ]
}

Códigos de Erro:

• 400 Bad Request — PDF corrompido, JSON de pools inválido ou dados faltando.

• 500 Internal Server Error — Falha ao persistir dados ou salvar no storage.

• 502 Bad Gateway — Falha no serviço de e-mail.

Consultar Status do Fluxo

GET /flow/status/{flow_id}

Retorna o estado atual do fluxo, os documentos dos signatários pendentes e uma URL temporária para cada arquivo que compõe o fluxo.

Autenticação: Bearer Token ou API Key.

Parâmetros de Path:

• flow_id (uuid, obrigatório) — Identificador do fluxo.

Resposta (200 OK) — fluxo ATTACHED:

{
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "WAITING",
  "signature_packaging": "ATTACHED",
  "current_signers": ["12345678900"],
  "documents": [
    {
      "type": "ORIGINAL",
      "url": "https://s3.rubrix.local/temp-url...",
      "file_name": "contrato.pdf",
      "mime_type": "application/pdf"
    }
  ]
}

Resposta (200 OK) — fluxo DETACHED após a primeira assinatura:

{
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "SIGNED",
  "signature_packaging": "DETACHED",
  "current_signers": [],
  "documents": [
    {
      "type": "ORIGINAL",
      "url": "https://s3.rubrix.local/temp-url...",
      "file_name": "contrato.pdf",
      "mime_type": "application/pdf"
    },
    {
      "type": "CMS",
      "url": "https://s3.rubrix.local/temp-url...",
      "file_name": "contrato.pdf.p7s",
      "mime_type": "application/pkcs7-signature"
    }
  ]
}

Campo	Tipo	Descrição
flow_id	string	Identificador do fluxo.
status	string	Status atual: CREATED, WAITING ou SIGNED.
signature_packaging	string	Modo de assinatura definido no /flow/init: ATTACHED ou DETACHED. Sempre retornado.
current_signers	array	CPF/CNPJ dos signatários do pool atual (quando status é WAITING).
documents	array	Arquivos do fluxo. Sempre contém o item ORIGINAL; o item CMS aparece apenas em fluxo DETACHED, a partir da primeira assinatura.

Estrutura de um item de documents:

Campo	Tipo	Descrição
type	string	ORIGINAL para o documento enviado no /flow/init; CMS para o CAdES (.p7s) com as assinaturas acumuladas.
url	string	URL temporária para download/visualização do arquivo.
file_name	string	Nome do arquivo.
mime_type	string	MIME type do arquivo: application/pdf, application/xml, application/pkcs7-signature ou application/octet-stream quando o original de um fluxo DETACHED não é PDF nem XML.

Códigos de Erro:

• 404 Not Found — Fluxo não encontrado.

• 500 Internal Server Error — Erro interno.

Assinar no Fluxo

POST /flow/sign

Aplica a assinatura de um participante em um fluxo ativo.

O modo de assinatura vem do fluxo, definido no /flow/init: este endpoint não aceita o campo signaturePackaging.

Autenticação: Bearer Token ou API Key.

Corpo da Requisição (JSON):

Campo	Tipo	Obrigatório	Descrição
flowId	uuid	Sim	ID do fluxo.
sessionId	string	Sim	ID da sessão obtida após autenticação no provedor.
stampData	object	Condicional	Posicionamento visual da assinatura (somente PDF). Obrigatório em fluxo ATTACHED de PDF e opcional em XML. Em fluxo DETACHED é rejeitado com 400 (STAMP_NOT_ALLOWED_FOR_DETACHED): CAdES não embute carimbo visual e o documento original não é alterado.
policyProfile	string	Não	Perfil da assinatura: B-B, B-T, B-LT ou B-LTA.
xmlXpath	string	Não	XPath para posicionamento em documentos XML.

Estrutura de StampData:

As coordenadas x e y são pontos PDF no sistema visual da página renderizada: origem no canto superior esquerdo da área visível, x para a direita e y para baixo. O backend ajusta valores finitos fora dos limites para evitar que o carimbo seja cortado.

Campo	Tipo	Descrição
pageNumber	integer	Número da página (deve ser > 0).
x	float	Coordenada X visual, em pontos PDF, a partir do canto superior esquerdo.
y	float	Coordenada Y visual, em pontos PDF, a partir do canto superior esquerdo.

Exemplo de Request:

{
  "flowId": "550e8400-e29b-41d4-a716-446655440000",
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "stampData": {
    "pageNumber": 1,
    "x": 100.0,
    "y": 120.0
  },
  "policyProfile": "B-T"
}

Respostas:

• 200 OK (fluxo ATTACHED) — Documento assinado, application/pdf ou application/xml.

• 200 OK (fluxo DETACHED) — Apenas o CAdES atualizado, application/pkcs7-signature, com Content-Disposition: attachment; filename="<nome-original>.p7s". O .p7s traz as assinaturas acumuladas até agora — a deste signatário e as dos anteriores, co-assinadas no mesmo CMS. O documento original não é alterado e continua disponível em /flow/status.

• 400 Bad Request — Dados inválidos, ou stampData enviado em fluxo DETACHED.

Webhook de Finalização

Quando todas as assinaturas de um fluxo são concluídas, a API envia automaticamente um POST para a URL de webhook configurada no /flow/init.

Detalhe	Descrição
Método	POST
Header	X-Flow-Id: {flowId}
Content-Type	Depende do modo do fluxo — veja abaixo.
Body	Depende do modo do fluxo — veja abaixo.

O corpo do POST varia conforme o signaturePackaging definido no /flow/init:

Modo	Content-Type	Body
ATTACHED	application/pdf ou application/xml	Binário do arquivo assinado.
DETACHED	application/zip	ZIP com dois arquivos: o documento original inalterado e o CAdES (.p7s) com as assinaturas de todos os signatários. Os nomes dentro do ZIP são os mesmos do storage (ex.: contrato.pdf e contrato.pdf.p7s).

Note

Em fluxo DETACHED a validação exige os dois arquivos. Guarde o original e o .p7s juntos:

openssl cms -verify -inform DER -in contrato.pdf.p7s -content contrato.pdf -noverify -binary

Assinatura Direta (Sign)

Módulo para assinaturas imediatas sem a necessidade de criar um fluxo persistente. O processo é baseado em sessões: ao inicializar os provedores, uma sessão é criada e deve ser autorizada antes de permitir a assinatura.

Note

Atualmente, os endpoints deste módulo não exigem autenticação. Apenas documentos do tipo CPF e CNPJ com país BR são aceitos.

Inicializar Provedores (Discovery)

POST /provider/init

Descobre quais identidades digitais estão disponíveis para o CPF ou CNPJ informado. Este endpoint inicia uma sessão de assinatura para cada identidade encontrada.

Corpo da Requisição (JSON):

Campo	Tipo	Obrigatório	Descrição
documents	array	Sim	Lista de documentos para consulta (mínimo 1).
additionalInfo	object	Não	Informações adicionais (chave-valor) para o provedor.
sessionOptions	object	Não	Configuração do token junto ao PSC. Suportado apenas por provedores DOC-ICP-17; os demais ignoram.

Estrutura de ``sessionOptions``:

Campo	Tipo	Obrigatório	Descrição
scope	string	Não	SINGLE_SIGNATURE (padrão) ou SIGNATURE_SESSION.
lifetimeSeconds	inteiro	Não	Tempo de vida desejado para o token, em segundos (mínimo 60). O PSC pode ignorar o valor.

Important

SIGNATURE_SESSION abre uma sessão que assina vários documentos com uma única autorização do titular. Por isso exige chamador autenticado (JWT ou API Key) tanto aqui quanto em POST /sign, e a sessão só pode ser usada pelo tenant que a abriu. SINGLE_SIGNATURE continua disponível para chamadas anônimas e é invalidado após a primeira assinatura.

Estrutura de cada documento:

Campo	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo do documento: CPF ou CNPJ.
number	string	Não	Número do documento (somente dígitos).
country	string	Sim	País. Atualmente apenas BR é aceito.

Exemplo de Request:

{
  "documents": [
    {
      "type": "CPF",
      "number": "12345678900",
      "country": "BR"
    }
  ]
}

Exemplo de Request com sessão de assinatura:

{
  "documents": [
    {
      "type": "CPF",
      "number": "12345678900",
      "country": "BR"
    }
  ],
  "sessionOptions": {
    "scope": "SIGNATURE_SESSION",
    "lifetimeSeconds": 3600
  }
}

Resposta (200 OK):

{
  "identities": [
    {
      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "country": "BR",
      "identityId": "cert-123",
      "productName": "Certificado A1",
      "providerName": "INTEGRAICP",
      "identityEndpoint": "https://provider.example.com/auth?session=...",
      "identityType": "QUALIFIED",
      "redirectTarget": "RUBRIX",
      "providerSlug": "cert-123"
    },
    {
      "sessionId": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "country": "BR",
      "identityId": "pix-456",
      "productName": "Assinatura via Pix",
      "providerName": "PIXSIGN",
      "identityEndpoint": "https://provider.example.com/pix?session=...",
      "identityType": "ADVANCED",
      "redirectTarget": "RUBRIX",
      "providerSlug": "pix-456"
    }
  ]
}

Campos da identidade retornada:

Campo	Tipo	Descrição
sessionId	string	Identificador da sessão de assinatura. Será utilizado em todos os passos seguintes.
country	string	País do documento.
identityId	string	Identificador da identidade no provedor.
productName	string	Nome do produto do provedor.
providerName	string	Nome do provedor. Valores possíveis (enum ProviderName): INTEGRAICP, PIXSIGN, GOLDID, SAFEWEB, SERPRO, SOCIALID, MOCKPROVIDERQUALIFICADO, MOCKPROVIDERAVANCADO.
identityEndpoint	string	URL para iniciar a autorização OAuth no provedor. O usuário deve ser redirecionado para esta URL.
identityType	string	Tipo da assinatura: QUALIFIED, ADVANCED, SIMPLE.
redirectTarget	string	Para onde o provedor redireciona após o login: RUBRIX ou TENANT.
providerSlug	string	Slug do provedor usado para resolução em POST /sign.

Códigos de Erro:

• 204 No Content — Nenhuma identidade disponível para os documentos informados.

• 400 Bad Request — Dados inválidos.

• 500 Internal Server Error — Erro interno.

Próximo passo: O usuário escolhe uma identidade e realiza a autorização:

• OAuth: Redireciona o usuário para o identityEndpoint. Após a autorização no provedor, a sessão é marcada como pronta.

• Pix: Utiliza os endpoints GET /pix/init/{sessionId} e GET /pix/copiaCola/{sessionId} para gerar e exibir a cobrança. Após o pagamento, a sessão é marcada como pronta.

Verificar Status da Sessão

GET /sign/ready?sessionId={id}

Verifica se a sessão de assinatura está pronta. A sessão será ready: true somente após a conclusão bem-sucedida da autorização (OAuth ou pagamento Pix).

Ideal para polling antes de chamar o endpoint de assinatura.

Parâmetros de Query:

• sessionId (string, obrigatório) — ID da sessão retornado pelo /provider/init.

Resposta (200 OK):

{
  "ready": true
}

• ready: false — A autorização ainda não foi concluída, ou o token não pode mais assinar.

• ready: true — A sessão está pronta. Prossiga para POST /sign.

Um token já utilizado (escopo SINGLE_SIGNATURE), expirado ou revogado devolve ready: false.

Códigos de Erro:

• 400 Bad Request — Parâmetros inválidos.

• 404 Not Found — Sessão não encontrada.

Revogar Sessão de Assinatura

DELETE /sign/session/{sessionId}

Revoga a sessão informada: o token do provedor deixa de ser utilizável pela Rubrix e o registro persistido é apagado. Requer autenticação (JWT ou API Key) do tenant dono da sessão.

Use ao encerrar um lote de assinaturas antes do fim do lifetimeSeconds contratado.

Exemplo:

curl --location --request DELETE 'https://rubrix.lat/core/api/sign/session/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  --header 'X-Api-Key: <SUA_API_KEY>'

Respostas:

• 204 No Content — Sessão revogada.

• 400 Bad Request — sessionId não é um UUID válido.

• 401 Unauthorized — Chamador não autenticado.

• 403 Forbidden — A sessão não pertence ao tenant autenticado.

• 404 Not Found — Sessão não encontrada.

Assinar Documento

POST /sign

Recebe o documento, o sessionId e os dados de posicionamento via multipart/form-data, aplica a assinatura e devolve o arquivo assinado.

Important

Este endpoint só pode ser chamado quando a sessão estiver com ready: true (verificado via GET /sign/ready).

Campos do Multipart Form:

Campo	Tipo	Obrigatório	Descrição
file	binary	Sim	Arquivo binário (PDF ou XML).
sessionId	string	Sim	ID da sessão autorizada (obtido via /provider/init).
stampData	JSON	Não	Dados de posicionamento visual (pageNumber, x, y), em pontos PDF a partir do canto superior esquerdo da página renderizada. Aplicável apenas a PDFs.
policyProfile	string	Não	Perfil de assinatura desejado: B-B, B-T, B-LT, B-LTA.
xmlXpath	string	Não	XPath para posicionamento em documentos XML.

Respostas:

• 200 OK — Documento assinado retornado como binário (application/pdf ou application/xml).

• 202 Accepted — Provedor CSC exige dados de autenticação adicionais do titular (PIN, OTP ou challenge). Veja estrutura abaixo. Reenvie o POST /sign incluindo o campo cscAuthData no multipart com os valores solicitados.

• 400 Bad Request — Requisição inválida ou sessão não está pronta.

• 401 Unauthorized — Sessão com escopo SIGNATURE_SESSION chamada sem autenticação.

• 403 Forbidden — Sessão com escopo SIGNATURE_SESSION de outro tenant.

• 404 Not Found — Sessão não encontrada.

• 409 Conflict — O token da sessão já foi utilizado (SESSION_TOKEN_CONSUMED) ou expirou (SESSION_TOKEN_EXPIRED).

• 500 Internal Server Error — Erro interno.

Corpo do 202 (CSC auth challenge):

{
  "status": "CSC_AUTH_DATA_REQUIRED",
  "authObjects": [
    {
      "id": "PIN",
      "type": "PIN",
      "format": "N",
      "label": "PIN de assinatura",
      "description": "Informe o PIN do seu certificado",
      "generator": null
    }
  ],
  "supportsGetChallenge": false,
  "authError": null
}

authError vem preenchido (ex.: CSC_INVALID_AUTH_DATA) quando o 202 é retornado após uma tentativa inválida, indicando que os valores devem ser reinformados.

Tip

Com sessionOptions.scope = SIGNATURE_SESSION no /provider/init, o mesmo sessionId assina vários documentos: repita o POST /sign enviando o novo arquivo, sem nova autorização do titular.

Autorização via Pix

Quando o usuário escolhe uma identidade do provedor PIXSIGN, a autorização é feita através do pagamento de uma cobrança Pix. Ao confirmar o pagamento, o certificado efêmero é emitido automaticamente e a sessão é marcada como pronta.

Gerar Cobrança Pix:

GET /pix/init/{session_id}

Gera uma cobrança Pix vinculada à sessão de assinatura.

Parâmetros de Path:

• session_id (string, obrigatório) — ID da sessão obtido em /provider/init.

Parâmetros de Query:

• isPqc (boolean, opcional, padrão false) — Reservado. Esta opção não está disponível no momento; mantenha false.

Respostas:

• 303 See Other — Redireciona (Location) para a URL de pagamento Pix do provedor.

Obter Código Copia e Cola:

GET /pix/copiaCola/{session_id}

Retorna a string do Pix Copia e Cola para ser exibida ao usuário.

Parâmetros de Path:

• session_id (string, obrigatório) — ID da sessão.

Resposta (200 OK):

{
  "pixCopiaCola": "00020101021226..."
}

Fluxo completo da autorização via Pix:

1. Chame GET /pix/init/{sessionId} para gerar a cobrança.

2. Chame GET /pix/copiaCola/{sessionId} para obter o código e exibi-lo ao usuário.

3. O usuário efetua o pagamento Pix.

4. Monitore GET /sign/ready?sessionId={id} até receber ready: true.

5. Chame POST /sign com o sessionId e o documento.

Verificação (Verify)

Verificar Assinaturas

POST /verify

Valida as assinaturas presentes em um documento PDF ou XML. Ideal para auditoria e conformidade.

Request: Arquivo binário via multipart/form-data no campo file.

Resposta (200 OK):

{
  "document": {
    "filename": "contrato_assinado.pdf",
    "hash": "abc123def456...",
    "mimeType": "application/pdf"
  },
  "signatures": [
    {
      "status": "APPROVED",
      "policy": "PAdES",
      "policyType": "B-T",
      "signer": {
        "name": "João Silva",
        "document": "12345678900",
        "country": "BR"
      },
      "authority": {
        "providerName": "INTEGRAICP",
        "authorityName": "AC VALID"
      },
      "isPqc": false
    }
  ]
}

Campos da Resposta:

Campo	Tipo	Descrição
document	object	Metadados do documento (nome, hash SHA, MIME type).
signatures	array	Lista de assinaturas encontradas.
signatures[].status	string	Resultado: APPROVED ou REJECTED.
signatures[].policy	string	Política aplicada: PDF, PAdES, XML, XAdES.
signatures[].policyType	string	Tipo de política: B-B, B-T, B-LT, B-LTA.
signatures[].signer	object	Dados do signatário (nome, documento, país).
signatures[].authority	object	Dados da autoridade certificadora.
signatures[].isPqc	boolean	Reservado. Hoje sempre false.

Códigos de Erro:

• 400 Bad Request — Requisição inválida.

• 500 Internal Server Error — Erro interno.

Erros Padronizados

Todas as respostas de erro seguem a estrutura abaixo:

{
  "code": "INVALID_DOCUMENT",
  "message": "O documento enviado está corrompido ou não é um PDF válido.",
  "details": [
    {
      "field": "document",
      "reason": "Base64 inválido"
    }
  ]
}

Campo	Tipo	Descrição
code	string	Código do erro para tratamento programático.
message	string	Mensagem legível sobre o erro.
details	array	Lista de detalhes adicionais (campo e motivo específicos).