Nivel gratuito (DAT-FREE)

Los cupos son de la cuenta, no de la llave. Todas las llaves de una cuenta descuentan del mismo contador, así que crear otra llave no suma cupo. La ficha GET /v5/entities/{id}?include=DAT-FREE cuesta 0 créditos, sin cargo base, para toda llave y con cualquier saldo. Con saldo descuenta de ese mismo contador con un tope de 500 al día y 10,000 al mes; el resto de los códigos (también CHK-BIN y DAT-RESOLVE) se cobra del saldo. El tope sigue a la billetera al momento de la llamada: una cuenta que gastó 30 hoy sin saldo y recarga tiene 470 fichas más hoy.

El nivel 0 da el menú pero no los booleanos: un agente sin llave aprende «Panadata tiene datos judiciales, inmobiliarios y de comercio sobre esta sociedad, constituida en 1914 y vigente». Los booleanos detrás cuestan un email confirmado. Los registros cuestan créditos.

{
  "id": "pa_own_4629361", "country": "panama",
  "nombre": "CERVECERÍA NACIONAL HOLDING, S.A.",
  "nivel": "DAT-FREE",
  "existe": true, "vigente": true, "suspendida": false,
  "tipo": "organizacion", "anio_constitucion": 1914,
  "directores": "10+",
  "tiene_judicial": true, "moroso_css": false, "contrata_con_estado": false,
  "en_planilla_estatal": false,
  "inmuebles": "3-9", "comercio_exterior": true, "noticias": true,
  "codigos_con_datos": ["DAT-ASSET","DAT-BIZ","DAT-BUSINESS","DAT-DOC","DAT-NEWS","DAT-REALESTATE","DAT-REGISTRY","DAT-RISK","DAT-TRADE"],
  "actualizado": "2026-09",
  "siguiente_paso": {"para_ver_los_registros": "https://platform.panadata.net/docs/precios", "tokens_dat_core": 0.66}
}

Sin llave (nivel 0) la ficha se reduce a id, country, nombre, nivel, existe, vigente, suspendida, tipo, anio_constitucion, codigos_con_datos, actualizado y siguiente_paso; los booleanos y rangos aparecen con llave gratuita. Para una persona natural la ficha es la misma menos directores, contrata_con_estado y comercio_exterior (y con vigente, suspendida y anio_constitucion en null, que son atributos de sociedad), con tiene_judicial, moroso_css, en_planilla_estatal, inmuebles y noticias como campos principales. Un booleano o un rango en null significa «no computado», no «no tiene».

Hoy la ficha no trae score ni pep_local: entran cuando exista el Operating Score calibrado 0–100 y la bandera PEP a nivel de entidad. Los booleanos y rangos se calculan sobre los mismos contadores que DAT-CORE ya carga; codigos_con_datos es la lista de códigos del catálogo que devolverían registros para esa entidad (nunca incluye DAT-ALL).

Estimador. Con llave gratuita POST /v5/resolve/batch con with_presence: true devuelve solo agregados: {country, count, estimator: true, summary{rows, resolved_exact, ambiguous, unresolved, invalid, homonyms_p50/p90/max, presence{DAT-…: n}}, note}, sin results[], sin ids ni candidatos. Hasta 100 filas por llamada; las filas válidas descuentan de la cuota del estimador (5,000/mes, 402 estimator_rows_exhausted al agotarse), nunca de los 30/día ni de los 500/mes. Sirve para cotizar un barrido: cuántas filas resuelven y qué códigos tienen datos. La resolución fila por fila es el resolve/batch pagado, o el gratuito sin with_presence (10 filas, dentro del cupo). Con llave pagada la misma llamada devuelve results[] por fila más summary.presence.

Cabeceras y cupo. Toda respuesta del nivel 1 (2xx y 429) trae X-Panadata-Tier: free, X-Panadata-Free-Remaining-Today y X-Panadata-Free-Remaining-Month (el estimador suma X-Panadata-Free-Estimator-Rows-Remaining). La ficha DAT-FREE de una cuenta con saldo trae X-Panadata-Free-Remaining-Today y X-Panadata-Free-Remaining-Month contra los topes con saldo (500 al día · 10,000 al mes), sin X-Panadata-Tier; su dry_run cotiza would_charge: "0" con el mismo bloque free_tier. El 429 free_tier_limit llega solo cuando used + filas > limit y dice used, remaining y requested (un lote de 7 sí pasa con 23/30) junto con reset_at y una cabecera Retry-After en segundos. Un identificador con formato irreconocible sale como outcome: invalid en el lote (no cuenta ni cobra) y como 400 invalid_identifier en POST /v5/resolve, que además acepta top (1..10).

