Classificador

Serviços para classificação de documentos.

O serviço identifica documentos dentro do arquivo enviado e a partir deles nossas IAs os classificam.

O classificador só responde que documento é aquele — ele não lê nada de dentro do documento. Para receber também os campos escritos nele, use o Full OCR.

Request

POST /classify/v3

Parâmetros

Este endpoint não tem parâmetros de query. Diferente de outros endpoints, um parâmetro de query desconhecido não devolve 422 aqui: ele é simplesmente ignorado.

Headers

Authorization: ApiKey <sua-chave-de-api>

Este endpoint também aceita o token JWT, no formato Authorization: Bearer <accessToken>. Veja Token JWT.

Arquivos aceitos

Como parâmetro esse endpoint espera o arquivo ou imagem a ser classificado. Para mais informações acesse aqui.

Item	Valor
Formatos	image/png, image/jpeg, application/pdf
Quantidade por chamada	1 arquivo
Tamanho máximo (multipart)	15 MB

TIP

Esse endpoint só aceita um arquivo ou imagem por vez.

O nome do campo do formulário é livre — ele volta na resposta, em metadata.filesInfo. Se mais de um arquivo for enviado, a requisição é recusada com 422.

Um PDF de várias páginas tem cada página analisada separadamente, e cada documento reconhecido vira uma entrada de data.

Além do multipart/form-data, o arquivo pode ser enviado em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/classify/v3' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'documento=@./cnh.jpg'

Response

Os campos abaixo descrevem a v3. As demais versões devolvem um data com outro formato — veja Versões.

Campo	Descrição	Tipo	Observação
id	ID único da requisição	String
version	Versão da API	String
data	Lista com os resultados da análise	Object[]	Vem vazia quando nada foi reconhecido
data.classification	Objeto com os detalhes da classificação	Object
data.classification.type	Tipo do documento encontrado	String	Vide lista de documentos aceitos
data.classification.subtype	Subtipo do documento encontrado	String	Vide lista de documentos aceitos
data.classification.country	País de origem do documento encontrado	String	Vide lista de documentos aceitos
data.classification.sides	Lista com o lado do documento encontrado	Object[]	Sempre conterá somente um item
data.classification.sides.side	Lado encontrado do documento	String	Enum: (OnlyFront, OnlyBack, FrontAndBack)
data.classification.sides.page	Página onde o documento foi encontrado	Number	Começa em 0
data.classification.sides.fieldname	Nome do campo em que o arquivo foi passado	String
data.classification.sides.confidence	Confiança da classificação	Number	Valor já filtrado internamente
metadata	Metadados da requisição (para apoio a debug)	Object
metadata.filesInfo	Lista com as informações (metadata dos arquivos)	Object[]
metadata.filesInfo.fieldname	Nome do parâmetro em que o arquivo foi passado	String
metadata.filesInfo.name	Nome do arquivo passado	String
metadata.filesInfo.size	Tamanho do arquivo passado, em bytes	Number
metadata.filesInfo.pages	Número de páginas do arquivo	Number	Para imagens, 1
metadata.filesInfo.mimetype	Mimetype do arquivo passado	String
metadata.filesInfo.encoding	Encoding do arquivo passado	String
metadata.filesInfo.sha256	SHA256 do arquivo passado	String
metadata.timeSpent	Tempo de processamento da requisição	Number	Em milissegundos

TIP

confidence - Já realizamos o filtro interno para devolver somente os documentos acima da confiança esperada. Recomendamos o uso de filtro nesse campo somente em casos específicos, onde o filtro default não atenda ou queira "subir a régua" da qualidade mínima aceita.

TIP

A resposta é sempre uma lista (campo data), pois em um arquivo/imagem pode ter nenhum, 1 ou mais identidades. Porém, para simplificar o consumo deste dado, a lista está ordenada do melhor ao pior resultado, ou seja, caso o cenário esperado seja somente um arquivo, recomendamos pegar o primeiro item da lista, caso esta esteja vazia significa que não foi possível identificar nenhum documento naquela imagem.

Exemplos JSON

Veja alguns exemplos em JSON da resposta.

