> For the complete documentation index, see [llms.txt](https://docs.cnpj.ws/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cnpj.ws/es/blog/como-automatizar-o-cadastro-de-clientes-com-uma-api-de-consulta-cnpj.md). # API de Consulta CNPJ: automatiza el registro de clientes ¿Cuántas veces tu equipo ya digitó la razón social, la dirección, el código CNAE y la inscripción estatal de un cliente nuevo — campo por campo — copiando de la tarjeta CNPJ de la Receita Federal de Brasil? Además de lento, este proceso es la principal puerta de entrada de errores de registro: un dígito equivocado en el CNPJ, una dirección desactualizada, una razón social abreviada de forma diferente en cada sistema. La buena noticia es que nada de esto necesita ser manual. Con una **API de consulta CNPJ**, tu sistema le pide al usuario un solo dato — el número de CNPJ — y completa todo lo demás automáticamente, con información oficial y actualizada. En este post mostramos cómo funciona este flujo, cómo implementarlo con la API de CNPJ.ws y cómo un ERP brasileño usa exactamente este enfoque en producción. ### El problema del registro manual Todo sistema que atiende empresas — ERP, CRM, plataforma de facturación, e-commerce B2B — necesita registrar personas jurídicas. En el flujo manual, eso significa un formulario con 10 a 20 campos que alguien completa consultando documentos. Los costos aparecen en tres frentes: * **Tiempo**: cada registro consume minutos de trabajo repetitivo, multiplicado por todos los clientes y proveedores de la base. * **Errores**: la digitación manual genera divergencias que se propagan a facturas, cobros y contratos — y retrabajo para corregirlas. * **Datos desactualizados**: la empresa cambia de dirección o de situación registral, y el registro en el sistema mantiene la información antigua. ### Cómo funciona una API de consulta CNPJ Una API de consulta CNPJ expone los datos públicos de las empresas brasileñas en formato estructurado (JSON), listo para ser consumido por cualquier aplicación. En el caso de CNPJ.ws, una única solicitud HTTP devuelve razón social, nombre de fantasía, situación registral, naturaleza jurídica, tamaño de la empresa, dirección completa, códigos CNAE, estructura societaria, inscripciones estatales y régimen tributario (Simples Nacional/MEI). El flujo de automatización tiene tres pasos: #### 1. El usuario informa solo el CNPJ En el formulario de registro, el único campo obligatorio pasa a ser el CNPJ. Vale la pena validar los dígitos verificadores en el front-end antes de consultar, evitando llamadas innecesarias. #### 2. El sistema consulta la API ```bash curl https://publica.cnpj.ws/cnpj/00000000000191 ``` La respuesta trae el objeto completo de la empresa. La API pública de CNPJ.ws permite hasta 3 consultas por minuto — suficiente para probar y para volúmenes bajos. Para uso en producción, la API comercial ofrece límites mayores, datos adicionales y SLA. #### 3. El formulario se completa solo Con la respuesta en mano, el sistema completa todos los campos: razón social, dirección, CNAE principal, régimen tributario. El usuario solo revisa y confirma. Lo que antes tomaba minutos ahora toma segundos — y los datos llegan exactamente como constan en el registro oficial del gobierno. ### Caso real: registro de clientes por IA en bitERP Un ejemplo de quien usa este flujo en producción es [bitERP, un ERP con inteligencia artificial](https://www.biterp.ai) desarrollado en Brasil. En bitERP, el usuario puede pedir en el chat algo como *"registra el cliente CNPJ 00.000.000/0001-00"* — y el agente de IA consulta la API de CNPJ.ws, completa el registro entero en pantalla y pide solo la confirmación final. La combinación es interesante porque une dos automatizaciones: la IA elimina la navegación por menús y formularios, y la API de consulta CNPJ elimina la búsqueda y digitación de los datos. El resultado es un onboarding de cliente que se resuelve en una sola frase, con datos oficiales de la Receita Federal — sin errores de digitación y sin registros incompletos. El mismo patrón se aplica a proveedores, transportadoras y cualquier otra entidad jurídica del sistema. ### Buenas prácticas al integrar Para aprovechar al máximo la integración, vale seguir algunas recomendaciones: * **Valida el CNPJ antes de consultar** — el dígito verificador es un cálculo local; no gastes una solicitud con un número inválido. * **Maneja los límites de solicitudes** — implementa retry con backoff para el error 429 y considera la API comercial para volumen. * **Guarda la fecha de la consulta** — los datos registrales cambian; saber cuándo se sincronizó el registro permite programar actualizaciones periódicas. * **Alerta de situación registral** — si la empresa consta como cerrada, suspendida o irregular, señálalo antes de concluir el registro. Esto evita emitir facturas a un CNPJ irregular. * **Deja que el usuario revise** — la automatización completa, el humano confirma. Especialmente los campos que el cliente puede querer sobrescribir, como el nombre de fantasía. ### Empieza ahora Puedes probar la consulta en este momento, sin registro: basta llamar a `https://publica.cnpj.ws/cnpj/{número}` y ver el JSON devuelto. Para llevar la integración a producción, conoce los [planes de la API comercial de CNPJ.ws](https://www.cnpj.ws) — y si quieres ver el flujo de registro automatizado funcionando dentro de un ERP, el ejemplo de bitERP muestra hasta dónde puede llegar esta automatización. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.cnpj.ws/es/blog/como-automatizar-o-cadastro-de-clientes-com-uma-api-de-consulta-cnpj.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.