API extraccion documentos aduaneros

Extraccion inteligente de datos de cualquier documento. Envia un archivo (PDF o imagen) junto con un esquema de extraccion en formato JSON, y recibe datos estructurados listos para usar.

POST https://api.camtomx.com/api/v3/camtomdocs/extract

Costo: Segun paginas procesadas (ver campo billed_pages en la respuesta).

Request

Headers

Header	Tipo	Requerido	Descripcion
`Authorization`	string	Si	`Bearer <api_key>`

Este endpoint usa multipart/form-data. No establezcas Content-Type manualmente — la mayoria de los clientes HTTP lo configuran automaticamente con el boundary correcto al enviar formularios.

Query parameters

string

required

Codigo de pais. Valores permitidos: COL, MEX, USA, ARG, WORLD.

boolean

default:"false"

Si es true, el campo json_response dentro de json_data se trata como un JSON Schema Draft 7 valido. Si es false, el sistema infiere las descripciones automaticamente.

boolean

default:"false"

Flag interno adicional.

Body parameters (multipart/form-data)

string

required

String JSON con el esquema de extraccion. Debe contener tres campos:

document_type — Tipo de documento (ej. "invoice", "packing_list")
document_description — Descripcion de lo que se quiere extraer
json_response — JSON Schema (Draft 7) que define la estructura de salida

file

El archivo a procesar. Formatos soportados: PDF, JPEG, PNG, TIFF, BMP, WEBP.Debe proporcionarse file_path o file_url, no ambos.

string

URL del documento a procesar. Alternativa a subir el archivo directamente.Debe proporcionarse file_path o file_url, no ambos.

Estructura del campo `json_data`

El parametro json_data es un string JSON con la siguiente estructura:

{
  "document_type": "invoice",
  "document_description": "Factura comercial de importacion con datos del exportador e importador",
  "json_response": {
    "type": "object",
    "properties": {
      "nombre_campo": {
        "type": "string",
        "description": "Descripcion de lo que representa este campo"
      },
      "campo_numerico": {
        "type": "number",
        "description": "Descripcion del valor numerico a extraer"
      },
      "campo_array": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "subcampo": { "type": "string" }
          }
        },
        "description": "Lista de elementos a extraer"
      }
    },
    "required": ["nombre_campo"]
  }
}

El campo json_response se valida contra la especificacion JSON Schema Draft 7. No puede estar vacio.

Incluye description en cada propiedad del schema. La IA usa estas descripciones para entender mejor que dato extraer, especialmente cuando el nombre del campo es ambiguo.

Ejemplo de request

El siguiente ejemplo extrae datos de una factura comercial:

import requests
import json

json_data = {
    "document_type": "invoice",
    "document_description": "Factura comercial de importacion",
    "json_response": {
        "type": "object",
        "properties": {
            "invoice_number": {
                "type": "string",
                "description": "Numero de factura"
            },
            "date": {
                "type": "string",
                "description": "Fecha de la factura en formato YYYY-MM-DD"
            },
            "seller": {
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "Nombre o razon social del vendedor"},
                    "tax_id": {"type": "string", "description": "RFC o tax ID del vendedor"},
                    "address": {"type": "string", "description": "Direccion del vendedor"}
                },
                "description": "Datos del vendedor/exportador"
            },
            "buyer": {
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "Nombre o razon social del comprador"},
                    "tax_id": {"type": "string", "description": "RFC o tax ID del comprador"}
                },
                "description": "Datos del comprador/importador"
            },
            "line_items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {"type": "string", "description": "Descripcion del producto"},
                        "quantity": {"type": "number", "description": "Cantidad"},
                        "unit_price": {"type": "number", "description": "Precio unitario en USD"},
                        "total": {"type": "number", "description": "Total de la linea en USD"}
                    }
                },
                "description": "Lineas de productos de la factura"
            },
            "total_amount": {
                "type": "number",
                "description": "Monto total de la factura en USD"
            },
            "currency": {
                "type": "string",
                "description": "Moneda de la factura (ej. USD, MXN, EUR)"
            }
        },
        "required": ["invoice_number", "total_amount", "line_items"]
    }
}

