InvoiCy OCR Internacional

O InvoiCy OCR Internacional é uma solução de inteligência artificial desenvolvida para empresas que precisam processar, traduzir e extrair dados estruturados de faturas e documentos fiscais emitidos em qualquer país ou idioma.

Ao receber um arquivo (PDF ou imagem) contendo uma fatura internacional, o produto aplica tecnologia OCR combinada a modelos de linguagem avançados para interpretar o conteúdo do documento e devolver um JSON estruturado com todos os dados principais da nota — independentemente do idioma original, do formato visual ou do país de origem.

O resultado é a eliminação de retrabalho manual na conferência e digitação de dados de importação, acelerando o processo de registro e conciliação de documentos internacionais nos sistemas de gestão do cliente.

Casos de Uso

O InvoiCy OCR Internacional é especialmente indicado para empresas que:

Importam produtos ou serviços e recebem faturas em idiomas estrangeiros (japonês, árabe, alemão, mandarim, entre outros) que precisam ser registradas em sistemas locais.
Operam em múltiplos países e necessitam padronizar o formato de faturas de diferentes origens em um único schema de dados.
Automatizam processos de contas a pagar e precisam eliminar a digitação manual de dados de notas recebidas.
Realizam auditorias fiscais e precisam de rastreabilidade e extração confiável de informações de documentos internacionais.

Exemplo prático: Uma empresa no Uruguai recebe regularmente faturas de fornecedores japoneses, escritas em japonês. Com o InvoiCy OCR Internacional, ela envia o arquivo da fatura para a API e recebe de volta um JSON estruturado com todos os dados — número da nota, valor, itens, datas, dados do emissor e do destinatário — traduzidos e organizados, prontos para importação no seu sistema de gestão.

Como Funciona

O fluxo de processamento do InvoiCy OCR Internacional segue quatro etapas principais:

1. Registro da empresa Antes de enviar documentos para processamento, é necessário registrar a empresa importadora na plataforma InvoiCy OCR. Este registro retorna um identificador único (EmpAK) que será utilizado em todas as requisições subsequentes.

2. Envio do documento Com a empresa registrada, o cliente envia o arquivo da fatura (em Base64) para o endpoint de importação de documentos. É possível escolher o processador de IA mais adequado para o tipo de documento.

3. Processamento assíncrono A API processa o documento em background, aplicando OCR e modelos de linguagem para interpretar, traduzir e estruturar as informações contidas na fatura. A resposta imediata do envio é um protocolo de rastreamento.

4. Consulta do resultado Utilizando o protocolo recebido, o cliente consulta a API para obter o JSON estruturado com todos os dados extraídos do documento.

Pré-requisitos

Importante: Pré-requisito Comercial
O InvoiCy OCR Internacional é um produto de acesso controlado. Para utilizar a solução, é obrigatório que o modelo comercial e a negociação estejam previamente formalizados com a equipe da Migrate. Após a contratação, a equipe comercial fornecerá as credenciais e as chaves de autenticação necessárias para o acesso à API. Para iniciar uma negociação, entre em contato com o time comercial da Migrate.

Requisitos técnicos:

Credenciais de acesso fornecidas após a negociação comercial.
Capacidade de realizar chamadas HTTP REST na sua aplicação.
Capacidade de converter arquivos (PDF ou imagens) para o formato Base64.
A integração técnica é de responsabilidade do cliente, que conectará diretamente com a API do produto

Ambientes Disponíveis

O produto dispõe de dois ambientes distintos para integração. Recomendamos o uso extensivo do ambiente de homologação antes de habilitar as operações em produção.

Homologação

Ambiente destinado a testes e validações técnicas. As requisições realizadas neste endpoint não afetam dados reais ou oficiais.

URL Base: https://apibrhomolog.invoicy.com.br/ocrdocuments/api/v1/

Produção

Ambiente oficial para operações reais. Este endpoint deve ser utilizado apenas após a conclusão e validação de todos os testes no ambiente anterior.

URL Base: https://apibr.invoicy.com.br/ocrdocuments/api/v1/

