Documentoscopia
Platform Docs Gateway
Gateway de documentoscopia para importação, acompanhamento e consulta de documentos
POST
Platform Docs Gateway
Visão Geral
A API Platform Docs Gateway centraliza a entrada de documentos da plataforma FlexDoc, valida os arquivos enviados, registra auditoria e orquestra o envio ao FlexImage/Backoffice. O gateway também expõe endpoints para acompanhar status, consultar resultados, recuperar arquivos processados, configurar parâmetros por projeto e receber webhooks de processamento.Importação de Documentos
Recebe frente, verso e selfie em Base64 via JSON
Orquestração FlexImage
Envia documentos ao Backoffice com workflow e preset configuráveis
Acompanhamento de Status
Lista, filtra e consulta documentos por organização e projeto
Auditoria e Webhook
Persiste eventos e recebe resultados do Backoffice
Fluxo de Documentoscopia
1
Autenticação
Envie
x-api-key ou Authorization: Bearer com os headers de organização/projeto.2
Preparar Arquivos
Converta documentos para Data URI Base64. Frente é obrigatória; verso e selfie são opcionais.
3
Importar Documentos
Faça
POST /api/v1/documents/import. O gateway valida CPF, tipo de arquivo, tamanho e assinatura do conteúdo.4
Enviar ao FlexImage
O gateway cria o registro local, resolve parâmetros de workflow e envia multipart/form-data ao FlexImage.
5
Receber Resultado
O Backoffice chama
/api/v1/webhooks/backoffice e o gateway atualiza status, resultado e auditoria.Ambientes
Em ambiente de desenvolvimento, a documentação OpenAPI fica disponível em
/docs e o JSON em /openapi.json.Authentication
As rotas protegidas de/api/v1/* aceitam duas estratégias de autenticação. Webhooks usam x-secret-token.
API key validada na Platform API.Formato:
x-api-key: {api_key}Uso recomendado: integrações server-to-server que já possuem chave do projeto.Bearer token validado na Platform API.Formato:
Bearer {access_token}Quando usar Bearer, informe também:x-organization-idx-project-id
Token secreto usado exclusivamente por rotas administrativas/webhooks, como
/api/v1/webhooks/backoffice.Formato: x-secret-token: {secret_token}Todas as respostas incluem ou propagam
requestId quando disponível, facilitando correlação em logs, auditoria e suporte.Importar Documentos
Importa documentos para análise de documentoscopia.Content-Type:
application/jsonTamanho máximo do body: 25 MBRequest Body
CPF do titular do documento.Formato: 11 dígitos, com ou sem máscara.Validações: tamanho de 11 dígitos e dígitos verificadores válidos.Exemplo:
"12345678909"Frente do documento em Data URI Base64.Formatos aceitos: JPG, JPEG, PNG e PDFTamanho máximo por arquivo: 5 MBExemplo:
Verso do documento em Data URI Base64.Quando informado, o gateway une frente e verso em um PDF antes de enviar ao FlexImage.Formatos aceitos: JPG, JPEG, PNG e PDF
Selfie do titular em Data URI Base64.Formatos aceitos: JPG, JPEG e PNG
Selfie não aceita PDF.
Response
Identificador da requisição gerado pelo gateway.
UUID do documento criado no gateway.
Identificador externo enviado ao FlexImage. Por padrão, usa o
requestId.Identificador do lote no Backoffice/FlexImage.
Resposta bruta retornada pelo FlexImage no envio do lote.
Consultar Documentos
GET /api/v1/documents
GET /api/v1/documents
Lista documentos do escopo autenticado com filtros, ordenação e paginação.Query params:
Response
GET /api/v1/documents/{id}
GET /api/v1/documents/{id}
Retorna os dados completos de um documento, incluindo o resultado do processamento quando disponível.Path param:
A consulta respeita o escopo de organização e projeto associado à autenticação.
GET /api/v1/documents/{id}/files
GET /api/v1/documents/{id}/files
Recupera os arquivos processados em Base64 diretamente no FlexImage.Disponibilidade: apenas depois que o documento possui Erros comuns:
backofficeBatchId, normalmente após envio/processamento.Response
GET /api/v1/documents/statistics
GET /api/v1/documents/statistics
Retorna contagens consolidadas por estado.Regras de consolidação:
Response
Status e Resultados
Status do Documento
Status do Documento
Resultado de Análise
Resultado de Análise
Parâmetros de Projeto
Os parâmetros permitem ajustar workflow, preset e checklist por organização/projeto autenticado. Quando não há parâmetro salvo, o gateway usa os defaults configurados por variável de ambiente.Lista parâmetros do projeto autenticado.
Cria ou atualiza um parâmetro.
Chave do parâmetro.Formato: letras maiúsculas, números e
_.Exemplos aceitos:PARAMETER_WORKFLOW_ALIASPARAMETER_WORKFLOW_PRESET_ALIASPARAMETER_CHECKLIST_CODEPARAMETER_CHECKLIST_GROUPPARAMETER_CHECKLIST_VERSION
Valor do parâmetro.
Presets de Workflow
Lista os presets aceitos para envio ao FlexImage.
Webhook do Backoffice
Recebe o resultado do processamento de documentos feito pelo Backoffice.Autenticação:
x-secret-tokenIdentificador externo usado para localizar o documento no gateway. Normalmente corresponde ao
requestId/batchExternalId.Código numérico de resultado recebido do Backoffice.
Indica se o resultado foi inconclusivo.
Lista de penalidades/regras aplicadas ao documento.
Health Checks
GET /health
GET /health
Retorna status básico da aplicação.
Response
GET /health/ready
GET /health/ready
Valida dependências necessárias para tráfego: PostgreSQL e Redis.
Response
GET /health/live
GET /health/live
Retorna se o processo da aplicação está vivo.
Response
Exemplos de Código
Operação Local
1
Instalar dependências
Execute
bun install.2
Subir infraestrutura
Execute
docker compose up -d para PostgreSQL e Redis locais.3
Configurar ambiente
Crie
.env a partir dos valores necessários para PostgreSQL, Redis, Platform API, FlexImage e tokens.4
Aplicar migrations
Execute
bun run migrate.5
Iniciar API
Execute
bun run dev e acesse http://localhost:3000/docs.Variáveis Principais
Boas Práticas
Arquivos e Base64
Arquivos e Base64
- Envie sempre Data URI completa:
data:image/jpeg;base64,... - Use JPG/PNG para selfie.
- Use JPG/PNG/PDF para documentos.
- Mantenha cada arquivo abaixo de 5 MB.
- Evite logar payloads com Base64 ou dados pessoais.
Autenticação
Autenticação
- Prefira
x-api-keypara integrações server-to-server. - Em Bearer, envie também
x-organization-idex-project-id. - Rotacione secrets e tokens periodicamente.
- Não exponha
x-secret-tokenem clientes web ou aplicativos móveis.
Acompanhamento
Acompanhamento
- Guarde
documentId,requestIdebackofficeBatchId. - Consulte
/api/v1/documents/{id}para status detalhado. - Use
/api/v1/documents/statisticspara dashboards e filas operacionais. - Trate
SENTePROCESSINGcomo estados assíncronos.
Tratamento de Erros
Tratamento de Erros
Platform Docs Gateway