response = requests.post(
    "https://api.camtomx.com/api/v3/camtomdocs/extract",
    headers={"Authorization": "Bearer sk_tu_api_key"},
    params={"country_code": "MEX", "json_schema": "true"},
    files={"file_path": ("factura.pdf", open("factura.pdf", "rb"), "application/pdf")},
    data={"json_data": json.dumps(json_data)}
)

data = response.json()
print(f"Status: {data['status']}")
print(f"Factura: {data['document_data']['invoice_number']}")
print(f"Total: {data['document_data']['total_amount']}")
print(f"Paginas cobradas: {data['billed_pages']}")

const fs = require("fs");
const FormData = require("form-data");

const jsonData = {
  document_type: "invoice",
  document_description: "Factura comercial de importacion",
  json_response: {
    type: "object",
    properties: {
      invoice_number: {
        type: "string",
        description: "Numero de factura"
      },
      date: {
        type: "string",
        description: "Fecha de la factura en formato YYYY-MM-DD"
      },
      seller: {
        type: "object",
        properties: {
          name: { type: "string", description: "Nombre o razon social del vendedor" },
          tax_id: { type: "string", description: "RFC o tax ID del vendedor" }
        },
        description: "Datos del vendedor/exportador"
      },
      line_items: {
        type: "array",
        items: {
          type: "object",
          properties: {
            description: { type: "string", description: "Descripcion del producto" },
            quantity: { type: "number", description: "Cantidad" },
            unit_price: { type: "number", description: "Precio unitario en USD" },
            total: { type: "number", description: "Total de la linea en USD" }
          }
        },
        description: "Lineas de productos de la factura"
      },
      total_amount: {
        type: "number",
        description: "Monto total de la factura en USD"
      },
      currency: {
        type: "string",
        description: "Moneda de la factura (ej. USD, MXN, EUR)"
      }
    },
    required: ["invoice_number", "total_amount", "line_items"]
  }
};

const form = new FormData();
form.append("file_path", fs.createReadStream("factura.pdf"));
form.append("json_data", JSON.stringify(jsonData));

const response = await fetch(
  "https://api.camtomx.com/api/v3/camtomdocs/extract?country_code=MEX&json_schema=true",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer sk_tu_api_key",
      ...form.getHeaders()
    },
    body: form
  }
);

const data = await response.json();
console.log(`Status: ${data.status}`);
console.log(`Factura: ${data.document_data.invoice_number}`);
console.log(`Total: ${data.document_data.total_amount}`);
console.log(`Paginas cobradas: ${data.billed_pages}`);

curl -X POST "https://api.camtomx.com/api/v3/camtomdocs/extract?country_code=MEX&json_schema=true" \
  -H "Authorization: Bearer sk_tu_api_key" \
  -F "file_path=@factura.pdf" \
  -F 'json_data={
    "document_type": "invoice",
    "document_description": "Factura comercial de importacion",
    "json_response": {
      "type": "object",
      "properties": {
        "invoice_number": {"type": "string", "description": "Numero de factura"},
        "total_amount": {"type": "number", "description": "Monto total"},
        "currency": {"type": "string", "description": "Moneda"},
        "line_items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "description": {"type": "string"},
              "quantity": {"type": "number"},
              "unit_price": {"type": "number"},
              "total": {"type": "number"}
            }
          }
        }
      },
      "required": ["invoice_number", "total_amount", "line_items"]
    }
  }'

Ejemplo con URL de archivo

Si el archivo ya esta alojado en un servidor, puedes usar file_url en lugar de subir el archivo:

import requests
import json

json_data = {
    "document_type": "packing_list",
    "document_description": "Lista de empaque con pesos y dimensiones",
    "json_response": {
        "type": "object",
        "properties": {
            "total_packages": {"type": "number", "description": "Total de bultos"},
            "total_weight_kg": {"type": "number", "description": "Peso total en kg"}
        }
    }
}

