Si usted desarrolla un POS, una tienda en línea o un ERP y sus clientes le piden que les facture desde ahí, no necesita dos integraciones ni pedirle a nadie su certificado. Con un solo token y un solo endpoint puede emitir de dos maneras: a nombre de su propia empresa y a nombre de cada cliente que gestiona. La única diferencia en el cuerpo de la petición es un campo: managed_contributor_id.
Descargue la guía completa
Preparamos una guía autoconclusiva con la base normativa, lo que hay que preparar una sola vez por cliente, los dos ejemplos completos con las diferencias señaladas, la tabla campo por campo y los errores que va a ver con su solución.
Guía del integrador: facturar a nombre propio y de sus clientes (PDF, disponible en dos idiomas)
Descargar en español Download in EnglishIgual que la guía de emisión por API, está escrita para que la lea una persona o una IA. Puede dársela a su asistente de programación y pedirle que arme el JSON; ahí vienen las reglas y los errores comunes para que el comprobante salga aceptado a la primera.
Las dos formas de emitir
Usted tiene el mismo código llamando al mismo endpoint. Lo que decide a nombre de quién sale la factura es si envía o no un campo:
| Modo directo | Modo integrador | |
|---|---|---|
| Quién vende | Su empresa | Su cliente |
| Emisor ante Hacienda | Su empresa | Su cliente, nunca usted |
| Campo extra en el JSON | Ninguno | managed_contributor_id |
| Certificado que firma | El de su empresa | El del cliente, usted nunca lo ve |
| Consecutivo | El de su empresa | El del cliente, en la terminal que Almendro le asignó |
| Cupo mensual | El suyo | El suyo también |
| Token | El suyo | El suyo. Nunca necesita el del cliente |
La URL es la misma en los dos casos: POST /api/v1/public/vouchers.
Por qué puede emitir a nombre de un cliente
Esta es la parte que suele generar dudas, y la respuesta es corta: usted nunca es el emisor de la factura de su cliente. El emisor ante Hacienda es el cliente, siempre. Usted es el sistema que le manda los datos a Almendro.
- La clave de 50 dígitos se genera con la cédula del cliente.
- El XML se firma con el certificado .p12 del cliente, que Almendro custodia. Usted nunca lo descarga ni lo manipula.
- El consecutivo avanza en los contadores del cliente.
- Hacienda recibe al cliente como emisor. Su empresa no aparece en el XML.
- Almendro guarda quién disparó la emisión en la bitácora, y se ve en la respuesta como
emitted_by. Es un dato de auditoría, no fiscal.
El consentimiento del cliente es el eje de todo: lo autoriza una vez y puede retirarlo cuando quiera desde su propio panel, sin pedirle permiso a usted. Al hacerlo usted deja de poder emitir para él, y los comprobantes ya emitidos no se afectan en nada. Un mismo cliente puede estar gestionado por varios integradores a la vez, cada uno con su terminal, sin que los consecutivos choquen.
Lo que cambia en la llamada
Emitiendo a nombre de un cliente, el cuerpo es idéntico salvo por dos campos:
{
"managed_contributor_id": "019d867d-0241-7288-8ece-fd64da75616d",
"voucher_type": "01",
"issuer_activity_code": "4752.0",
...
}
El managed_contributor_id es el id que devuelve GET /my-contributors. El issuer_activity_code tiene que ser la actividad económica del cliente: si manda la suya, sale error. La respuesta viene con is_via_integrator: true más los bloques emitted_by y emitter.
Un detalle que ahorra soporte: no mande local_code ni terminal_code en modo gestionado. La terminal se resuelve sola, y es la que evita que dos integradores del mismo cliente generen consecutivos duplicados.
Cuatro condiciones para que se acepte
- Su plan permite clientes gestionados (plan Integrador o equivalente).
- Existe una relación de gestión activa entre usted y ese cliente.
- El cliente tiene un certificado .p12 activo para el ambiente que usted está llamando. Sandbox y producción usan certificados distintos.
- La cuenta del cliente no está suspendida.
Si falta cualquiera, la petición se rechaza con 422 antes de generar nada: no gasta consecutivo, no gasta cupo, no llega a Hacienda. Puede corregir y reintentar sin costo. La guía trae la tabla completa de errores con su significado y su solución.
Pruebe primero en sandbox
Es el mismo JSON y el mismo token: lo único que cambia es que la URL lleva /sandbox antes de /vouchers. Los comprobantes de sandbox no tienen valor fiscal y no gastan numeración ni cupo de producción. Cuando Hacienda acepte sus pruebas, quita /sandbox de la URL y no hay nada más que cambiar.
Empiece hoy
La referencia interactiva completa de la API está en fe.almendro.cr/docs-v2. El token se obtiene en el panel de Almendro, en la sección del SDK / API, con un plan que incluya clientes gestionados. Si tiene alguna consulta técnica, escríbanos y con gusto le ayudamos.
