Zaptic

Desarrolladores

Developers

Referencia de la API de Procesamiento: envía el texto extraído del documento, define campos, recibe datos estructurados y una puntuación opcional. La extracción y la puntuación están respaldadas por Google Gemini.

Antes de integrar: obtén una licencia

El acceso a la API requiere una licencia de Zaptic vinculada a tu saldo de créditos. Puedes comenzar con una licencia gratuita o comprar un paquete de créditos en nuestra tienda; después del registro o del pago, recibirás una clave de licencia para enviar en cada cuerpo de solicitud.

Ver planes (incluyendo licencia gratuita)

Cómo funciona la API de Procesamiento

  1. Obtener una licencia

    Solicita una licencia gratuita o compra un paquete de créditos en la página de precios.

  2. Extraer localmente

    Analiza el PDF/DOC por tu cuenta. Zaptic no acepta cargas de archivos, solo el texto/contenido dentro de ellos.

  3. POST /process

    Envía la licencia, origen, requested_fields y extracted_content como JSON.

  4. Usar la respuesta

    Asigna los valores extraídos a formularios, ATS o a tu base de datos. Las puntuaciones aparecen cuando se envía scoring_criteria.

Créditos: Cada solicitud cuesta 1 crédito. Añadir scoring_criteria cuesta 1 crédito adicional. Las solicitudes idénticas repetidas se sirven desde la caché y no vuelven a consumir créditos.

Endpoint

Método
POST
URL
https://api.zaptic.io/json-api/zaptic/v1/process
Cabeceras (Headers)
Content-Type: application/json

Cuerpo de la solicitud (Request body)

Campo Requerido Descripción
license Sí Clave de licencia de tu paquete comprado.
origin Sí Identificador del llamador, por ejemplo, ats_connector o el slug de tu producto.
requested_fields Sí Schema of fields to extract. Each entry has label, type (text, number, array, or list), and subfields when type is array or list. See Field schemas.
extracted_content Sí Texto plano tomado del interior del PDF/DOC, no el archivo binario.
domain No Host o dominio del sitio asociado con la integración.
lang No Sugerencia de configuración regional (locale), por ejemplo, en_US o es_ES.
scoring_criteria No Criterios opcionales (requisito + peso 1–10) para que Gemini pueda calificar el documento según tus reglas (+1 crédito).

Ejemplo de solicitud

Ejemplo de extracción de CV con campos de lista anidados y puntuación opcional. Los valores a continuación son ficticios: reemplaza YOUR_LICENSE_KEY y usa tu propio contenido. 