response = requests.post(
    "https://api.camtomx.com/api/v3/camtomdocs/extract",
    headers={"Authorization": "Bearer sk_tu_api_key"},
    params={"country_code": "MEX"},
    data={
        "json_data": json.dumps(json_data),
        "file_url": "https://example.com/documentos/packing-list.pdf"
    }
)

curl -X POST "https://api.camtomx.com/api/v3/camtomdocs/extract?country_code=MEX" \
  -H "Authorization: Bearer sk_tu_api_key" \
  -F "file_url=https://example.com/documentos/packing-list.pdf" \
  -F 'json_data={"document_type":"packing_list","document_description":"Lista de empaque","json_response":{"type":"object","properties":{"total_packages":{"type":"number"}}}}'

Response

Campos de respuesta

string

Estado de la extraccion. Valores posibles: "success" o "error".

object

Objeto con los datos extraidos del documento, estructurado segun el JSON Schema proporcionado en json_data.json_response. Los campos coinciden con las propiedades definidas en tu schema.

number

Numero de paginas del documento que fueron cobradas. Este valor determina el costo en creditos de la operacion.

Ejemplo de respuesta exitosa

{
  "status": "success",
  "document_data": {
    "invoice_number": "INV-2024-00847",
    "date": "2024-11-15",
    "seller": {
      "name": "Acme Manufacturing Co.",
      "tax_id": "US-EIN-12-3456789",
      "address": "1234 Industrial Blvd, Los Angeles, CA 90001"
    },
    "buyer": {
      "name": "Importaciones del Norte S.A. de C.V.",
      "tax_id": "IDN200315ABC"
    },
    "line_items": [
      {
        "description": "Hydraulic pump model HP-200, industrial grade",
        "quantity": 10,
        "unit_price": 450.00,
        "total": 4500.00
      },
      {
        "description": "Replacement seals kit for HP-200",
        "quantity": 20,
        "unit_price": 25.00,
        "total": 500.00
      }
    ],
    "total_amount": 5000.00,
    "currency": "USD"
  },
  "billed_pages": 2
}

Schemas para documentos comunes

Show Factura comercial (Commercial Invoice)

{
  "document_type": "invoice",
  "document_description": "Factura comercial de importacion/exportacion",
  "json_response": {
    "type": "object",
    "properties": {
      "invoice_number": {"type": "string", "description": "Numero de factura"},
      "date": {"type": "string", "description": "Fecha de emision (YYYY-MM-DD)"},
      "incoterm": {"type": "string", "description": "Incoterm (EXW, FOB, CIF, etc.)"},
      "seller_name": {"type": "string", "description": "Razon social del vendedor"},
      "seller_tax_id": {"type": "string", "description": "RFC o tax ID del vendedor"},
      "buyer_name": {"type": "string", "description": "Razon social del comprador"},
      "buyer_tax_id": {"type": "string", "description": "RFC del comprador"},
      "line_items": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "hs_code": {"type": "string", "description": "Fraccion arancelaria si aparece"},
            "quantity": {"type": "number"},
            "unit": {"type": "string", "description": "Unidad de medida"},
            "unit_price": {"type": "number"},
            "total": {"type": "number"}
          }
        }
      },
      "subtotal": {"type": "number"},
      "total_amount": {"type": "number"},
      "currency": {"type": "string"},
      "country_of_origin": {"type": "string", "description": "Pais de origen de la mercancia"}
    },
    "required": ["invoice_number", "total_amount", "line_items"]
  }
}

Show Packing List

