Skip to main content
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.
x-api-key
string
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.
Authorization
string
Bearer token validado na Platform API.Formato: Bearer {access_token}Quando usar Bearer, informe também:
  • x-organization-id
  • x-project-id
x-secret-token
string
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

POST /api/v1/documents/import
endpoint
required
Importa documentos para análise de documentoscopia.Content-Type: application/jsonTamanho máximo do body: 25 MB

Request Body

cpf
string
required
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"
documents.identification.front
string
required
Frente do documento em Data URI Base64.Formatos aceitos: JPG, JPEG, PNG e PDFTamanho máximo por arquivo: 5 MBExemplo:
documents.identification.back
string
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
string
Selfie do titular em Data URI Base64.Formatos aceitos: JPG, JPEG e PNG
Selfie não aceita PDF.

Response

requestId
string
required
Identificador da requisição gerado pelo gateway.
documentId
string
required
UUID do documento criado no gateway.
batchExternalId
string
required
Identificador externo enviado ao FlexImage. Por padrão, usa o requestId.
backofficeBatchId
string
required
Identificador do lote no Backoffice/FlexImage.
flexImageResponse
unknown
required
Resposta bruta retornada pelo FlexImage no envio do lote.

Consultar Documentos

Lista documentos do escopo autenticado com filtros, ordenação e paginação.Query params:
Response
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.
Recupera os arquivos processados em Base64 diretamente no FlexImage.Disponibilidade: apenas depois que o documento possui backofficeBatchId, normalmente após envio/processamento.
Response
Erros comuns:
Retorna contagens consolidadas por estado.
Response
Regras de consolidação:

Status e Resultados


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.
GET /api/v1/parameters
endpoint
Lista parâmetros do projeto autenticado.
POST /api/v1/parameters
endpoint
Cria ou atualiza um parâmetro.
key
string
required
Chave do parâmetro.Formato: letras maiúsculas, números e _.Exemplos aceitos:
  • PARAMETER_WORKFLOW_ALIAS
  • PARAMETER_WORKFLOW_PRESET_ALIAS
  • PARAMETER_CHECKLIST_CODE
  • PARAMETER_CHECKLIST_GROUP
  • PARAMETER_CHECKLIST_VERSION
value
string
required
Valor do parâmetro.

Presets de Workflow

GET /api/v1/workflow-presets
endpoint
Lista os presets aceitos para envio ao FlexImage.

Webhook do Backoffice

POST /api/v1/webhooks/backoffice
endpoint
required
Recebe o resultado do processamento de documentos feito pelo Backoffice.Autenticação: x-secret-token
external_id
string
Identificador externo usado para localizar o documento no gateway. Normalmente corresponde ao requestId/batchExternalId.
result
number
Código numérico de resultado recebido do Backoffice.
inconclusivo
boolean
Indica se o resultado foi inconclusivo.
penalidades
array
Lista de penalidades/regras aplicadas ao documento.

Health Checks

Retorna status básico da aplicação.
Response
Valida dependências necessárias para tráfego: PostgreSQL e Redis.
Response
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

  • 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.
  • Prefira x-api-key para integrações server-to-server.
  • Em Bearer, envie também x-organization-id e x-project-id.
  • Rotacione secrets e tokens periodicamente.
  • Não exponha x-secret-token em clientes web ou aplicativos móveis.
  • Guarde documentId, requestId e backofficeBatchId.
  • Consulte /api/v1/documents/{id} para status detalhado.
  • Use /api/v1/documents/statistics para dashboards e filas operacionais.
  • Trate SENT e PROCESSING como estados assíncronos.