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. Los negocios los crea una persona en la plataforma, con la sesión de su cuenta; una API key no puede crearlos (403 con el código person_required).
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:
{ "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 con una API key de ese negocio. Es gratis, sin límite de negocios, no necesita certificado y nunca pasa a Producción.
Un negocio en vivo
Para registrarlo, solo necesitas el RUC (el RUC de práctica se rechaza con un 422 en ruc):
{ "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 5 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 con su primer pago confirmado; hasta entonces puedes configurarlo todo, pero no emite en Pruebas ni en Producción.
Con varios negocios
Cada negocio tiene sus propias API keys, que creas en la plataforma estando en él. Una API key emite solo con su negocio y no ve los demás, así que ninguna petición dice con cuál emite: para emitir con otro negocio, usa la API key de ese negocio.
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.