{
  "document_type": "packing_list",
  "document_description": "Lista de empaque con detalles de bultos, pesos y dimensiones",
  "json_response": {
    "type": "object",
    "properties": {
      "reference_number": {"type": "string", "description": "Numero de referencia del packing list"},
      "related_invoice": {"type": "string", "description": "Numero de factura relacionada"},
      "date": {"type": "string", "description": "Fecha (YYYY-MM-DD)"},
      "packages": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "package_number": {"type": "string", "description": "Numero de bulto o caja"},
            "description": {"type": "string"},
            "quantity": {"type": "number"},
            "net_weight_kg": {"type": "number", "description": "Peso neto en kg"},
            "gross_weight_kg": {"type": "number", "description": "Peso bruto en kg"},
            "dimensions_cm": {"type": "string", "description": "Dimensiones LxWxH en cm"}
          }
        }
      },
      "total_packages": {"type": "number", "description": "Total de bultos"},
      "total_net_weight_kg": {"type": "number"},
      "total_gross_weight_kg": {"type": "number"}
    },
    "required": ["packages", "total_packages"]
  }
}

Show Certificado de origen

{
  "document_type": "certificate_of_origin",
  "document_description": "Certificado de origen con datos del exportador, importador y productos",
  "json_response": {
    "type": "object",
    "properties": {
      "certificate_number": {"type": "string", "description": "Numero de certificado"},
      "exporter_name": {"type": "string", "description": "Nombre del exportador"},
      "exporter_address": {"type": "string"},
      "importer_name": {"type": "string", "description": "Nombre del importador"},
      "country_of_origin": {"type": "string", "description": "Pais de origen"},
      "country_of_destination": {"type": "string", "description": "Pais de destino"},
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "hs_code": {"type": "string"},
            "origin_criterion": {"type": "string", "description": "Criterio de origen aplicado"}
          }
        }
      },
      "treaty": {"type": "string", "description": "Tratado comercial aplicable (T-MEC, TLCUE, etc.)"},
      "issue_date": {"type": "string"},
      "expiration_date": {"type": "string"}
    },
    "required": ["certificate_number", "country_of_origin", "products"]
  }
}

Endpoints auxiliares

CamtomDocs tambien ofrece endpoints auxiliares que no consumen creditos:

Endpoint	Metodo	Descripcion
`/api/v3/camtomdocs/generate-schema`	POST	Genera un JSON Schema a partir de una descripcion en texto
`/api/v3/camtomdocs/generate-excel-schema`	POST	Genera un JSON Schema a partir de un archivo Excel
`/api/v3/camtomdocs/validate-schema`	POST	Valida un JSON Schema contra la especificacion Draft 7
`/api/v3/camtomdocs/validate-file`	POST	Valida un archivo y devuelve metadatos (tipo, paginas, tamano)

Errores comunes

Codigo	Causa	Solucion
`400`	Campo `json_data` ausente o `json_response` vacio	Verifica que `json_data` contenga un JSON valido con `document_type`, `document_description` y `json_response`
`401`	API key invalida o ausente	Revisa el header `Authorization`
`402`	Creditos insuficientes	Recarga creditos en app.camtomx.com
`422`	JSON Schema invalido o formato de archivo no soportado	Valida tu schema con `/api/v3/camtomdocs/validate-schema` antes de enviar
`429`	Limite de cuota excedido	Espera antes de reintentar
`502`	Error en el procesamiento de IA	Reintenta la peticion. Si persiste, contacta soporte

Para la referencia completa de errores, consulta codigos de error.

General

Autenticacion

Endpoints

Referencia

API extraccion documentos aduaneros

Request

Headers

Query parameters

Body parameters (multipart/form-data)

Estructura del campo `json_data`

Ejemplo de request

Ejemplo con URL de archivo

Response

Campos de respuesta

Ejemplo de respuesta exitosa

Schemas para documentos comunes

Endpoints auxiliares

Errores comunes

​Request

​Headers

​Query parameters

​Body parameters (multipart/form-data)

​Estructura del campo json_data

​Ejemplo de request

​Ejemplo con URL de archivo

​Response

​Campos de respuesta

​Ejemplo de respuesta exitosa

​Schemas para documentos comunes

​Endpoints auxiliares

​Errores comunes

Request

Headers

Query parameters

Body parameters (multipart/form-data)

Estructura del campo `json_data`

Ejemplo de request

Ejemplo con URL de archivo

Response

Campos de respuesta

Ejemplo de respuesta exitosa

Schemas para documentos comunes

Endpoints auxiliares

Errores comunes