{
    "license": "YOUR_LICENSE_KEY",
    "domain": "app.example-hr.io",
    "origin": "ats_connector",
    "lang": "en_US",
    "scoring_criteria": {
        "techstack": {
            "requirement": "Hands-on experience with Node.js, TypeScript, and REST API design. Cloud deployment experience preferred.",
            "weight": 10
        },
        "seniority": {
            "requirement": "Minimum 4 years in backend or full-stack roles with ownership of production services.",
            "weight": 8
        },
        "location": {
            "requirement": "Eligible to work in the EU or within CET business hours.",
            "weight": 6
        }
    },
    "requested_fields": {
        "name": {
            "label": "Full name",
            "type": "text"
        },
        "job_title": {
            "label": "Job title / role",
            "type": "text"
        },
        "professional_summary": {
            "label": "Professional summary",
            "type": "text"
        },
        "profile_type": {
            "label": "Profile type",
            "type": "text"
        },
        "age": {
            "label": "Age",
            "type": "text"
        },
        "date_of_birth": {
            "label": "Date of birth",
            "type": "text"
        },
        "projects": {
            "label": "Projects",
            "type": "array",
            "subfields": {
                "name": {
                    "label": "Name",
                    "type": "text"
                },
                "description": {
                    "label": "Description",
                    "type": "text"
                }
            }
        },
        "work_experience": {
            "label": "Work experience",
            "type": "array",
            "subfields": {
                "company": {
                    "label": "Company",
                    "type": "text"
                },
                "years": {
                    "label": "Years",
                    "type": "text"
                },
                "tasks": {
                    "label": "Tasks",
                    "type": "array",
                    "subfields": {
                        "task": {
                            "label": "Task",
                            "type": "text"
                        }
                    }
                }
            }
        },
        "skills": {
            "label": "Skills",
            "type": "list",
            "subfields": {
                "item": {
                    "label": "Skill",
                    "type": "text"
                }
            }
        },
        "education": {
            "label": "Education",
            "type": "text"
        }
    },
    "extracted_content": "Jordan Ellis\r\nSenior Backend Engineer | API Platforms & Integrations\r\nBerlin, Germany | jordan.ellis@example-hr.io | https://github.com/jellis-dev\r\n\r\nProfessional summary\r\nBackend engineer with 6+ years building SaaS APIs, workflow automation, and document pipelines. Comfortable with Node.js, PostgreSQL, and event-driven architectures.\r\n\r\nFeatured projects\r\nAtlas Forms — No-code intake builder for enterprise HR teams.\r\nLedger Lite — Lightweight billing microservice for subscription products.\r\nDevCast Brief — Internal podcast summarizing platform release notes.\r\n\r\nExperience\r\nNorthwind Labs — Senior Backend Engineer (2023 – Present)\r\nDesigned REST and webhook APIs consumed by partner ATS tools. Led migration to structured logging and idempotent job queues.\r\n\r\nCloudSphere Inc — Software Engineer (2020 – 2023)\r\nBuilt document ingestion services and PDF text extraction workers. Integrated third-party OCR providers.\r\n\r\nSkills: Node.js, TypeScript, PostgreSQL, REST, webhooks, Docker, Redis, GitHub Actions, AWS, PDF parsing, API design, event-driven architecture.\r\n\r\nEducation\r\nB.Sc. Computer Science — Rhine Valley University of Applied Sciences"
}

Ejemplo de respuesta

Las claves bajo data.extracted_fields reflejan tus requested_fields. Cuando se envió scoring_criteria, data.internal_analysis incluye total_score y el resumen.

Propiedad Descripción
status success o error.
version Versión del esquema de respuesta de la API.
data.extracted_fields Valores estructurados para cada campo solicitado.
data.internal_analysis Presente cuando se envió scoring_criteria: total_score y el resumen. 
{
    "status": "success",
    "version": "1.0",
    "data": {
        "extracted_fields": {
            "name": "Jordan Ellis",
            "country": "Germany",
            "email": "jordan.ellis@example-hr.io",
            "github": "https://github.com/jellis-dev",
            "projects": [
                {
                    "name": "Atlas Forms",
                    "description": "No-code intake builder for enterprise HR teams"
                },
                {
                    "name": "Ledger Lite",
                    "description": "Lightweight billing microservice for subscription products"
                },
                {
                    "name": "DevCast Brief",
                    "description": "Internal podcast summarizing platform release notes"
                }
            ],
            "work_experience": [
                {
                    "company": "Northwind Labs",
                    "years": "2023 – Present",
                    "tasks": [
                        {
                            "task": "Designed REST and webhook APIs for partner ATS integrations."
                        },
                        {
                            "task": "Led migration to structured logging and idempotent background jobs."
                        },
                        {
                            "task": "Owned PostgreSQL schema changes and performance reviews."
                        }
                    ]
                },
                {
                    "company": "CloudSphere Inc",
                    "years": "2020 – 2023",
                    "tasks": [
                        {
                            "task": "Built document ingestion services and PDF text extraction workers."
                        },
                        {
                            "task": "Integrated third-party OCR providers behind a unified adapter layer."
                        }
                    ]
                }
            ],
            "skills": [
                "Node.js",
                "TypeScript",
                "PostgreSQL",
                "REST",
                "webhooks",
                "Docker",
                "Redis",
                "GitHub Actions",
                "AWS",
                "PDF parsing",
                "API design",
                "event-driven architecture"
            ]
        },
        "internal_analysis": {
            "total_score": 84,
            "summary": "Jordan is a strong backend candidate with relevant API and document-pipeline experience. Tech stack and seniority align well with the role; location fit is acceptable for CET collaboration."
        }
    }
}

