Configurar sandbox

Contribuyentes explica cada endpoint por separado. Esta página es la misma información pero en el orden en que realmente se usa, de cero a poder cotizar o emitir.

1. Generá una llave de sandbox

   Desde el panel, en Integración → Llaves de API, con el proyecto de sandbox seleccionado. Va a empezar con timbre_sk_sandbox_… — ese prefijo es la forma de confirmar, con solo mirarla, que no es la de producción. Autenticación tiene el resto del formato.

2. Dá de alta el contribuyente

   POST /internal/v1/issuers con su cédula, nombre comercial, régimen y el .p12 de su certificado de firma. El certificado se valida al recibirlo. Contribuyentes tiene el payload completo y los errores posibles.

3. Registrá una sucursal y un terminal

   Sin al menos un terminal no hay numeración, y sin numeración no hay documento. Sucursales y terminales son compartidos entre ambientes, así que este paso no se repite cuando actives producción.

4. Cargá las credenciales de Hacienda del sandbox

   El usuario y la contraseña del ATV de sandbox, por PUT /internal/v1/issuers/environments/sandbox/credentials. La respuesta trae verification.outcome: confirmá que sea accepted antes de seguir. Si es unreachable, volvé a guardarlas —no es un rechazo, es que no hubo veredicto.

   ¿No tenés todavía ese usuario, o el certificado .p12 del paso anterior? Credenciales de Hacienda muestra dónde conseguir ambos, con capturas de cada pantalla.

Confirmá que puede emitir

Un contribuyente factura cuando las tres cosas de Contribuyentes son ciertas para sandbox: está activo, tiene un terminal, y credentialStatus en sandbox no es absent ni rejected. Podés verlas todas juntas en

curl https://api.timbre.cr/internal/v1/issuers/list \
  -H "Authorization: Bearer timbre_sk_sandbox_…"

Con environment=sandbox como parámetro de consulta si querés dejarlo explícito —es lo que asume si lo omitís.

Cumplidas, el camino sigue en Primeros pasos: cotizar, emitir, seguir el estado.

Cuando esto ya funcione

Repetilo en producción con Configurar producción —es casi el mismo camino, pero con menos pasos: el contribuyente, sus sucursales y sus terminales ya existen, y lo único nuevo es la llave y las credenciales de Hacienda de producción de ese contribuyente.