Claude Code Plugins

Community-maintained marketplace

Feedback

airparser-api

@guillempuche/transports-pau-automatizaciones
0
0

Guia para integrar con el servicio de parsing de documentos Airparser via API, webhooks y Make.com. Usar cuando se configuren inboxes, esquemas de extraccion, o flujos de automatizacion para procesamiento de recibos.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name airparser-api
description Guia para integrar con el servicio de parsing de documentos Airparser via API, webhooks y Make.com. Usar cuando se configuren inboxes, esquemas de extraccion, o flujos de automatizacion para procesamiento de recibos.

Integracion API de Airparser

1) Vision General

Airparser es un servicio de parsing de documentos impulsado por LLM que extrae datos estructurados de emails, PDFs e imagenes. Esta skill cubre la integracion API, configuracion de esquemas de extraccion y flujos de automatizacion para el sistema de procesamiento de recibos de Transports Pau.

Nota: Airparser usa el termino "Inbox" para referirse a un parser/proyecto (equivalente al "Mailbox" de Parsio).

2) Autenticacion

Clave API

La clave API se almacena en el archivo .env del proyecto:

# Archivo: .env (ya configurado, incluido en .gitignore)
AIRPARSER_API_KEY=tu_clave_api_aqui

La clave API se encuentra en: https://app.airparser.com/account

Cargar variables de entorno

# Cargar .env antes de ejecutar comandos
source .env

# Verificar que esta cargada
echo $AIRPARSER_API_KEY

URL Base

https://api.airparser.com

Header de autenticacion

Usar X-API-Key en el header HTTP:

source .env && curl -X GET https://api.airparser.com/inboxes/ \
  -H "X-API-Key: $AIRPARSER_API_KEY"

3) Conceptos Clave

Concepto Descripcion
Inbox Proyecto/parser que recibe documentos. Tiene email propio
Document Documento recibido (email, PDF, imagen)
Extraction Schema Definicion de campos a extraer usando descripcion en lenguaje natural
Webhook Endpoint para recibir datos parseados en tiempo real (con firma de seguridad)

4) Referencia API - Inboxes

Listar Inboxes

source .env && curl -X GET https://api.airparser.com/inboxes \
  -H "X-API-Key: $AIRPARSER_API_KEY"

Eliminar Inbox

source .env && curl -X DELETE https://api.airparser.com/inboxes/<inbox_id> \
  -H "X-API-Key: $AIRPARSER_API_KEY"

Obtener Inbox ID

El Inbox ID se encuentra en la URL del navegador cuando abres el inbox:

https://app.airparser.com/inboxes/<INBOX_ID>/documents

O via API listando los inboxes.

5) Referencia API - Documentos

Subir documento para parsear

Formatos soportados: EML, PDF, HTML, TXT, MD, DOCX y mas Tamano maximo: 20MB

source .env && curl -X POST https://api.airparser.com/inboxes/<inbox_id>/upload \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -F "file=@recibo.pdf"

Con metadata opcional (se incluira en el JSON parseado como __meta__):

source .env && curl -X POST https://api.airparser.com/inboxes/<inbox_id>/upload \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -F "file=@recibo.pdf" \
  -F 'meta={"conductor_id": "123", "vehiculo": "1234-ABC"}'

Retorna: Document ID

Obtener documento con datos parseados

source .env && curl -X GET https://api.airparser.com/docs/<document_id>/extended \
  -H "X-API-Key: $AIRPARSER_API_KEY"

Nota: Se recomienda usar webhooks para recibir datos en tiempo real en lugar de polling.

Listar documentos

source .env && curl -X GET "https://api.airparser.com/inboxes/<inbox_id>/docs?page=1" \
  -H "X-API-Key: $AIRPARSER_API_KEY"

Con filtros:

source .env && curl -X GET "https://api.airparser.com/inboxes/<inbox_id>/docs?page=1&from=2025-01-01&to=2025-12-31&statuses[]=parsed" \
  -H "X-API-Key: $AIRPARSER_API_KEY"

