Nivel gratuito (DAT-FREE)

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). 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.