Integracion API de Nanonets

1) Vision General

Nanonets es un servicio de OCR e IA que permite crear modelos personalizados para extraer datos estructurados de imagenes y documentos. Soporta operaciones sincronas y asincronas.

2) Autenticacion

Clave API

La clave API se obtiene en: https://app.nanonets.com/#keys

Almacenar en .env:

# Archivo: .env
NANONETS_API_KEY=tu_clave_api_aqui

URL Base

https://app.nanonets.com

Metodo de autenticacion

Nanonets usa Basic Auth con la API key como usuario y password vacio:

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/" \
  -u "$NANONETS_API_KEY:"

3) Conceptos Clave

4) Referencia API - Predicciones (OCR)

Prediccion sincrona desde archivo local

Optimo para archivos de 3 paginas o menos.

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "[email protected]"

Con metadata opcional:

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "[email protected]" \
  -F "request_metadata={\"conductor_id\": \"123\"}"

Parametros:

• file (requerido): Archivo local
• request_metadata (opcional): JSON con datos adicionales
• pagestoprocess (opcional): Paginas a procesar (ej: "1,2")

Prediccion sincrona desde URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelUrls/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/recibo.pdf"]}'

Prediccion asincrona desde archivo

Recomendado para archivos de mas de 3 paginas.

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelFile/?async=true" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@documento_largo.pdf"

Prediccion asincrona desde URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/LabelUrls/?async=true" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/documento.pdf"]}'

5) Referencia API - Obtener Resultados

Obtener todas las predicciones de un modelo

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/getModelImages/?start_day_interval=30&current_batch_day=0" \
  -u "$NANONETS_API_KEY:"

Parametros:

• startdayinterval: Dias hacia atras desde hoy
• currentbatchday: Dia actual del batch (0 = hoy)

Obtener prediccion por File ID

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/getFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Obtener prediccion por Page ID

source .env && curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ImageLevelInferences/{page_id}/" \
  -u "$NANONETS_API_KEY:"

6) Referencia API - Entrenamiento

Subir imagenes de entrenamiento por archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UploadFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@imagen_entrenamiento.jpg"

Subir imagenes de entrenamiento por URL

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UploadUrls/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://ejemplo.com/imagen1.jpg", "https://ejemplo.com/imagen2.jpg"]}'

Entrenar modelo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/Train/" \
  -u "$NANONETS_API_KEY:"

7) Referencia API - Gestion de Archivos

Aprobar archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ApproveFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Eliminar archivo

source .env && curl -X DELETE "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/DeleteFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

Actualizar campos de un archivo

source .env && curl -X PATCH "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/UpdateFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {"label": "fecha", "ocr_text": "2025-12-23"},
      {"label": "total", "ocr_text": "45.99"}
    ]
  }'

Exportar archivo

source .env && curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/{model_id}/ExportFile/{request_file_id}/" \
  -u "$NANONETS_API_KEY:"

8) Estructura de Respuesta

Respuesta de prediccion exitosa

{
  "message": "Success",
  "result": [
    {
      "message": "Success",
      "input": "recibo.pdf",
      "prediction": [
        {
          "id": "abc123",
          "label": "fecha",
          "xmin": 100,
          "ymin": 200,
          "xmax": 250,
          "ymax": 230,
          "score": 0.95,
          "ocr_text": "23/12/2025",
          "type": "field",
          "status": "correctly_predicted",
          "page_no": 0,
          "label_id": "label_001"
        },
        {
          "id": "def456",
          "label": "total",
          "xmin": 300,
          "ymin": 400,
          "xmax": 400,
          "ymax": 430,
          "score": 0.92,
          "ocr_text": "45.99",
          "type": "field",
          "status": "correctly_predicted",
          "page_no": 0,
          "label_id": "label_002"
        },
        {
          "label": "lineas_detalle",
          "type": "table",
          "score": 0.89,
          "xmin": 50,
          "xmax": 500,
          "ymin": 500,
          "ymax": 700,
          "cells": [
            {
              "row": 1,
              "col": 1,
              "label": "descripcion",
              "text": "Gasoil",
              "score": 0.91
            },
            {
              "row": 1,
              "col": 2,
              "label": "cantidad",
              "text": "50L",
              "score": 0.88
            }
          ]
        }
      ],
      "page": 0,
      "request_file_id": "file_789",
      "processing_type": ""
    }
  ],
  "signed_urls": {
    "original": "https://...",
    "original_with_long_expiry": "https://..."
  }
}

Campos de respuesta clave

9) Sync vs Async

Para async, usar el endpoint de "Get Prediction by File ID" para obtener resultados.

10) Manejo de Errores

Codigos de respuesta

Manejo de 429 (Rate Limit)

# Implementar exponential backoff
for i in 1 2 4 8 16; do
  response=$(curl -s -w "%{http_code}" ...)
  if [ "${response: -3}" != "429" ]; then
    break
  fi
  sleep $i
done

11) Obtener Model ID

El model_id se encuentra en la URL del dashboard de Nanonets:

https://app.nanonets.com/#/ocr/model/{MODEL_ID}/...

O via la lista de modelos (requiere acceso al dashboard).

12) Ejemplo: Flujo completo

# 1. Cargar credenciales
source .env

# 2. Subir archivo para prediccion
curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/LabelFile/" \
  -u "$NANONETS_API_KEY:" \
  -F "file=@recibo_gasoil.pdf" \
  -F 'request_metadata={"matricula": "1234-ABC"}'

# Respuesta incluye prediction con campos extraidos

# 3. Si es async, obtener resultados despues
curl -X GET "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/getFile/$REQUEST_FILE_ID/" \
  -u "$NANONETS_API_KEY:"

# 4. Aprobar archivo despues de revision
curl -X POST "https://app.nanonets.com/api/v2/OCR/Model/$MODEL_ID/ApproveFile/$REQUEST_FILE_ID/" \
  -u "$NANONETS_API_KEY:"

13) Comparacion con Parsio

14) Recursos

• Documentacion API Nanonets
• Autenticacion
• Rate Limits
• Postman Collection