Parametros:

  • page (number): Numero de pagina
  • from (string): Fecha desde (YYYY-MM-DD)
  • to (string): Fecha hasta (YYYY-MM-DD)
  • q (string): Busqueda
  • statuses (array): Estados: importing, parsed, fail, new, quota, parsing, exception

6) Referencia API - Extraction Schema

Crear/Actualizar esquema de extraccion

source .env && curl -X POST https://api.airparser.com/inboxes/<inbox_id>/schema \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "type": "scalar",
        "data": {
          "name": "total_amount",
          "description": "El importe total del recibo",
          "type": "decimal",
          "default_value": "0.00"
        }
      }
    ]
  }'

Tipos de campos

1. Scalar (valores simples)

{
  "type": "scalar",
  "data": {
    "name": "nombre_campo",
    "description": "Descripcion para el LLM",
    "type": "string|integer|decimal|boolean",
    "default_value": "valor_por_defecto"
  }
}

Tipos soportados: string, integer, decimal, boolean

2. List (arrays de objetos)

{
  "type": "list",
  "data": {
    "name": "lineas",
    "description": "Lista de items",
    "attributes": [
      {
        "name": "producto",
        "description": "Nombre del producto",
        "type": "string",
        "default_value": ""
      },
      {
        "name": "cantidad",
        "description": "Cantidad",
        "type": "integer",
        "default_value": "0"
      }
    ]
  }
}

3. Object (objeto unico)

{
  "type": "object",
  "data": {
    "name": "direccion",
    "description": "Direccion de envio",
    "attributes": [
      {
        "name": "calle",
        "description": "Calle",
        "type": "string",
        "default_value": ""
      }
    ]
  }
}

4. Enum (valores predefinidos)

{
  "type": "enum",
  "data": {
    "name": "estado",
    "description": "Estado del pedido",
    "values": ["pendiente", "procesando", "enviado", "entregado"]
  }
}

Clonar esquema entre inboxes

source .env && curl -X POST https://api.airparser.com/inboxes/<source_inbox_id>/schema-clone \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"destination_inbox_id": "<target_inbox_id>"}'

Reglas de validacion

  • Nombres de campo: 1-100 caracteres, solo letras minusculas, numeros y guiones bajos
  • Nombres unicos dentro del esquema
  • Descripciones: max 3000 caracteres
  • Valores por defecto: max 400 caracteres
  • Valores de enum: unicos, 1-100 caracteres cada uno

7) Webhooks

Configurar webhook (via UI)

  1. Ir a Integrations → Webhooks en Airparser
  2. Seleccionar "Create a webhook"
  3. Pegar la URL de destino

Airparser envia datos via POST cada vez que se parsea un documento.

Verificar firma del webhook (seguridad)

Airparser firma cada payload con un Signing Secret. La firma se envia en el header airparser-signature.

Pseudocodigo:

signature = base64(HMAC_SHA256(payload_binary, secret))

Node.js ejemplo:

const crypto = require('crypto');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const SIGNING_SECRET = "<your_secret_key>";
  const signature1 = req.get('airparser-signature');
  const signature2 = crypto
    .createHmac('sha256', SIGNING_SECRET)
    .update(req.rawBody)
    .digest('base64');

  if (signature1 === signature2) {
    // Firma valida
    res.sendStatus(200);
  } else {
    // Firma invalida - rechazar
    res.sendStatus(403);
  }
});

PHP ejemplo:

$payload = @file_get_contents('php://input');
// Procesar payload...
http_response_code(200);

8) Esquema para Recibos Transports Pau

Esquema de extraccion configurado en esquema-airparser.json:

