DEVSDESIGN — DEVELOPERS & DESIGN

API v1 · contrato 1.0.0

Autenticación

API keys, permisos por alcance y manejo seguro de credenciales.

API keys

La API se autentica con una API key enviada como token Bearer en el encabezado Authorization. No usa OAuth ni sesiones.

Encabezado de autenticación
Authorization: Bearer dd_test_…

El prefijo indica el ambiente:

PrefijoAmbienteUso
dd_test_PruebasDesarrollo e integración. No genera comprobantes con validez fiscal.
dd_live_ProducciónEmisión real. Disponible cuando la plataforma complete su acreditación.

Permisos por alcance

Cada API key tiene una lista de permisos (scopes). Una operación responde 403 forbidden si la clave no tiene el permiso requerido. Asigna a cada clave solo lo que necesita.

PermisoPermite
companies:readConsultar empresas emisoras.
companies:writeCrear, modificar y eliminar empresas emisoras.
documents:readConsultar comprobantes, estados, eventos, XML y PDF.
documents:writeEmitir comprobantes.
received:writeResponder comercialmente a comprobantes recibidos.
webhooks:manageAdministrar endpoints de webhooks y sus entregas.

Crear, rotar y revocar claves

Las claves se administran desde el portal. Por seguridad, esas acciones exigen verificación en dos pasos (MFA) y haber confirmado tu identidad en los últimos 10 minutos.

  • Rotar una clave genera una nueva para reemplazarla. Hazlo de forma periódica y siempre que sospeches de una exposición.
  • Revocar una clave la invalida de inmediato: las solicitudes que la usen responderán 401.

Buenas prácticas

  • Usa la API solo desde tu backend. Una clave incluida en una aplicación móvil o en JavaScript del navegador queda expuesta.
  • Guarda las claves en un gestor de secretos o en variables de entorno, nunca en el repositorio.
  • Usa claves distintas por aplicación y por ambiente, para poder revocar una sin afectar a las demás.
  • No compartas claves por correo ni por tickets de soporte.

Errores de autenticación

EstadoCódigoCausa
401unauthenticatedFalta la clave, tiene un formato incorrecto o fue revocada.
403forbiddenLa clave es válida pero no tiene el permiso que exige la operación.

¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.