Ejemplos de código

La licencia y la carga útil (payload) viajan en el cuerpo JSON.

cURL

curl -X POST "https://api.zaptic.io/json-api/zaptic/v1/process" \
  -H "Content-Type: application/json" \
  -d @payload.json

JavaScript (fetch)

const processUrl = "https://api.zaptic.io/json-api/zaptic/v1/process";

const payload = {
  license: process.env.ZAPTIC_LICENSE,
  domain: "app.example-hr.io",
  origin: "ats_connector",
  lang: "en_US",
  requested_fields: {
    name: { label: "Full name", type: "text" },
    email: { label: "Email", type: "text" },
  },
  extracted_content: documentTextFromYourParser,
};

const response = await fetch(processUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(payload),
});

const body = await response.json();
if (body.status !== "success") {
  throw new Error(body.message ?? "Zaptic process failed");
}

const fields = body.data.extracted_fields;
const analysis = body.data.internal_analysis;
console.log(fields.name, analysis?.total_score);

Python

import os
import requests

PROCESS_URL = "https://api.zaptic.io/json-api/zaptic/v1/process"

payload = {
    "license": os.environ["ZAPTIC_LICENSE"],
    "domain": "app.example-hr.io",
    "origin": "ats_connector",
    "lang": "en_US",
    "requested_fields": {
        "name": {"label": "Full name", "type": "text"},
        "email": {"label": "Email", "type": "text"},
    },
    "extracted_content": document_text_from_your_parser,
}

