Saltar al contenido
firmo
Docs / Autenticación y ambientes

Autenticación y ambientes

API keys sk_test y sk_live, ambientes sandbox, test, cert y prod, cómo cambiar de uno a otro y cómo manejar varias empresas con tus keys.

API key#

Cada solicitud lleva tu API key en el header Authorization con el esquema Bearer:

Header
Authorization: Bearer sk_test_…
  • Firmo guarda las API keys como hash SHA-256. Solo se muestran una vez, al crearlas. Si pierdes una, genera otra.
  • Sin key, o con una key inválida, la API responde 401 con código no_autorizado.

Ambientes#

El prefijo de la key define el ambiente. La URL base es la misma.

KeyAmbienteQué hace
sk_test_…sandboxSi tu empresa no ha subido certificado, usa el simulador de Firmo: no toca la DGII y responde como ella, firmando con un certificado autofirmado.
sk_test_…testSi subiste tu certificado y lo pides con PATCH /v1/company, envía a TesteCF, el ambiente de pruebas real de la DGII.
sk_live_…certDurante la certificación de tu empresa como emisor (CerteCF).
sk_live_…prodProducción: e-CF con validez fiscal.

Cada e-CF indica en qué ambiente se emitió en el campo ambiente (sandbox, test, cert o prod).

Pasar de simulador a TesteCF#

Cuando subas tu certificado digital, puedes probar contra la DGII real sin salir de sandbox:

PATCH /v1/company
curl -X PATCH https://api.firmo.do/v1/company \
  -H "Authorization: Bearer $FIRMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ambiente": "test" }'

Varias empresas#

Si tu cuenta maneja varias empresas, indica cuál con el header Firmo-Company. Sin él, se usa la empresa principal de la cuenta. Ver Integradores.

El header Firmo-Channel#

Cada e-CF guarda el canal por el que se creó (canal): portal, api, sdk, mcp, sheets, whatsapp, excel o certificacion. Con una API key el valor predeterminado es api; el SDK, el servidor MCP y la plantilla de Google Sheets de Firmo envían solos Firmo-Channel con sdk, mcp o sheets. Si construyes tu propio cliente, no hace falta que lo envíes.

Solo se aceptan api, sdk, mcp y sheets; cualquier otro valor se ignora y queda api. Es un dato declarado por el cliente: Firmo no lo verifica. Puedes filtrar con GET /v1/ecf?channel=sdk. Los e-CF anteriores al seguimiento de canales tienen canal en null.

Protege tus keys

Usa las keys solo desde tu servidor. Nunca las pongas en una app móvil, en JavaScript del navegador ni en un repositorio.