Convenciones

URL base y versiónCopiar enlace a esta sección

https://api.fiscalbase.io/v1

Todo lo de Ecuador vive bajo /v1/ec/…, y sus objetos traen country (ec, código ISO 3166-1 en minúsculas): los comprobantes, las entidades y la consulta de contribuyentes siguen las reglas del SRI y se llaman como el SRI los llama. Lo que no depende del país (webhooks, portal) va directo bajo /v1.

Una versión nueva de la API solo llega con cambios incompatibles. Dentro de /v1 solo agregamos: campos nuevos en las respuestas, parámetros opcionales, endpoints y eventos. Tu integración debe ignorar los campos que no conoce.

AutenticaciónCopiar enlace a esta sección

Envía tu clave API como token Bearer en cada solicitud. La clave también decide el ambiente.

Authorization: Bearer fb_sandbox_…

JSONCopiar enlace a esta sección

Enviamos y recibimos JSON, con Content-Type: application/json. La única excepción es subir tu certificado, que es un archivo: va como multipart/form-data.

• Campos en snake_case y en inglés (unit_price, access_key), como las demás APIs que ya usas. Los valores del catálogo del SRI van con sus nombres de negocio: iva_15, consumidor_final, tarjeta_credito.
• Un campo que no conocemos es un error. Si escribes auxiliary_cod en vez de auxiliary_code, respondemos 422 en lines.0.auxiliary_cod con Campo desconocido, en vez de emitir el comprobante sin ese dato. Vale para el cuerpo y para los parámetros de las listas.
• Una respuesta trae siempre todos sus campos. Lo opcional que no enviaste vuelve como null, y las listas vacías como []. No tienes que distinguir entre "falta" y "vacío".

Montos y cantidadesCopiar enlace a esta sección

Los montos son texto con dos decimales: "11.50", no 11.5. Las cantidades y los precios unitarios aceptan hasta seis decimales: "2.5", "0.333333".

Usamos texto porque los números JSON se convierten a coma flotante en casi todos los lenguajes, y 0.1 + 0.2 no da 0.3. Con texto, lo que envías es exactamente lo que calculamos, y lo que calculamos es exactamente lo que va al SRI. Cada comprobante, receptor, importación y consumo trae su currency, el código ISO 4217 de sus montos: en Ecuador, USD.

FechasCopiar enlace a esta sección

• Fechas de calendario en ISO 8601: "2026-09-29". La fecha de emisión la ponemos nosotros: es siempre hoy en Ecuador (UTC−5), porque el SRI exige transmitir los comprobantes el mismo día.
• Momentos en ISO 8601 con zona: "2026-09-29T15:42:07.000Z" (created_at, status_transitions, authorized_at).

IdentificadoresCopiar enlace a esta sección

Los id son UUID versión 7: se ordenan por fecha de creación, así que el más reciente siempre es el mayor. Cada objeto trae su tipo en object (invoice, credit_note, entity…), así que el id no necesita prefijo.

Los comprobantes también tienen los identificadores del SRI: su number (001-001-000000001) y su access_key de 49 dígitos.

MetadataCopiar enlace a esta sección

Cada comprobante acepta metadata: hasta 20 pares de texto, con claves de hasta 40 caracteres y valores de hasta 500. La devolvemos tal cual y nunca la interpretamos ni la imprimimos. Es el lugar para guardar tu propio número de pedido o de cliente.

{ "metadata": { "order_id": "1041", "store": "quito-norte" } }