Crear un negocio
Un negocio de práctica para Sandbox, o tu RUC real. Con solo el RUC, tomamos del SRI todo lo que tus comprobantes deben decir de ti.
Un negocio (en la API, entity) es quien emite comprobantes desde tu organización, y es de una de dos clases que eliges al crearlo y no cambian: de Sandbox, para practicar, o en vivo, con un RUC real. Una organización puede tener varios de cada clase: tu empresa, la de un cliente al que le facturas, cada RUC de un grupo.
Un negocio de Sandbox
Para practicar no necesitas tu RUC. Inventas el nombre; todos los negocios de Sandbox usan el RUC de práctica 9999999999001:
curl -X POST https://api.fiscalbase.io/v1/ec/entities \
-H "Authorization: Bearer $FISCALBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "kind": "sandbox", "legal_name": "NEGOCIO DE PRÁCTICA S.A." }'Puedes enviar también trade_name, head_office_address y los demás campos opcionales de abajo, además de keeps_accounting (por defecto, no) y regime (por defecto, general). Cada tipo de comprobante recibe la numeración 001-001 en Sandbox, así que puedes emitir tu primera factura en el siguiente request. Es gratis, sin límite de negocios, no necesita certificado, nunca pasa a Producción y lo puedes borrar (DELETE /v1/ec/entities/{id}, una persona propietaria o administradora desde la consola), con todo lo que emitió.
Un negocio en vivo
Para registrarlo, solo necesitas el RUC (el RUC de práctica se rechaza con un 422 en ruc):
curl -X POST https://api.fiscalbase.io/v1/ec/entities \
-H "Authorization: Bearer $FISCALBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "kind": "live", "ruc": "1790012345001" }'Consultamos el registro del SRI y tomamos de ahí lo que tus comprobantes deben decir:
| Campo | De dónde sale |
|---|---|
legal_name | La razón social del RUC |
trade_name | El nombre comercial; puedes cambiarlo |
head_office_address | La dirección de la matriz; puedes cambiarla |
head_office_phone y head_office_email | Opcionales: los envías tú, null los quita, y se imprimen en el RIDE (el XML del SRI no los lleva) |
reply_to_email y footer_legend | Opcionales: el correo al que responden tus clientes y una línea (hasta 160 caracteres) que se imprime al pie del RIDE; null los quita |
portal_shows_test | Solo en un negocio en vivo: true muestra también los comprobantes de Pruebas en su portal; false por defecto |
keeps_accounting | Si el RUC está obligado a llevar contabilidad |
regime | general, rimpe_emprendedor o rimpe_negocio_popular |
Nada de esto lo escribes tú, así que no puede quedar mal escrito. El régimen, por ejemplo, decide la leyenda RIMPE que el SRI exige en cada comprobante: la ponemos nosotros.
Cuándo rechazamos un RUC
Respondemos 422 si el RUC:
- no existe en el SRI, o no está activo;
- está marcado por el SRI como empresa fantasma o con transacciones inexistentes;
- es contribuyente especial o agente de retención y no enviaste su número de resolución, que va impreso en cada comprobante:
{
"kind": "live",
"ruc": "1790012345001",
"special_taxpayer_resolution": "12345",
"withholding_agent_resolution": "1"
}Guardamos una resolución solo si el SRI registra esa obligación para el RUC. La de contribuyente especial tiene de 3 a 13 letras y dígitos; la de agente de retención, hasta 8 dígitos, y la guardamos sin ceros a la izquierda (00000123 queda 123), como exige la ficha técnica. Si el registro no dice en qué régimen está el RUC, te pedimos regime.
Gran contribuyente
El registro del SRI no dice quién es gran contribuyente, así que, si lo eres, decláralo con tu resolución:
{
"kind": "live",
"ruc": "1790012345001",
"large_taxpayer_resolution": "NAC-GCTRGEC23-00000001"
}Desde entonces escribimos la leyenda Gran Contribuyente con esa resolución en tus facturas, liquidaciones de compra y notas de crédito y de débito, como exige el anexo 24. Puedes agregarla o quitarla (null) después con PATCH /v1/ec/entities/{id}.
Si el SRI no responde, recibes 503: vuelve a intentar en unos minutos.
Qué falta para emitir
Un negocio en vivo emite en Pruebas y en Producción, no en Sandbox. Necesita abrir su numeración, subir su certificado y tener un plan cuyo primer pago hayamos validado; hasta entonces puedes configurarlo todo, pero no emite.
Con varios negocios
Si tu organización tiene un solo negocio de la clase que tu clave emite (Sandbox para una clave de Sandbox; en vivo para una de Pruebas o Producción), lo usamos sin que lo digas. Con más de uno, cada comprobante lleva entity_id:
{ "entity_id": "5b0e…", "buyer": { … }, "lines": [ … ] }Un RUC real se registra una sola vez por organización; si lo repites, respondemos 409. Los negocios de Sandbox comparten el RUC de práctica y no chocan. Un entity_id de la otra clase es un 422 que dice de cuál es.