Clientes

Concepto

Un cliente representa una entidad jurídica o física que puede emitir documentos electrónicos.

Hay dos categorias de clientes:

• Cliente directo.
• Cliente bajo integración.

Cliente directo

Un cliente directo es el que interactua con el API sin necesidad de integradores (intermediarios). Puede ser un software que gestione la facturación de una entidad y se comunique directamente con el API para el procesamiento de documentos, pero solamente para su entidad.

Cliente bajo integración

Un cliente bajo integración no es consciente de la interacción con el API, todas sus acciones las realiza directamente con el sistema integrador delegando totalmente sus acciones al integrador.

Autenticación y Seguridad

El API de Facturación Electrónica para Costa Rica utiliza Basic Authentication más un TOKEN único como método de autenticación, esto sobre HTTPS para garantizar la seguridad.

Cada cliente recibirá un AUTH TOKEN que debe enviar en los HTTP Headers de cada request.

Como parte del Basic Authentication se proveerá:

• Usuario
• Contraseña

Ejemplo - POST /api/documents/v4

Endpoint para autenticarse, tanto integradores como cualquier tipo de clientes utiliza este endpoint para pedir un JWT que puede usar en sub siguientes llamadas al API.

Los siguientes headers deben enviarse:

• AuthToken: TOKEN único que enlaza la petición a una configuración de sucursal especifíca.
• Authorization: Header estándar de Basic Authentication.

Ejemplo de llamada:

                    
    curl -X 'POST' \
    'https://api44.qupos.com/api/documents/v4' \
    -H 'accept: text/plain' \
    -H 'AuthToken: TOKEN_UNICO' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Basic bmNxOk5DUVXXXXXXXXAwNzA1' \
    -H 'Content-Type: application/json' \
    -d '{
        "id_externo" : "56",
        "tipo_documento": "01",
        "registro_fiscal8707": "123456789112",
        "codigo_actividad_emisor": "123456",
        "fecha_emision": "2025-05-06T13:00:00",
        "clave": "50603042300310140926100200001050000019023171187576",
        ...  
    }'
                        
                      

Documentos electrónicos

La facturación electrónica está regulada por el Ministerio de Hacienda bajo la Dirección General de Tributación.

Factura electrónica - 01

• Documento principal que respalda la venta de bienes o la prestación de servicios.
• Es obligatorio para contribuyentes inscritos como emisores electrónicos.

Nota de débito electrónica - 02

• Se usa para aumentar el valor de una factura electrónica previamente emitida.
• Por ejemplo, para cargos adicionales por intereses o servicios posteriores.

Nota de crédito electrónica - 03

• Documento que se utiliza para anular o modificar total o parcialmente una factura o tiquete electrónico.
• Sirve para hacer devoluciones, descuentos, errores en el precio, etc.

Tiquete electrónico - 04

• Se utiliza para ventas al consumidor final.
• No requiere incluir identificación del comprador (aunque puede hacerse opcionalmente).
• Su uso está limitado a montos menores y actividades de venta directa.

Confirmación de aceptación del comprobante electrónico - 05

Es el mensaje electrónico que el receptor (comprador) debe enviar al emisor para aceptar un documento tributario

Confirmación de aceptación parcial del comprobante electrónico - 06

Es el mensaje electrónico que el receptor (comprador) debe enviar al emisor para aceptar parcialmente un documento tributario

Confirmación de rechazo del comprobante electrónico - 07

Es el mensaje electrónico que el receptor (comprador) debe enviar al emisor para rechazar parcialmente un documento tributario

Factura electrónica de compras - 08

Factura electrónica de exportación - 09

Recibo Electrónico de Pago - 10

Validaciones Documentos

Al enviar un documento electrónico, este debe cumplir con las siguientes validaciones:

• Datos Generales
• Receptor
• Identificación
• Ubicación
• Teléfono
• Detalle
• Otros Cargos
• Identificación Tercero
• Resumen
• Medios de Pago
• Información de Referencia