{
  "fields": [
    {
      "type": "scalar",
      "data": {
        "name": "razon_social",
        "description": "Nombre del comercio/empresa del recibo. Recortar espacios, preservar acentos.",
        "type": "string",
        "default_value": ""
      }
    },
    {
      "type": "scalar",
      "data": {
        "name": "fecha",
        "description": "Fecha de transaccion mas cercana al total. Convertir DD/MM/YYYY o DD-MM-YYYY a YYYY-MM-DD.",
        "type": "string",
        "default_value": ""
      }
    },
    {
      "type": "scalar",
      "data": {
        "name": "matricula",
        "description": "Matricula espanola del vehiculo si aparece. Formato normalizado. Vacio si no encontrada.",
        "type": "string",
        "default_value": ""
      }
    },
    {
      "type": "scalar",
      "data": {
        "name": "importe",
        "description": "Total a pagar en EUR. Buscar TOTAL, TOTAL A PAGAR. Usar el total final si hay varios.",
        "type": "decimal",
        "default_value": "0.00"
      }
    },
    {
      "type": "enum",
      "data": {
        "name": "categoria",
        "description": "Clasificar por palabras clave: gasoil (gasoil/diesel/fuel), peajes (peaje/toll/autopista), limpieza_vehiculos (lavado/limpieza), otros (default).",
        "values": ["gasoil", "peajes", "limpieza_vehiculos", "otros"]
      }
    },
    {
      "type": "enum",
      "data": {
        "name": "pago",
        "description": "empresa = facturado a Transports Pau o tarjeta empresa. transportista = pagado por conductor. Vacio si ambiguo.",
        "values": ["empresa", "transportista"]
      }
    }
  ]
}

Aplicar esquema via API

source .env && curl -X POST https://api.airparser.com/inboxes/<inbox_id>/schema \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @esquema-airparser.json

9) Integracion con Make.com

Trigger: Watch Document Parsed

  1. Anadir modulo Airparser: "Watch Document Parsed"
  2. Conectar cuenta Airparser (email/password)
  3. Seleccionar inbox

Action: Upload a Document for Parsing

Importa un documento externo a Airparser para parsearlo.

Flujo de procesamiento

Trigger Airparser (doc.parsed)
    |
    v
Text Parser (normalizar matricula)
    |
    v
Text Parser (normalizar fecha)
    |
    v
Set Variable (mapeo categoria)
    |
    v
Google Drive (subir original)
    |
    v
Google Sheets (anadir fila)

Si usaste Google Sign Up

Para conectar con Make necesitas credenciales email/password:

  1. Cerrar sesion de Airparser
  2. Ir a https://app.airparser.com/forgot
  3. Crear nueva password via email

10) Ejemplo: Flujo completo

# 1. Cargar credenciales
source .env

# 2. Listar inboxes para obtener ID
curl -X GET https://api.airparser.com/inboxes \
  -H "X-API-Key: $AIRPARSER_API_KEY"

# Respuesta: [{"_id": "abc123", "name": "Recibos", ...}]

# 3. Aplicar esquema de extraccion
curl -X POST https://api.airparser.com/inboxes/abc123/schema \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -H "Content-Type: application/json" \
  -d @esquema-airparser.json

# 4. Subir documento de prueba
curl -X POST https://api.airparser.com/inboxes/abc123/upload \
  -H "X-API-Key: $AIRPARSER_API_KEY" \
  -F "file=@recibo_gasoil.pdf" \
  -F 'meta={"matricula": "1234-ABC"}'

# Respuesta: "<document_id>"

# 5. Obtener datos parseados (o usar webhook)
curl -X GET https://api.airparser.com/docs/<document_id>/extended \
  -H "X-API-Key: $AIRPARSER_API_KEY"

11) Mapeo de Campos para Transports Pau

Keywords de Categoria (CA/ES)

Categoria Keywords
gasoil gasoil, diesel, combustible, fuel, carburant
peajes peatge, peaje, autopista, toll, via-t, telepeaje
limpieza_vehiculos rentat, lavado, neteja, limpieza, autolavado
otros (fallback por defecto)

Mapeo Tipo de Pago

Tipo Keywords
empresa targeta empresa, tarjeta empresa, compte, company card
transportista efectivo, cash, efectiu, targeta personal, tarjeta personal

Normalizacion de Matricula

Formato entrada: 1234 ABC, 1234-ABC, 1234ABC Formato salida: 1234-ABC

Regex: ^(\d{4})-?([A-Z]{3})$

12) Manejo de Errores

Codigo Significado Accion
401 API key invalida Verificar AIRPARSER_API_KEY en .env
404 Inbox/documento no encontrado Verificar IDs
429 Limite de peticiones Esperar y reintentar
500 Error del servidor Reintentar

13) Recursos