> ## Documentation Index
> Fetch the complete documentation index at: https://docs.camtomx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API extraccion documentos aduaneros

> Endpoint REST para extraer datos de facturas, pedimentos y documentos de comercio exterior con JSON Schema. Ejemplos en Python, JS y cURL.

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>` |

<Note>
  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.
</Note>

### Query parameters

<ParamField query="country_code" type="string" required>
  Codigo de pais. Valores permitidos: `COL`, `MEX`, `USA`, `ARG`, `WORLD`.
</ParamField>

<ParamField query="json_schema" type="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.
</ParamField>

<ParamField query="f_u" type="boolean" default="false">
  Flag interno adicional.
</ParamField>

### Body parameters (multipart/form-data)

<ParamField body="json_data" type="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
</ParamField>

<ParamField body="file_path" type="file">
  El archivo a procesar. Formatos soportados: PDF, JPEG, PNG, TIFF, BMP, WEBP.

  Debe proporcionarse `file_path` o `file_url`, no ambos.
</ParamField>

<ParamField body="file_url" type="string">
  URL del documento a procesar. Alternativa a subir el archivo directamente.

  Debe proporcionarse `file_path` o `file_url`, no ambos.
</ParamField>

### Estructura del campo `json_data`

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

```json theme={null}
{
  "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.

<Tip>
  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.
</Tip>

### Ejemplo de request

El siguiente ejemplo extrae datos de una factura comercial:

<CodeGroup>
  ```python Python theme={null}
  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']}")
  ```

  ```javascript JavaScript theme={null}
  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}`);
  ```

  ```bash cURL theme={null}
  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"]
      }
    }'
  ```
</CodeGroup>

### Ejemplo con URL de archivo

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

<CodeGroup>
  ```python Python (con URL) theme={null}
  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"
      }
  )
  ```

  ```bash cURL (con URL) theme={null}
  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"}}}}'
  ```
</CodeGroup>

## Response

### Campos de respuesta

<ResponseField name="status" type="string">
  Estado de la extraccion. Valores posibles: `"success"` o `"error"`.
</ResponseField>

<ResponseField name="document_data" type="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.
</ResponseField>

<ResponseField name="billed_pages" type="number">
  Numero de paginas del documento que fueron cobradas. Este valor determina el costo en creditos de la operacion.
</ResponseField>

### Ejemplo de respuesta exitosa

```json theme={null}
{
  "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

<Expandable title="Factura comercial (Commercial Invoice)">
  ```json theme={null}
  {
    "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"]
    }
  }
  ```
</Expandable>

<Expandable title="Packing List">
  ```json theme={null}
  {
    "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"]
    }
  }
  ```
</Expandable>

<Expandable title="Certificado de origen">
  ```json theme={null}
  {
    "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"]
    }
  }
  ```
</Expandable>

## 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](https://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](/api/errors).