Primeros pasos
Operar en producción
Claves, errores, datos ausentes, costos de reintento y observabilidad.
Ejecuta las consultas desde tu servidor
Guarda ECUADORAPI_KEY en el entorno del backend. Autentica y autoriza a los usuarios de tu aplicación antes de consultar. No incluyas claves ni resultados personales en logs, analítica o URLs públicas.
Valida el contrato de cada endpoint
Verifica el estado HTTP y error antes de leer data. Valida los tipos y permite null en los campos que lo admiten. Solicita únicamente los datos que necesita tu flujo; una consulta no acredita la identidad de quien usa tu aplicación.
Prepara límites y tiempos de espera
Usa un timeout finito. Ante 429 respeta Retry-After. Para errores temporales limita los reintentos y aplica espera progresiva; no reintentes automáticamente errores de formato, autenticación o saldo.
Controla el costo de los reintentos
Una consulta exitosa repetida puede volver a cobrarse. Si la conexión se corta, no asumas que la operación quedó sin procesar. Consulta los registros y decide si tu producto necesita reintentar.
Define qué hacer ante datos ausentes
La disponibilidad y cobertura varían por endpoint. Distingue un campo null, una respuesta sin resultados y un error temporal. No prometas que todos los registros tendrán todos los campos ni interpretes una ausencia como una comprobación definitiva.
Observa la integración
Revisa las solicitudes, códigos HTTP, latencia y cargos en la consola. La página de estado muestra comportamiento observado del servicio; las métricas históricas no constituyen un SLA. Define en tu producto cómo continuar cuando una consulta no esté disponible.
Resultados, errores y cobro
Las consultas usan el header X-Lookup-Outcome para distinguir su resultado de los estados del registro, como ACTIVO en un RUC. En errores, data es null, error es true y message explica el problema. Usa code para identificarlo; algunos endpoints conservan códigos propios.
| Resultado | HTTP | Interpretación y cobro |
|---|---|---|
ok | 200 | Consulta confirmada, incluso con listas vacías, total 0 o registered=false. Se cobra según la oferta del endpoint. |
not_found | 404 | No se encontró el registro solicitado. Sin cobro ni consumo de cupo. No acredita la inexistencia legal de la persona o del registro. |
not_applicable | 200 | La consulta no aplica a este registro. Sin cobro ni consumo de cupo. No confirma ausencia de deudas. |
incomplete | 503 | No se pudo confirmar el resultado requerido. Sin cobro ni consumo de cupo. |
unavailable | 503 | No se pudo completar la consulta temporalmente. Sin cobro ni consumo de cupo. |
disabled | 503 | Consulta deshabilitada. Sin cobro ni consumo de cupo. Consulta su disponibilidad antes de reintentar. |
partial | 200 | Reporte con el resultado principal confirmado y secciones incompletas. Conserva las secciones disponibles y se cobra al precio del reporte. |
Respeta Retry-After, expresado en segundos. Si persiste el error, aumenta la espera entre reintentos y limita su cantidad. El intervalo no garantiza recuperación. No reintentes automáticamente errores de formato, autenticación, saldo o consultas deshabilitadas. Una conexión interrumpida no confirma que la consulta haya fallado: revisa tus registros antes de repetir una consulta que pudo completarse.
En reportes parciales, revisa outcome, code y retry_after de cada sección. Una sección ausente no invalida las disponibles. Los campos null y las listas vacías, por sí solos, no indican un fallo. Preparar sesiones y descargar documentos mantiene las reglas de cobro de cada endpoint.
Prueba éxito, datos ausentes, clave inválida, saldo insuficiente, límites y errores temporales con el playground ficticio. Después comprueba una consulta real autorizada y su registro en tu consola.
Abrir playground