API Parser Factura y VEP

Inicio

La API recibe la URL publica de una imagen o PDF de factura, nota de credito, nota de debito, factura E o VEP argentino y devuelve un JSON con los datos detectados.

Credenciales

Cada cliente recibe un client_id y un secret. Ambos deben enviarse en cada solicitud.

X-Client-Id: CLIENT_ID
X-Client-Secret: CLIENT_SECRET
Content-Type: application/json

Alternativa con Authorization

Tambien se puede enviar el secret como Bearer, manteniendo el client id en header.

Authorization: Bearer CLIENT_SECRET
X-Client-Id: CLIENT_ID
Content-Type: application/json

Creditos

El servicio descuenta automaticamente 1 credito por cada uso. La respuesta exitosa incluye el saldo anterior y el saldo posterior.

{
  "credits": {
    "mode": "database",
    "consumed": 1,
    "balance_before": 100,
    "balance_after": 99,
    "movement_id": 10,
    "reference_id": "7b7f3e..."
  }
}

Si el cliente no tiene saldo disponible, la API no procesa la imagen y responde INSUFFICIENT_CREDITS.

Request

Enviar un JSON con la URL de la imagen o PDF. La URL debe ser accesible publicamente por HTTPS o HTTP.

{
  "image_url": "https://dominio.com/facturas/factura-a-0001.jpg"
}

Campos de entrada

Ejemplo curl

Factura

curl -X POST "https://vxtlogistica.com/api_reader/api_parser_factura.php" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: CLIENT_ID" \
  -H "X-Client-Secret: CLIENT_SECRET" \
  -d '{
    "image_url": "https://dominio.com/facturas/factura-a-0001.jpg"
  }'

VEP

curl -X POST "https://vxtlogistica.com/api_reader/api_parser_vep.php" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: CLIENT_ID" \
  -H "X-Client-Secret: CLIENT_SECRET" \
  -d '{
    "image_url": "https://dominio.com/veps/vep-04-2026.pdf"
  }'

Respuesta exitosa

{
  "success": true,
  "data": {
    "parsed": {
      "comprobante": {
        "tipo": "Factura",
        "letra": "A",
        "codigo_tipo": "001",
        "punto_venta": "0056",
        "numero": "00018287",
        "fecha_emision": "2026-07-03",
        "cae": "12345678901234",
        "cae_vencimiento": "2026-07-13",
        "moneda": "PES"
      },
      "emisor": {
        "razon_social": "EMPRESA SA",
        "cuit": "30111111118",
        "condicion_iva": "IVA Responsable Inscripto",
        "domicilio": "Av. Ejemplo 123"
      },
      "receptor": {
        "razon_social": "CLIENTE SRL",
        "cuit": "30222222229",
        "condicion_iva": "IVA Responsable Inscripto"
      },
      "items": [
        {
          "codigo": "SERV-001",
          "descripcion": "Servicio mensual",
          "cantidad": 1,
          "precio_unitario": 1000,
          "alicuota_iva": 21,
          "total": 1210
        }
      ],
      "iva": [
        {
          "alicuota": 21,
          "base_imponible": 1000,
          "importe": 210
        }
      ],
      "totales": {
        "importe_neto_gravado": 1000,
        "iva_total": 210,
        "total": 1210
      }
    },
    "source": {
      "image_url": "https://dominio.com/facturas/factura-a-0001.jpg"
    },
    "credits": {
      "mode": "database",
      "consumed": 1,
      "balance_before": 100,
      "balance_after": 99,
      "movement_id": 10,
      "reference_id": "7b7f3e..."
    }
  }
}

Lector de VEPs

El endpoint api_parser_vep.php lee VEPs, Volante Electronico de Pago, y devuelve los datos visibles del volante.

Respuesta VEP

{
  "success": true,
  "data": {
    "parsed": {
      "vep": {
        "numero": "123456789012",
        "estado": "Pendiente",
        "fecha_generacion": "2026-04-10",
        "fecha_vencimiento": "2026-04-30"
      },
      "contribuyente": {
        "cuit": "30111111118",
        "razon_social": "EMPRESA SA"
      },
      "organismo": {
        "nombre": "ARCA",
        "concepto": "Volante Electronico de Pago"
      },
      "obligacion": {
        "impuesto": "IVA",
        "periodo": "04/2026"
      },
      "importes": {
        "capital": 1000,
        "intereses_resarcitorios": 0,
        "total": 1000
      }
    },
    "source": {
      "image_url": "https://dominio.com/veps/vep-04-2026.pdf"
    },
    "credits": {
      "mode": "database",
      "consumed": 1,
      "balance_before": 100,
      "balance_after": 99,
      "movement_id": 11,
      "reference_id": "7b7f3e..."
    }
  }
}

Campos habituales

Evidencia opcional

Por defecto, la API no devuelve metadatos de evidencia para mantener compatibilidad con clientes existentes. Si el request trae include_evidence: true, agrega _meta y quality.

{
  "image_url": "https://dominio.com/facturas/factura-a-0001.jpg",
  "include_evidence": true
}

{
  "comprobante": {
    "punto_venta": "0056",
    "numero": "00018287",
    "_meta": {
      "punto_venta": {
        "confidence": 0.96,
        "evidence": "0056 - 00018287"
      },
      "numero": {
        "confidence": 0.94,
        "evidence": "0056 - 00018287"
      }
    }
  },
  "quality": {
    "overall_confidence": 0.91,
    "needs_review": false,
    "low_confidence_fields": []
  }
}

Campos parseados

La estructura puede variar segun el comprobante y la calidad de imagen. Los grupos esperados son:

Token OpenAI opcional

Normalmente no hace falta enviar token OpenAI: el servicio usa el token configurado en la API. Si el cliente necesita usar su propio token, puede enviarlo en el body.

{
  "image_url": "https://dominio.com/facturas/factura-a-0001.jpg",
  "openai_token": "sk-..."
}

Errores frecuentes

Ejemplo sin creditos

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "No hay creditos disponibles.",
    "credits": {
      "balance": 0,
      "required": 1
    }
  }
}

Recomendaciones

• Usar imagenes nitidas, sin cortes y con el comprobante completo visible.
• Evitar fotos torcidas, borrosas o con sombras fuertes.
• Subir la imagen a una URL temporal privada pero accesible para la API.
• No asumir que todos los campos van a venir siempre: validar campos opcionales en la integracion.
• Guardar la respuesta completa para auditoria si el sistema del cliente necesita trazabilidad.