Zonas horarias. Los contadores del nivel 1 (30 o 100/día, 500 o 1,000/mes, estimador) se cortan por día y mes UTC; el reset_at de los 429 es la próxima medianoche o el próximo día 1 en UTC. El presupuesto global del nivel 0 se corta a medianoche de Panamá (America/Panama, UTC−5, sin horario de verano). Son dos calendarios distintos: a las 03:00Z del día 22 el nivel 1 ya está en su día 22 y el nivel 0 sigue en su día 21.

dry_run=1 es gratis en los tres niveles. Sin llave, con llave gratuita o con saldo, cualquier ruta cobrable con ?dry_run=1 devuelve {dry_run, would_charge, product_codes, credits} para cualquier código pedido (también los pagados), sin cobrar y sin consumir contadores ni presupuesto: una llave gratuita puede cotizar ?include=DAT-ALL&dry_run=1 antes de cargar créditos. El candado free_tier_code_locked aplica solo a la llamada real. En el detalle, ?inline_limit=1..100 (default 10) acota las listas de cada sección para cualquier llave; DAT-FREE no lleva listas, así que no le afecta.

El dry_run de una llave gratuita cotiza en entidades, no en créditos. Esa llave nunca paga, así que su cotización trae would_charge: "0" y credits: 0, más un bloque free_tier con lo que la llamada real le haría al cupo. Leer los contadores no los incrementa: cotizar nunca cuenta. Las cifras de primer nivel son las del período del presupuesto y month trae las del mes:

• budget: daily (el cupo de 30/día y 500/mes, o 100 y 1,000 con dominio corporativo) o estimator (resolve/batch con with_presence, que descuenta filas del estimador, 5,000/mes, y no toca el cupo diario).
• counts_as: cuántas entidades o filas contaría la llamada real (las filas inválidas cuentan 0). period, used, limit y remaining dan el estado del período.
• would_exceed: true cuando el día o el mes no alcanzan, exactamente cuando la llamada real recibiría el 429. En ese caso llegan también exceeded_period, would_status (429, o 402 para el estimador), code y reset_at.
• locked: true con locked_codes: el código pedido está fuera del nivel gratuito. La cotización conserva el precio en créditos (lo que costaría con saldo) y la llamada real sería 403 free_tier_code_locked, sin contar nada.
• Si los contadores no se pueden leer, used, remaining y would_exceed vienen en null; la respuesta sigue siendo 200. El dry_run también trae las cabeceras X-Panadata-Free-Remaining-Today y X-Panadata-Free-Remaining-Month.

Ejemplo ilustrativo: un POST /v5/resolve/batch?dry_run=1 de 8 filas con 23 de 30 entidades usadas hoy.

{"dry_run": true, "would_charge": "0", "credits": 0, "product_codes": ["DAT-RESOLVE"],
 "free_tier": {"budget": "daily", "counts_as": 8, "period": "day", "used": 23, "limit": 30, "remaining": 7,
   "month": {"used": 141, "limit": 500, "remaining": 359},
   "would_exceed": true, "exceeded_period": "day", "would_status": 429, "code": "free_tier_limit",
   "reset_at": "2026-09-24T00:00:00+00:00", "upgrade_url": "https://platform.panadata.net/facturacion"}}

Cuando se agota: 429 con code: free_tier_limit (nivel 1: period, limit, used, remaining, requested + Retry-After) o code: public_budget_exhausted (nivel 0), ambos con reset_at y upgrade_url (con llave, la página de compra https://platform.panadata.net/facturacion; sin llave, esta misma página, https://platform.panadata.net/docs/dat-free); cuando se pide un código fuera del nivel: 403 con code: free_tier_code_locked, locked_codes y free_tier_codes; una llave vencida: 401 con code: key_expired. El MCP lee esos campos y muestra el paso siguiente en vez de un error. Los cuerpos completos están en la guía de Errores.

claude mcp add --transport http panadata https://mcp.panadata.net/mcp

curl -X POST 'https://api.panadata.net/v5/resolve' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Cerveceria Nacional"}'

resolve_entity({"name": "Cerveceria Nacional"})

Candidatos con nombre, tipo, identificador enmascarado (8-***-2264, 155***-2-2016), confidence, matched_on y exact_homonyms; una fila por llamada. Con llave gratuita, además resolve/batch hasta 10 filas; con saldo, el identificador completo y lote de 100.

curl 'https://api.panadata.net/v5/entities/pa_own_4629361?include=DAT-FREE'

get_entity({"id": "pa_own_4629361", "include": ["DAT-FREE"]})

Sin llave: existe, vigente, suspendida, tipo, año, menú, actualizado y siguiente_paso, con las cabeceras X-Panadata-Tier: public y X-Panadata-Public-Budget-Remaining. Con llave gratuita (Authorization: Bearer pk_…): la ficha completa de arriba; sin include la ficha DAT-FREE es la respuesta por defecto de una llave sin saldo. Con saldo: los códigos que el menú anuncia.