API key#
Cada solicitud lleva tu API key en el header Authorization con el esquema Bearer:
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
401con códigono_autorizado.
Ambientes#
El prefijo de la key define el ambiente. La URL base es la misma.
| Key | Ambiente | Qué hace |
|---|---|---|
sk_test_… | sandbox | Si 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_… | test | Si subiste tu certificado y lo pides con PATCH /v1/company, envía a TesteCF, el ambiente de pruebas real de la DGII. |
sk_live_… | cert | Durante la certificación de tu empresa como emisor (CerteCF). |
sk_live_… | prod | Producció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:
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.