Leitor de documentos

Este serviço é usado para ler informações de uma imagem de documento com tecnologia OCR da FacePhi e organizar as informações em campos.

O serviço pode lidar com diferentes tipos de documentos, incluindo cédulas de identidade, cartões de estrangeiro, faturas e PDFs. É necessário especificar o tipo de documento e o modelo para processar o documento corretamente.

Para uma lista completa de tipos de documentos e modelos suportados, consulte Documentos suportados por OCR.

Documentos suportados por OCR

Tipos de documento

O serviço OCR pode processar diferentes tipos de documentos. Use o parâmetro type para especificar o tipo de documento a processar:

Tipo	Valor	Descrição
Cédula de identidade	id_card	Cédulas ou cartões de identidade nacionais
Cartão de estrangeiro	foreign_card	Cartões de identificação de estrangeiros
PDF	pdf	Documentos PDF que exigem processamento OCR
Fatura	invoice	Documentos de faturamento

Modelos suportados por tipo de documento

Cédulas de identidade (ID Cards)

Para cédulas de identidade, use o código do país ISO 3166-1 alpha-3 como parâmetro model:

País	Código ISO
Argentina	ARG
México	MEX

Cartões de estrangeiro (Foreign Cards)

Para cartões de estrangeiro, use os seguintes códigos como parâmetro model:

País	Código ISO
México	MEX

Faturas (Invoices)

Para faturas, use o código do provedor como parâmetro model:

Provedor	Código
TELMEX	TELMEX
CFE	CFE

Documentos PDF

Para documentos PDF, use o código do tipo de documento como parâmetro model:

Tipo de documento	Código
IVA: El Salvador	IVA
RENTA: El Salvador	RENTA

Endpoint

POST /ocr

Cabeçalhos

Nome	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	API Key de autorização de acesso.
family	string	Não	Valor: Onboarding. Obrigatório com o serviço de tracking.

Todas as chamadas aos Endpoints para tracking com Identity Platform devem conter o header family.

Corpo da solicitação

Content-Type: application/json

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
type	string	Sim	Tipo de documento a ser processado. Somente os tipos permitidos na configuração do tenant podem ser usados. Valores possíveis: id_card, passport, driver_license, foreign_card, invoice, pdf
model	string	Sim	Identificador do modelo de documento a ser processado. Para documentos de identidade, use o código do país ISO 3166-1 alpha-3. Para faturas ou documentos PDF, use os códigos específicos fornecidos pela FacePhi.
files	string[]	Sim	Imagens do documento codificadas em Base64 (RFC4648). Máximo de duas imagens por solicitação. A primeira imagem é tratada como o lado frontal.
isCropped	boolean	Não	Indica se as imagens fornecidas já estão recortadas. Valor padrão: false
forceDetection	boolean	Não	Força a detecção OCR mesmo se a detecção automática do documento falhar. Valor padrão: false
retrieveImages	boolean	Não	Retorna imagens recortadas na resposta quando há suporte para o tenant configurado. Valor padrão: false
tracking	object	Não	Objeto que representa as informações de tracking necessárias.
tracking.extraData	string	Não	Token gerado pelo SDK Mobile/Web. Contém informações de tracking tokenizadas com a Plataforma.
tracking.operationId	string	Não	Identificador de operação gerado pelo SDK Mobile/Web.

Exemplo de solicitação

{
  "type": "pdf",
  "model": "IVA",
  "files": ["JVBERi0xLjQKJeLjz9MKNSAwIG9iago8P..."],
  "tracking": {
    "extraData": "BQABAQG2gBNjuHN4kLmPqYf7R...",
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Respostas

200 Sucesso

Parâmetros de resposta

Parâmetro	Tipo	Descrição
serviceResultCode	integer	Código que indica o resultado geral da execução do serviço.
serviceResultLog	string	Campo descritivo do resultado da execução do serviço.
timestamp	string	Momento em que o serviço finalizou o processamento.
serviceTransactionId	string	Identificador de transação associado à solicitação processada pela API.
serviceResult	object	Objeto com o resultado do OCR contendo os campos extraídos.
serviceTime	string	Tempo total de execução do serviço (milissegundos).

Service Result Code

O serviceResultCode indica o resultado geral da execução do serviço:

serviceResultCode	Descrição	Código HTTP
0	A execução do serviço foi bem-sucedida, o módulo processou a solicitação corretamente.	200

Exemplo de resposta

{
  "serviceResultCode": 200,
  "serviceResultLog": "Service executed ok",
  "timestamp": "2024-07-12T09:43:36Z",
  "serviceTransactionId": "99999999-9999-9999-9999-999999999999",
  "serviceResult": {
    "dictionary": {
      "CommercialName": "Nome comercial de exemplo",
      "DeclarationNumber": "11111111111",
      "EconomicActivity": "Transportes nacionais",
      "NIT": "9999-999999-999-9",
      "NRC": "999999-9",
      "Name": "John Doe",
      "TaxedPeriod": "04 2021"
    },
    "model": "IVA",
    "side": "front",
    "type": "pdf",
    "version": "2021"
  },
  "serviceTime": "638"
}

400 Solicitação inválida

{
  "status": 400,
  "title": "Solicitação inválida",
  "detail": "Requisição inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400",
  "errors": []
}

401 Não autorizado

{
  "message": "Não autorizado"
}

403 Acesso negado

{
  "Message": "O usuário não está autorizado a acessar este recurso com uma negação explícita"
}

502 Gateway inválido

{
  "status": 502,
  "title": "Gateway inválido",
  "detail": "O servidor recebeu uma resposta inválida.",
  "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502"
}

504 Gateway Timeout

{
  "message": "A solicitação do Endpoint excedeu o tempo limite"
}