A URL base (BASE_URL) deve ser substituída pela URL correspondente ao ambiente desejado. Por exemplo:

https://apibr.invoicy.com.br/ocrdocuments/api/v1/Company

Autenticação

Todas as requisições à API do InvoiCy OCR Internacional utilizam um mecanismo de autenticação baseado em hash MD5, enviado via header.

Geração do hash no registro de empresa

Para o registro de empresa, o hash MD5 é gerado a partir da concatenação da chave do parceiro com o JSON do corpo da requisição:

MD5(chave_do_parceiro + json_do_corpo)

Geração do hash nas demais requisições

Para as requisições de importação e consulta de documentos, o hash MD5 é gerado a partir da concatenação do EmpAK (retornado no registro de empresa) com um timestamp Unix em UTC:

MD5(empAK + timestamp_unix_utc)

Exemplo de string antes da geração: x99Xxxxxx+XX9/xxXXxX9xXXXXXx+9xx1740080360

Importante: O hash MD5 possui validade de 5 minutos a partir da sua geração. Requisições enviadas com hash expirado serão rejeitadas com o código de erro 403 Forbidden.

Headers obrigatórios

Todas as requisições devem incluir os seguintes headers:

X-Client-MD5-Hash: [MD5 gerado]
Content-Type: application/json; api-version=1.0

Guia de Integração

Esta seção descreve o passo a passo para integrar com o InvoiCy OCR Internacional.

Passo 1 — Consulta de Países (opcional)

Antes de registrar uma empresa, pode ser necessário obter o countryId correspondente ao país de operação. Utilize o endpoint de consulta de países passando o nome do país.

Exemplo: GET BASE_URL/Country?Nome=Uruguai

O campo id retornado na resposta deve ser utilizado no campo countryId do cadastro da empresa.

Passo 2 — Registro da Empresa

Realize o registro da empresa na plataforma InvoiCy OCR. Este passo é feito uma única vez por empresa.

Gere o hash MD5 conforme descrito na seção de autenticação.
Envie a requisição POST para BASE_URL/Company com o JSON de cadastro.
Armazene com segurança o EmpAK retornado. Ele será utilizado em todas as requisições futuras.

Exemplo de estrutura JSON para registro de empresa:

{
  "name": "Nome da Empresa S.A.",
  "cnpj": "00.000.000/0001-00",
  "partnerId": "{{ partnerId }}",
  "email": "contato@empresa.com.br",
  "phone": "(11) 3333-4444",
  "address": {
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "countryId": "{{ countryId }}"
  }
}

Passo 3 — Importação do Documento

Com a empresa registrada, envie o arquivo da fatura para processamento.

Converta o arquivo (PDF ou imagem) para Base64.
Gere o hash MD5 utilizando o EmpAK e o timestamp Unix atual.
Envie a requisição POST para BASE_URL/DocumentHandler/AddDocument.
Armazene o protocolo retornado na resposta.

Importante: A data e hora retornadas na resposta são fornecidas em formato UTC.

Exemplo de estrutura JSON para envio de documento:

{
  "companyId": 1,
  "fileBase64": "Base64_Document",
  "mimeType": "application/pdf",
  "processor": 8,
  "targetLanguage": "pt-BR"
}

Passo 4 — Consulta do Resultado

Utilize o protocolo obtido no passo anterior para consultar o resultado do processamento.

Envie a requisição GET para BASE_URL/DocumentHandler/SearchDocument?companyId={id}&protocol={protocolo}.
O retorno será o JSON estruturado com todos os dados extraídos da fatura.

Referência de Endpoints

Para exemplos interativos, payloads completos e testes, acesse a documentação completa no Postman.

Consulta de Países

Retorna o identificador (id) de um país pelo nome. O valor retornado é utilizado no campo countryId durante o registro da empresa. O nome do país deve ser informado como parâmetro ao final da URL.

GET BASE_URL/Country?Nome={nome_do_pais}

Registro de Empresa

Registra uma empresa na plataforma InvoiCy OCR, habilitando-a para processar documentos. O retorno contém o EmpAK, que deve ser armazenado de forma segura pelo cliente e utilizado em todas as requisições posteriores.