1. Exemplo quando uma identidade é encontrada na imagem

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v3",
  "data": [
    {
      "classification": {
        "type": "DriversLicense",
        "subtype": "Printed",
        "country": "BRA",
        "sides": [
          {
            "side": "FrontAndBack",
            "page": 0,
            "fieldname": "documento",
            "confidence": 0.99
          }
        ]
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

2. Exemplo quando nenhum documento é encontrado na imagem

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v3",
  "data": [],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ou token JWT ausente, inválido, ou sem a permissão nextid.classifications.classify.
404 Not Found	A versão informada na URL não existe. Só v2, v3, v4 e v5 são aceitas.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo base64.
413 Payload Too Large	O arquivo enviado em multipart/form-data passa de 15 MB.
415 Unsupported Media Type	O header Content-Type está ausente ou não é suportado.
422 Unprocessable Entity	O formato do arquivo não é aceito, ou foi enviado mais de um arquivo na mesma chamada.
500 Internal Server Error	Falha inesperada durante o processamento.

Um documento que o classificador não reconhece não é erro: a resposta vem 200 com data vazio.

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

A versão documentada nesta página é a v3, chamada em /classify/v3. É a que usa o mesmo vocabulário de tipos da lista de identidades aceitas abaixo.

‼️ Omitir a versão entrega a chamada para a v2

POST /classify, sem versão no caminho, é atendido pela v2, que responde em outro formato. Informe sempre a versão na URL.

Versão	Situação	O que muda
v3	Recomendada	classification com type, subtype, country e sides como lista.
v4	Disponível	sides some do classification: sobram um side consolidado (Front, Back, FrontAndBack) e um sameImage. page, fieldname e confidence migram para metadata.filesInfo[].details.
v5	Disponível	Aceita na URL. Devolve o mesmo corpo de resposta da v4, com version: "v5".
v2	Legada	Não traz subtype nem country. type usa o vocabulário antigo (CNH, RG, CPF, OTHERS…) e o lado vem em face. É o que responde quando a versão é omitida na URL.

O que muda na v2

Cada item de data traz page e fieldname na raiz, e o classification é reduzido a três campos:

Campo	Descrição	Tipo
data.page	Página onde o documento foi encontrado	Number
data.fieldname	Nome do campo em que o arquivo foi passado	String
data.classification.type	CNH, RG, CPF, PROOF-OF-RESIDENCE, SELFIE, IMPRESSOS, CARTAOCREDITO ou OTHERS	String
data.classification.face	front, back ou front-back	String
data.classification.confidence	Confiança da classificação	Number

Todo tipo fora dessa lista — passaporte, carteira de conselho, documento estrangeiro — é devolvido como OTHERS na v2.

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v2",
  "data": [
    {
      "page": 0,
      "fieldname": "documento",
      "classification": {
        "confidence": 0.99,
        "type": "CNH",
        "face": "front-back"
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0"
      }
    ],
    "timeSpent": 10000
  }
}

O que muda na v4 e na v5

O classification deixa de ter a lista sides e passa a ter um side já consolidado, no vocabulário Front / Back / FrontAndBack. page, fieldname e confidence saem do classification e reaparecem em metadata.filesInfo[].details.

Campo	Descrição	Tipo
data.classification.type	Tipo do documento encontrado	String
data.classification.subtype	Subtipo do documento encontrado	String
data.classification.country	País de origem do documento encontrado	String
data.classification.side	Lado consolidado: Front, Back ou FrontAndBack	String
data.classification.sameImage	true quando frente e verso vieram da mesma página do mesmo arquivo	Boolean
metadata.filesInfo[].details	Uma entrada por face reconhecida naquele arquivo	Object[]
metadata.filesInfo[].details[].side	Face reconhecida: Front, Back ou FrontAndBack	String
metadata.filesInfo[].details[].page	Página em que ela foi reconhecida. Começa em 0.	Number
metadata.filesInfo[].details[].confidence	Confiança da classificação daquela face	Number

🚧 Na v4 e na v5 a lista não vem ordenada por confiança

A confidence sai do classification antes da ordenação, então a ordenação por confiança não acontece nessas versões: quando mais de um documento é reconhecido no mesmo arquivo, data vem na ordem em que eles foram processados, e não do melhor para o pior. Se você depende dessa ordem, use a v3.

Status Code: 200

{
  "id": "5a7bad63-cac6-430c-ac65-a94def0f7b7a",
  "version": "v4",
  "data": [
    {
      "classification": {
        "country": "BRA",
        "type": "DriversLicense",
        "subtype": "Printed",
        "side": "FrontAndBack",
        "sameImage": true
      }
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "documento",
        "name": "arquivo.JPG",
        "size": 567098,
        "pages": 1,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "41c2ece339abfcf9ba1e7d5a60666162a24ef34ba95adeb41ed1d9721c91c6b0",
        "details": [
          {
            "side": "FrontAndBack",
            "confidence": 0.99,
            "page": 0
          }
        ]
      }
    ],
    "timeSpent": 10000
  }
}

Tipo e Subtipos de Identidades

Lista com os tipos, subtipos e lados de cada identidade reconhecida por nosso classificador. Perceba que a lista abaixo respeita a seguinte sequência: País de origem, Tipo, Subtipo e Lado.

Ex.:

• País
  • Tipo
    • Subtipo
      • Lado

---

Lista Completa

ARG

DriversLicense

• empty
  • OnlyFront

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

BHR

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

BRA

FederalCouncil

• Accounting_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Accounting_Plastic
  • OnlyBack
  • OnlyFront
• Administration_v1
  • OnlyBack
  • OnlyFront
• Administration_v2
  • OnlyBack
  • OnlyFront
• ArchitectureAndUrbanism
  • OnlyFront
• Biology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Biomedicine
  • OnlyBack
  • OnlyFront
• Chemistry
  • OnlyBack
  • OnlyFront
• Dentistry
  • OnlyBack
  • OnlyFront
• EngineeringAndAgronomy_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• EngineeringAndAgronomy_Plastic
  • OnlyBack
  • OnlyFront
• Fishery
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Lawyers
  • OnlyBack
  • OnlyFront
• Medicine_Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Medicine_Plastic
  • OnlyBack
  • OnlyFront
• Musician
  • OnlyBack
  • OnlyFront
• Nursing_v1
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Nursing_v2
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Nutrition
  • OnlyBack
  • OnlyFront
• Pharmacy_Paper
  • OnlyBack
  • OnlyFront
• Pharmacy_Plastic
  • OnlyBack
  • OnlyFront
• PhysicalEducation
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Psychology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Radiology
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• SalesRepresentatives
  • OnlyFront
• SocialService
  • OnlyBack
  • OnlyFront
• Veterinary
  • OnlyBack
  • OnlyFront

DriversLicense

• BoatAndVessel
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Printed
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Resolution2021Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Resolution2021Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack

FederalID

• Decree2018Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Decree2018Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Decree2018Plastic
  • OnlyBack
  • OnlyFront
• Decree2022Paper
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MainModel
  • OnlyBack
  • OnlyFront
  • FrontAndBack

FederalRevenueService

• CIC
  • OnlyFront
• Plastic
  • OnlyFront
• Printed
  • OnlyFront
• Temporary
  • OnlyFront

FirefighterID

• RioDeJaneiro
  • OnlyBack
  • OnlyFront

ForeignID

• empty
  • OnlyBack
  • OnlyFront

MigratoryRegister

• empty
  • OnlyBack
  • OnlyFront

RefugeRequest

• empty
  • OnlyBack
  • OnlyFront
  • FrontAndBack

MilitaryID

• Airforce
  • OnlyBack
  • OnlyFront
• Army_Paper
  • OnlyBack
  • OnlyFront
• Army_Temporary
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MilitaryDischarge
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Navy_Paper
  • OnlyBack
  • FrontAndBack
• Navy_Plastic
  • OnlyBack
  • OnlyFront

Passport

• empty
  • OnlyFront

PoliceID

• Alagoas
  • OnlyFront
• Amazonas
  • OnlyFront
• Bahia
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• Ceara
  • OnlyFront
• DistritoFederal
  • OnlyBack
  • OnlyFront
• EspiritoSanto
  • OnlyFront
• MatoGrosso
  • OnlyBack
  • OnlyFront
• MatoGrossoDoSul
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• MinasGerais_Paper
  • OnlyBack
  • OnlyFront
• MinasGerais_Plastic
  • OnlyFront
• Para
  • OnlyBack
  • OnlyFront
• Paraiba
  • OnlyBack
  • OnlyFront
• Pernambuco
  • OnlyBack
  • OnlyFront
• Piaui
  • OnlyFront
• RioDeJaneiro
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• RioGrandeDoNorte
  • OnlyFront
• SaoPaulo
  • OnlyBack
  • OnlyFront
  • FrontAndBack

ProofOfResidence

• Celesc
  • OnlyFront
• Cemig
  • OnlyFront
• Claro
  • OnlyFront
• CoelbaCelpe
  • OnlyFront
• Copel
  • OnlyFront
• Cpfl
  • OnlyFront
• Edp
  • OnlyFront
• Enel
  • OnlyFront
• Energisa
  • OnlyFront
• Equatorial
  • OnlyFront
• Light
  • OnlyFront
• Rge
  • OnlyFront
• Sabesp
  • OnlyFront
• Saneago
  • OnlyFront
• Tim
  • OnlyFront
• Vivo
  • OnlyFront

Transportation

• ANTT
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• CRLV_Digital
  • OnlyBack
  • OnlyFront
  • FrontAndBack
• CRLV_Printed
  • OnlyBack
  • OnlyFront
  • FrontAndBack

VoterID

• empty
  • OnlyBack
  • OnlyFront

WorkAndSocialSecurityRegistry

• Handwritten
  • OnlyBack
  • OnlyFront
• Printed
  • OnlyBack
  • OnlyFront

---

COL

DriversLicense

• empty
  • OnlyFront

FederalID

• empty
  • OnlyBack
  • OnlyFront

Passport

• empty
  • OnlyFront

---

ESP

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

ITA

FederalID

• empty
  • OnlyBack
  • OnlyFront

---

MAR

DriversLicense

• empty
  • OnlyBack
  • OnlyFront

---

MEX

VoterID

• empty
  • OnlyFront

---

PAK

FederalID

• empty
  • OnlyFront
  • OnlyBack

---

PER

FederalID_Paper

• empty
  • OnlyFront

FederalID_Plastic

• empty
  • OnlyFront

Passport

• empty
  • OnlyFront

---

PRT

FederalID

• empty
  • OnlyFront
  • OnlyBack

Passport

• empty
  • OnlyFront

---

PRY

FederalID

• empty
  • OnlyFront

---

URY

FederalID

• empty
  • OnlyFront

---

USA

DriversLicense

• Florida
  • OnlyFront
• Georgia
  • OnlyFront

Passport

• empty
  • OnlyFront

SocialSecurityID

• empty
  • OnlyFront

---

VEN

FederalID

• empty
  • OnlyFront

Passport

• empty
  • OnlyFront