{ "openapi": "3.1.0", "info": { "title": "API eInforma", "version": "1.0", "description": "Accede a la mayor base de datos de empresas de España desde una API REST. Úsala para enriquecer tu CRM o ERP, autocompletar formularios de alta de clientes o automatizar procesos de prospección.\n\n## Primeros pasos\n\n1. **Consigue tus credenciales.** Date de alta gratis en [einforma.com/api](https://www.einforma.com/api) y obtendrás un `client_id` y un `client_secret`.\n2. **Inicia sesión** con el botón **Iniciar sesión**. Introduce tus credenciales una sola vez: pediremos el token y lo añadiremos a todas las llamadas de prueba.\n3. **Busca una empresa** con `GET /companies`. Solo necesitas el texto a buscar.\n4. **Recupera su ficha** con el `id` del resultado. Empieza por `/companies/{id}/test` y podrás ver todo lo que te devolvemos para integrarlo en tu sistema.\n5. **Contrata una API** y podrás acceder a `/companies/{id}/report` para obtener fichas con datos reales de las empresas.\n\n## Autenticación\n\nLa API usa OAuth 2.0 con el flujo *client credentials*. Desde esta documentación no tienes que hacer nada más que iniciar sesión. En tu integración son dos pasos.\n\n**1. Pide el token** (válido durante los segundos que indica `expires_in`):\n\n```bash\ncurl -X POST https://developers.einforma.com/api/v1/oauth/token \\\n -d client_id=TU_CLIENT_ID \\\n -d client_secret=TU_CLIENT_SECRET \\\n -d grant_type=client_credentials \\\n -d scope=buscar:consultar:empresas\n```\n\n**2. Envíalo en la cabecera `Authorization`** de cada llamada:\n\n```bash\ncurl \"https://developers.einforma.com/api/v1/companies?companySearch=informa\" \\\n -H \"Authorization: Bearer TU_ACCESS_TOKEN\"\n```\n\nReutiliza el token hasta que caduque en lugar de pedir uno por llamada.\n\n## Fichas test y consumo de saldo\n\nTu cuenta tiene dos saldos independientes, que puedes consultar en `GET /balances`:\n\n| Saldo | Lo consume | Para qué sirve |\n|---|---|---|\n| `test` | `GET /companies/{id}/test` | Desarrollar y probar la integración |\n| `ficha` | `GET /companies/{id}/report` | Uso real en producción |\n\nLa búsqueda de empresas no consume saldo. El detalle de las fichas consumidas está en `GET /orders`.\n\n## Formatos de respuesta\n\nTodas las operaciones devuelven JSON por defecto. Si prefieres XML, envía la cabecera `Accept: application/xml`.\n\n## Errores\n\nLos errores devuelven siempre el mismo formato, con el código HTTP repetido en `status` y una explicación en `message`:\n\n```json\n{ \"status\": 401, \"message\": \"Token de acceso no válido o caducado\" }\n```\n\n| Código | Significado | Qué hacer |\n|---|---|---|\n| `400` | Falta un parámetro o su valor no es válido | Revisa los parámetros de la petición |\n| `401` | Token ausente, no válido o caducado | Vuelve a iniciar sesión o pide un token nuevo |\n| `402` | No dispones de saldo para la ficha solicitada (solo fichas) | Consulta tu saldo en `GET /balances` y recárgalo |\n| `404` | Empresa no encontrada (solo fichas) | Comprueba el `id`; obténlo con `GET /companies` |\n| `406` | Empresa temporalmente bloqueada (solo fichas) | Inténtalo de nuevo más tarde; si persiste, escríbenos |\n| `500` | Error interno | Reintenta más tarde; si persiste, escríbenos |\n\n## Soporte\n\nTe ayudamos con la integración en [developers@einforma.com](mailto:developers@einforma.com) o en el teléfono gratuito **900 10 30 20**.", "contact": { "name": "Soporte a desarrolladores", "email": "developers@einforma.com", "url": "https://www.einforma.com" } }, "servers": [ { "url": "https://developers.einforma.com/api/v1" } ], "tags": [ { "name": "Token de acceso", "description": "Obtén el token de acceso OAuth 2.0 que necesitan el resto de operaciones." }, { "name": "Empresas y autónomos", "description": "Busca empresas y autónomos y recupera su ficha: datos identificativos, contacto, actividad, ventas y empleados." }, { "name": "Consumos", "description": "Consulta qué fichas has consumido en un periodo." }, { "name": "Saldos", "description": "Consulta el saldo disponible de fichas test y fichas reales." } ], "paths": { "/oauth/token": { "post": { "tags": [ "Token de acceso" ], "summary": "Obtener token de acceso", "operationId": "LogIn", "security": [], "description": "Intercambia tus credenciales por un token de acceso. Reutiliza el token hasta que caduque en lugar de pedir uno por cada llamada.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "client_id", "client_secret", "grant_type", "scope" ], "properties": { "client_id": { "type": "string", "description": "Identificador de cliente que recibiste al darte de alta." }, "client_secret": { "type": "string", "description": "Clave secreta asociada a tu `client_id`. No la publiques ni la incluyas en código de navegador." }, "grant_type": { "type": "string", "enum": [ "client_credentials" ], "default": "client_credentials", "description": "Siempre `client_credentials`. Ya viene relleno." }, "scope": { "type": "string", "enum": [ "buscar:consultar:empresas" ], "default": "buscar:consultar:empresas", "description": "Siempre `buscar:consultar:empresas`. Ya viene relleno." } } } } } }, "responses": { "200": { "description": "Token generado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" }, "example": { "access_token": "eyJhbGciOiJSUzI1NiJ9.ejemplo", "token_type": "bearer", "expires_in": 3600, "scope": "buscar:consultar:empresas" } } } }, "400": { "description": "Petición incorrecta: falta un parámetro o su valor no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El parámetro companySearch es obligatorio" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } }, "/companies": { "get": { "tags": [ "Empresas y autónomos" ], "summary": "Buscar empresas", "operationId": "listCompaniesByName", "security": [ { "Bearer": [] } ], "description": "Busca empresas o autónomos por denominación social, marca, denominación comercial, rótulo o anagrama. No consume saldo.\n\nCon `predictive=true` la búsqueda se comporta como un autocompletado: devuelve los 3 primeros resultados de empresas y los 3 primeros de autónomos que coinciden exactamente con el término. Es la opción indicada para formularios web.", "parameters": [ { "name": "companySearch", "in": "query", "required": true, "description": "Término de búsqueda.", "schema": { "type": "string" }, "example": "informa" }, { "name": "rows", "in": "query", "description": "Número de resultados que devuelve la consulta.", "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "name": "start", "in": "query", "description": "Posición del primer resultado, para paginar.", "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "predictive", "in": "query", "description": "Activa la búsqueda predictiva (autocompletado).", "schema": { "type": "boolean", "default": false } }, { "name": "individuals", "in": "query", "description": "Busca autónomos en lugar de empresas.", "schema": { "type": "boolean", "default": false } }, { "name": "province", "in": "query", "description": "Filtra por código de provincia.", "schema": { "type": "integer", "minimum": 1, "maximum": 70 } } ], "responses": { "200": { "description": "Resultados de la búsqueda.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultadoBusqueda" }, "example": { "total": 2, "empresa": [ { "id": "B00000000", "denominacion": "EMPRESA EJEMPLO SL", "tipoDenominacion": "Denominación social", "denominacionBusqueda": "EMPRESA EJEMPLO", "provincia": "MADRID" }, { "id": "A00000001", "denominacion": "EJEMPLO SERVICIOS SA", "tipoDenominacion": "Marca", "denominacionBusqueda": "EJEMPLO", "provincia": "BARCELONA" } ] } }, "application/xml": { "schema": { "$ref": "#/components/schemas/ResultadoBusqueda" } } } }, "400": { "description": "Petición incorrecta: falta un parámetro o su valor no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El parámetro companySearch es obligatorio" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } }, "/companies/{id}/test": { "get": { "tags": [ "Empresas y autónomos" ], "summary": "Obtener ficha test", "operationId": "findTestReportById", "security": [ { "Bearer": [] } ], "description": "Devuelve la ficha de una empresa o autónomo en modo test. Consume saldo **test**, no saldo de fichas: úsala mientras desarrollas.", "parameters": [ { "$ref": "#/components/parameters/IdEmpresa" } ], "responses": { "200": { "description": "Ficha de la empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empresa" }, "example": { "denominacion": "EMPRESA EJEMPLO SL", "nombreComercial": [ "EJEMPLO" ], "domicilioSocial": "CALLE MAYOR 1", "localidad": "MADRID", "formaJuridica": "SOCIEDAD LIMITADA", "cnae": "6201 - Actividades de programación informática", "fechaUltimoBalance": "2025-12-31", "identificativo": "B00000000", "situacion": "ACTIVA", "telefono": [ "910000000" ], "fax": [], "web": [ "www.ejemplo.es" ], "email": "info@ejemplo.es", "cargoPrincipal": "ADMINISTRADOR ÚNICO", "capitalSocial": 3000, "ventas": 1250000, "anioVentas": 2025, "empleados": 14, "fechaConstitucion": "2012-03-15" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Empresa" } } } }, "400": { "description": "Petición incorrecta: el identificador de empresa no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El identificador de empresa no es válido" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "402": { "description": "Actualmente no dispone de saldo. Pago requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 402, "message": "Actualmente no dispone de saldo. Pago requerido." } } } }, "404": { "description": "Empresa no encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 404, "message": "Empresa no encontrada" } } } }, "406": { "description": "Empresa temporalmente bloqueada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 406, "message": "Empresa temporalmente bloqueada" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } }, "/companies/{id}/report": { "get": { "tags": [ "Empresas y autónomos" ], "summary": "Obtener ficha", "operationId": "findReportById", "security": [ { "Bearer": [] } ], "description": "Devuelve la ficha de una empresa o autónomo. Consume una unidad de saldo de **fichas**.", "parameters": [ { "$ref": "#/components/parameters/IdEmpresa" } ], "responses": { "200": { "description": "Ficha de la empresa.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Empresa" }, "example": { "denominacion": "EMPRESA EJEMPLO SL", "nombreComercial": [ "EJEMPLO" ], "domicilioSocial": "CALLE MAYOR 1", "localidad": "MADRID", "formaJuridica": "SOCIEDAD LIMITADA", "cnae": "6201 - Actividades de programación informática", "fechaUltimoBalance": "2025-12-31", "identificativo": "B00000000", "situacion": "ACTIVA", "telefono": [ "910000000" ], "fax": [], "web": [ "www.ejemplo.es" ], "email": "info@ejemplo.es", "cargoPrincipal": "ADMINISTRADOR ÚNICO", "capitalSocial": 3000, "ventas": 1250000, "anioVentas": 2025, "empleados": 14, "fechaConstitucion": "2012-03-15" } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Empresa" } } } }, "400": { "description": "Petición incorrecta: el identificador de empresa no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El identificador de empresa no es válido" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "402": { "description": "Actualmente no dispone de saldo. Pago requerido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 402, "message": "Actualmente no dispone de saldo. Pago requerido." } } } }, "404": { "description": "Empresa no encontrada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 404, "message": "Empresa no encontrada" } } } }, "406": { "description": "Empresa temporalmente bloqueada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 406, "message": "Empresa temporalmente bloqueada" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } }, "/orders": { "get": { "tags": [ "Consumos" ], "summary": "Listar consumos", "operationId": "listOrders", "security": [ { "Bearer": [] } ], "description": "Lista las fichas consumidas entre dos fechas.", "parameters": [ { "name": "start_date", "in": "query", "description": "Fecha de inicio del periodo (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } }, { "name": "end_date", "in": "query", "description": "Fecha de fin del periodo (AAAA-MM-DD).", "schema": { "type": "string", "format": "date" } } ], "responses": { "200": { "description": "Consumos del periodo.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Consumo" } }, "example": [ { "cif": "B00000000", "fecha": "2026-09-14T10:32:05Z" }, { "cif": "A00000001", "fecha": "2026-09-22T16:05:41Z" } ] }, "application/xml": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Consumo" } } } } }, "400": { "description": "Petición incorrecta: falta un parámetro o su valor no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El parámetro companySearch es obligatorio" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } }, "/balances": { "get": { "tags": [ "Saldos" ], "summary": "Consultar saldo", "operationId": "listBalances", "security": [ { "Bearer": [] } ], "description": "Devuelve el saldo disponible de fichas test y de fichas reales.", "responses": { "200": { "description": "Saldo actual.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Saldo" }, "example": { "test": 50, "ficha": 120 } }, "application/xml": { "schema": { "$ref": "#/components/schemas/Saldo" } } } }, "400": { "description": "Petición incorrecta: falta un parámetro o su valor no es válido.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 400, "message": "El parámetro companySearch es obligatorio" } } } }, "401": { "description": "No autorizado: el token no se ha enviado, no es válido o ha caducado.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 401, "message": "Token de acceso no válido o caducado" } } } }, "500": { "description": "Error interno. Si persiste, contacta con soporte.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "status": 500, "message": "Error interno del servidor" } } } } } } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "description": "Se rellena al iniciar sesión." } }, "parameters": { "IdEmpresa": { "name": "id", "in": "path", "required": true, "description": "NIF o identificador de la empresa o autónomo, tal como lo devuelve la búsqueda.", "schema": { "type": "string" }, "example": "B00000000" } }, "schemas": { "Token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Token que debes enviar en la cabecera `Authorization: Bearer`." }, "token_type": { "type": "string", "description": "Tipo de token.", "examples": [ "bearer" ] }, "expires_in": { "type": "integer", "description": "Segundos de validez del token." }, "scope": { "type": "string", "description": "Permisos concedidos." } } }, "Error": { "type": "object", "properties": { "status": { "type": "integer", "format": "int64", "description": "Código HTTP del error." }, "message": { "type": "string", "description": "Descripción del error." } } }, "ResultadoBusqueda": { "type": "object", "xml": { "name": "resultado" }, "properties": { "total": { "type": "integer", "description": "Número total de coincidencias.", "xml": { "attribute": true } }, "empresa": { "type": "array", "description": "Página de resultados.", "items": { "$ref": "#/components/schemas/EmpresaResultado" } } } }, "EmpresaResultado": { "type": "object", "properties": { "id": { "type": "string", "description": "NIF o identificador. Úsalo para pedir la ficha." }, "denominacion": { "type": "string", "description": "Denominación social." }, "tipoDenominacion": { "type": "string", "description": "Campo por el que ha coincidido la búsqueda (denominación social, marca, rótulo…)." }, "denominacionBusqueda": { "type": "string", "description": "Texto con el que ha coincidido." }, "provincia": { "type": "string", "description": "Provincia del domicilio social." } } }, "Empresa": { "type": "object", "xml": { "name": "empresa" }, "properties": { "denominacion": { "type": "string", "description": "Denominación social." }, "nombreComercial": { "type": "array", "items": { "type": "string" }, "description": "Nombres comerciales." }, "identificativo": { "type": "string", "description": "NIF." }, "formaJuridica": { "type": "string", "description": "Forma jurídica." }, "situacion": { "type": "string", "description": "Situación de la empresa (activa, extinguida…)." }, "fechaConstitucion": { "type": "string", "description": "Fecha de constitución." }, "domicilioSocial": { "type": "string", "description": "Dirección del domicilio social." }, "localidad": { "type": "string", "description": "Localidad del domicilio social." }, "cnae": { "type": "string", "description": "Código y descripción de la actividad (CNAE)." }, "cargoPrincipal": { "type": "string", "description": "Cargo principal." }, "telefono": { "type": "array", "items": { "type": "string" }, "description": "Teléfonos." }, "fax": { "type": "array", "items": { "type": "string" }, "description": "Faxes." }, "web": { "type": "array", "items": { "type": "string" }, "description": "Sitios web." }, "email": { "type": "string", "description": "Correo electrónico de contacto." }, "capitalSocial": { "type": "number", "description": "Capital social, en euros." }, "ventas": { "type": "number", "description": "Importe de ventas, en euros." }, "anioVentas": { "type": "integer", "description": "Ejercicio al que corresponden las ventas." }, "empleados": { "type": "integer", "description": "Número de empleados." }, "fechaUltimoBalance": { "type": "string", "description": "Fecha del último balance depositado." } } }, "Consumo": { "type": "object", "properties": { "cif": { "type": "string", "description": "NIF de la ficha consumida." }, "fecha": { "type": "string", "format": "date-time", "description": "Fecha y hora del consumo." } } }, "Saldo": { "type": "object", "properties": { "test": { "type": "number", "description": "Fichas test disponibles." }, "ficha": { "type": "number", "description": "Fichas reales disponibles." } } } } }, "externalDocs": { "description": "eInforma", "url": "https://www.einforma.com/api" } }