POST BASE_URL/Company

Importação de Documento

Recebe o arquivo de fatura em formato Base64 e inicia o processamento via OCR e IA. O retorno contém um protocolo para rastreamento do processamento assíncrono.

POST BASE_URL/DocumentHandler/AddDocument

Campos do corpo da requisição:

Campo	Tipo	Descrição
`companyid`	string	ID da empresa retornado no registro.
`fileBase64`	string	Conteúdo do arquivo em Base64 (PDF ou imagem).
`mimeType`	string	Tipo MIME do arquivo enviado. Ver formatos suportados.
`processor`	integer	Identificador do processador de IA. Ver processadores disponíveis.

Consulta de Documento

Consulta o resultado do processamento de um documento previamente importado. Retorna o JSON estruturado com todos os dados extraídos da fatura.

GET BASE_URL/DocumentHandler/SearchDocument?companyId={id}&protocol={protocolo}

Parâmetros de consulta:

Parâmetro	Descrição
`companyId`	ID da empresa retornado no registro.
`protocol`	Protocolo retornado no momento da importação do documento.

Estrutura de Retorno: Detalhamento dos Campos

O JSON de retorno da consulta de documento contém os seguintes campos:

Dados do Emissor

ID	Campo	Descrição	Tipo	Tam. Máx.
A01	`documentType`	Tipo de documento.	int	—
A02	`issuerDocument`	Número do documento fiscal do emissor.	string	50
A03	`nameFantasy`	Nome fantasia da empresa emissora.	string	100
A04	`corporateName`	Razão social da empresa emissora.	string	150
A05	`address`	Endereço da empresa emissora.	string	200
A06	`postalCode`	Código postal do endereço da emissora.	string	20
A07	`city`	Cidade da empresa emissora.	string	100
A08	`state`	Estado/Província da empresa emissora.	string	50
A09	`country`	País da empresa emissora.	string	50
A36	`taxID`	Identificação fiscal do emissor (ex: RUT, CNPJ, CPF).	string	50

Dados da Fatura

ID	Campo	Descrição	Tipo	Tam. Máx.
A10	`invoiceNumber`	Número da fatura.	string	50
A11	`invoiceSeries`	Série da fatura.	string	20
A12	`purchaseOrder`	Número da ordem de compra (OC).	string	—
A13	`documentLetter`	Letra do documento.	string	—
A14	`issueDate`	Data de emissão da fatura.	DateTime	—
A15	`dueDate`	Data de vencimento da fatura.	DateTime	—
A16	`caeDueDate`	Data de vencimento do CAE.	DateTime	—
A17	`inclusionDate`	Data e hora de inclusão do documento no sistema.	DateTime	—
A23	`caeNumber`	Número do CAE.	string	—
A34	`referenceNumber`	Número de referência adicional.	string	50

Valores e Condições Comerciais

ID	Campo	Descrição	Tipo	Tam. Máx.
A18	`netAmount`	Subtotal (valor líquido).	decimal	—
A19	`totalAmount`	Valor total da fatura.	decimal	—
A20	`ivaPercentage`	Percentual de IVA/imposto.	decimal	—
A21	`exchangeRate`	Taxa de câmbio.	decimal	—
A24	`currency`	Moeda da fatura.	string	10
A25	`paymentMethod`	Método de pagamento.	string	50
A26	`taxCondition`	Condição frente ao IVA.	string	—
A35	`paymentDetails`	Detalhes sobre o pagamento da fatura.	string	200
A58	`incoterm`	Incoterm aplicável à transação.	string	20
A22	`observation`	Observações adicionais sobre a fatura.	string	500

Dados do Destinatário

ID	Campo	Descrição	Tipo	Tam. Máx.
A27	`clientName`	Nome do cliente destinatário.	string	100
A28	`clientAddress`	Endereço do cliente destinatário.	string	200
A29	`clientPostalCode`	Código postal do cliente.	string	20
A30	`clientCity`	Cidade do cliente.	string	100
A31	`clientState`	Estado/Província do cliente.	string	50
A32	`clientCountry`	País do cliente.	string	50
A33	`clientDocumentNumber`	Número do documento do cliente (ex: RUT, CPF, CNPJ).	string	50
A58	`unit`	Unidade do cliente identificada na fatura (ex: loja, unidade locada ou unidade faturável).	string	100