response = requests.post(
    PROCESS_URL,
    headers={"Content-Type": "application/json"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
body = response.json()

if body.get("status") != "success":
    raise RuntimeError(body.get("message", "Zaptic process failed"))

fields = body["data"]["extracted_fields"]
analysis = body["data"].get("internal_analysis")
print(fields["name"], analysis.get("total_score") if analysis else None)

PHP

$processUrl = "https://api.zaptic.io/json-api/zaptic/v1/process";

$payload = [
    "license"           => getenv( "ZAPTIC_LICENSE" ) ?: "",
    "domain"            => "app.example-hr.io",
    "origin"            => "ats_connector",
    "lang"              => "en_US",
    "requested_fields"  => [
        "name" => [
            "label" => "Full name",
            "type"  => "text",
        ],
        "email" => [
            "label" => "Email",
            "type"  => "text",
        ],
    ],
    "extracted_content" => $documentTextFromYourParser,
];

$ch = curl_init( $processUrl );
curl_setopt_array( $ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [ "Content-Type: application/json" ],
    CURLOPT_POSTFIELDS     => json_encode( $payload ),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 120,
] );

$responseBody = curl_exec( $ch );
$httpCode = (int) curl_getinfo( $ch, CURLINFO_HTTP_CODE );
curl_close( $ch );

if ( $responseBody === false || $httpCode >= 400 ) {
    throw new RuntimeException( "Zaptic process request failed (HTTP {$httpCode})" );
}

$body = json_decode( $responseBody, true );

if ( ( $body["status"] ?? "" ) !== "success" ) {
    throw new RuntimeException( $body["message"] ?? "Zaptic process failed" );
}

$extractedFields = $body["data"]["extracted_fields"] ?? [];
$internalAnalysis = $body["data"]["internal_analysis"] ?? null;

Esquemas de campo

Define qué debe extraer Zaptic de extracted_content. Tanto la extracción de campos como la puntuación opcional se realizan a través de Google Gemini: tú envías el esquema y Gemini asigna el texto a tu estructura.

Impulsado por Gemini: Toda la interpretación del texto del documento (extracción estructurada y puntuación según tus criterios) es realizada por modelos de Google Gemini en la infraestructura de Zaptic.

requested_fields

An object whose keys are your field names. Every field must include label and type. There are four types:

Tipo subfields Forma de la respuesta
text No utilizado Un único valor de cadena de texto.
number No utilizado A single numeric value (JSON number).
array Requerido Una matriz (array) de objetos: un objeto por bloque repetido, con claves que coinciden con los subcampos.
list Requerido Una matriz plana de cadenas de texto (lista simple), no objetos.

text

Valores escalares: nombres, correos electrónicos, resúmenes, fechas, etc. 

"name": {
  "label": "Full name",
  "type": "text"
}

number

Numeric values: amounts, counts, years of experience, percentages, etc. Returned as a JSON number, not a string. 

"years_experience": {
  "label": "Years of experience",
  "type": "number"
}

Example response (number):

"years_experience": 8

array

Repeating structured blocks. You must provide subfields with at least one child field. Each subfield can be text, number, array, or list—so you can nest array or list inside array (or list) without limit. 

"work_experience": {
  "label": "Work experience",
  "type": "array",
  "subfields": {
    "company": { "label": "Company", "type": "text" },
    "years": { "label": "Years", "type": "number" },
    "tasks": {
      "label": "Tasks",
      "type": "array",
      "subfields": {
        "task": { "label": "Task", "type": "text" }
      }
    }
  }
}

Ejemplo de respuesta (array → objetos):

"tasks": [
  { "task": "Built document ingestion services and PDF text extraction workers." },
  { "task": "Integrated third-party OCR providers behind a unified adapter layer." }
]

list

Una lista simple de valores del documento (habilidades, etiquetas, viñetas). Todavía se requiere subfields; normalmente un hijo de tipo texto (por ejemplo, item) cuyos valores se aplanan en una matriz de cadenas en la respuesta. 

"skills": {
  "label": "Skills",
  "type": "list",
  "subfields": {
    "item": { "label": "Skill", "type": "text" }
  }
}

Ejemplo de respuesta (list → matriz de cadenas):

"skills": [
  "Node.js",
  "TypeScript",
  "PostgreSQL",
  "REST",
  "webhooks"
]

Dentro de los subcampos puedes encadenar más nodos de tipo matriz o lista a cualquier profundidad (por ejemplo, matriz de empresas, cada una con una matriz de tareas, cada una con listas anidadas).

scoring_criteria

Objeto opcional de reglas para que Gemini pueda leer todo el extracted_content, evaluar qué tan bien coincide con cada regla y devolver una puntuación junto con un resumen en data.internal_analysis. Ideal para la contratación: compara CVs con los requisitos del puesto, pila tecnológica, antigüedad o ubicación.

Cada criterio es una clave (tu slug) con:

  • requirement — Descripción en lenguaje sencillo de lo que estás buscando en el documento.
  • weight — Número entero del 1 al 10: qué tan importante es este criterio al calcular la puntuación general (10 = la más alta).

Enviar scoring_criteria cuesta un crédito adicional por solicitud. La respuesta incluye total_score y un breve resumen que explica la coincidencia. 

"scoring_criteria": {
  "techstack": {
    "requirement": "Hands-on experience with Node.js, TypeScript, and REST API design.",
    "weight": 10
  },
  "seniority": {
    "requirement": "Minimum 4 years in backend or full-stack roles.",
    "weight": 8
  },
  "location": {
    "requirement": "Eligible to work in the EU or within CET business hours.",
    "weight": 6
  }
}
"internal_analysis": {
  "total_score": 84,
  "summary": "Strong backend candidate; tech stack and seniority align well with the role."
}
  • Nunca expongas tu clave de licencia: usa variables de entorno o almacenamiento de secretos.
  • Las coincidencias en caché (cache hits) en cargas útiles duplicadas no descuentan créditos.
  • Need a license? Browse credit packs.