Itens da Fatura (lista — campo `items`)

ID	Campo	Descrição	Tipo	Tam. Máx.
A38	`itemCode`	Código do artigo na fatura.	string	50
A39	`quantity`	Quantidade do artigo.	decimal	-
A40	`dispatchDate`	Data de despacho do artigo.	DateTime	-
A41	`unitOfMeasure`	Unidade de medida (ex: KG).	string	20
A42	`iclPricePerLiter`	ICL por litro.	decimal	-
A43	`unitPrice`	Preço unitário do artigo.	decimal	-
A44	`itemDiscount`	Desconto aplicado ao artigo.	decimal	-
A45	`itemDiscountPercentage`	Percentual de desconto aplicado.	decimal	-
A46	`totalPrice`	Preço total do artigo após descontos.	decimal	-
A47	`itemName`	Nome/descrição do artigo.	string	100
A48	`eanOrDun`	Código EAN ou código de barras.	string	50
A49	`referenceNumberItem`	Número de referência do artigo.	string	50
A50	`origin`	Origem do artigo.	string	50
A51	`ncmOrHts`	Código NCM (mercadoria) ou HTS (tarifa aduaneira).	string	50
A52	`stockID`	Identificação do estoque do artigo.	string	50
A53	`packingUnit`	Unidade de embalagem.	string	20
A54	`packingQuantity`	Quantidade de artigos por embalagem.	decimal	-

Encargos Adicionais (lista — campo `additionalCharges`)

ID	Campo	Descrição	Tipo	Tam. Máx.
A56	`additionalChargeDescription`	Descrição do encargo adicional.	string	200
A57	`additionalChargeValue`	Valor do encargo adicional.	decimal	-

Formatos de Arquivo Suportados

O campo mimeType da requisição de importação aceita os seguintes valores:

Valor	Formato
`application/pdf`	Documento PDF
`image/png`	Imagem PNG
`image/jpeg`	Imagem JPEG
`image/jpg`	Imagem JPG
`image/bmp`	Imagem BMP
`image/pjpeg`	Imagem PJPEG
`image/x-png`	Imagem X-PNG

Processadores Disponíveis

O campo processor define qual motor de inteligência artificial será utilizado no processamento do documento. A escolha do processador pode impactar a precisão e o tempo de processamento.

Valor	Processador
`1`	DocumentAI
`6`	Gemini 3.0 Flash
`8`	Gemini 3.1 Pro Preview
`9`	DocumentAI + Gemini 3.0 Flash
`11`	DocumentAI + Gemini 3.1 Pro Preview
`12`	Gemini 3.5 Flash
`13`	Gemini 3.1 Flash Lite
`14`	DocumentAI + Gemini 3.5 Flash
`15`	DocumentAI + Gemini 3.1 Flash Lite
`16`	Gemini 3.8 Flash
`17`	Gemini 3.5 Flash Lite
`18`	DocumentAI + Gemini 3.8 Flash
`19`	DocumentAI + Gemini 3.5 Flash Lite

Boas Práticas e Limitações

Um documento por arquivo: Não é recomendado importar mais de uma fatura em um mesmo arquivo PDF. Documentos com múltiplas faturas podem reduzir a precisão do processamento.
Qualidade do arquivo: Documentos com boa resolução e contraste tendem a gerar resultados mais precisos na extração de dados.
Validade do hash: O hash MD5 de autenticação expira em 5 minutos. Certifique-se de gerar um novo hash a cada requisição.
Processamento assíncrono: O processamento dos documentos não é instantâneo. Implemente uma lógica de polling (consultas periódicas) para verificar o resultado da extração.
Armazenamento do EmpAK: O EmpAK retornado no registro de empresa deve ser armazenado de forma persistente e segura, pois é necessário para todas as operações subsequentes.