Nota Débito (JSON)

Introducción

Una nota de débito electrónica es un documento que certifica ajustes o incrementos sobre transacciones previas relacionadas con la transferencia de bienes o servicios y posee la misma validez legal que una nota de débito tradicional impresa. La diferencia principal es que se crea, envía y almacena digitalmente. Este documento electrónico debe incluir todos los datos fiscales necesarios que permitan verificar la modificación de la transacción entre el emisor y el receptor, asegurando así la correcta aplicación de cualquier cargo adicional previamente acordado.

Beneficios de la Facturación Electrónica

  • Eficiencia Operativa: La automatización del proceso de facturación reduce la carga administrativa, disminuyendo los errores humanos y acelerando las transacciones.

  • Reducción de Costos: Menores gastos en papel, impresión, envío y almacenamiento de documentos físicos.

  • Acceso y Gestión Simplificados: El almacenamiento digital facilita la búsqueda y gestión de documentos, lo que es especialmente útil para auditorías y cumplimiento fiscal

Autenticación

Para acceder al servicio de facturación electrónica a través de nuestra API REST, los usuarios deben autenticarse utilizando el método de Authorization Bearer Token. Este proceso implica dos pasos principales:

  1. Autenticación Básica: Los usuarios envían sus credenciales (usuario y contraseña) codificadas en base64 en el encabezado de la solicitud.

  2. Identificador del Servicio: Junto con las credenciales, los usuarios deben especificar el identificador del servicio que desean utilizar.

  3. Generación del Token: Los usuarios pueden generar el token enviando una solicitud [GET] a URL_API_AUTH/ServicioEDOC, incluyendo el identificador del servicio deseado.

Servicios Disponibles

Cada servicio dentro de la plataforma tiene un identificador único que debe ser proporcionado durante la solicitud de autenticación. A continuación, se muestra una tabla con los identificadores y nombres de los servicios disponibles:

ID
Servicio

1

Emisión de Comprobante

2

Recepción de Comprobante

3

Consulta de Emisión

4

Consulta de Recepción

15

Manifiesto Receptor

16

Anulación

Seguridad y Manejo del Token

  • Almacenamiento Seguro: Es esencial que el token se almacene de manera segura para evitar accesos no autorizados.

  • Caducidad y Renovación: Los tokens tienen un período de validez limitado y deben ser renovados periódicamente.

  • Revocación de Tokens: En caso de compromiso, el token debe ser revocado inmediatamente.

Autenticación

get
Autorizaciones
AuthorizationstringRequerido
Parámetros de consulta
Idinteger · int64Opcional

Identificador del servicio: 1. Emisión documento, 2. Recepción documento, 3. Consulta emisión, 4. Consulta recepción, 15. Manifiesto Receptor, 16. Anulación

Respuestas
200

OK. Procesado correctamente.

application/json
get
/ServicioEDOC

Emisión de Nota Débito

En esta sección, abordaremos los detalles técnicos específicos del proceso de emisión de notas de débito electrónicas utilizando la tecnología REST. Exploraremos cómo este enfoque facilita la integración eficiente y segura de los sistemas de facturación dentro de las infraestructuras empresariales existentes, asegurando la conformidad con los estándares legales y fiscales relevantes. Nos centraremos en la implementación de REST para describir las interacciones entre los sistemas y los métodos empleados para la transmisión de datos de facturación electrónica.

En esta sección, abordaremos los detalles técnicos específicos del proceso de emisión de notas de crédito electrónicas utilizando la tecnología REST. Exploraremos cómo este enfoque facilita la integración eficiente y segura de los sistemas de facturación dentro de las infraestructuras empresariales existentes, asegurando la conformidad con los estándares legales y fiscales relevantes. Nos centraremos en la implementación de REST para describir las interacciones entre los sistemas y los métodos empleados para la transmisión de datos de facturación electrónica.

Estados eDoc

La gestión adecuada de los estados eDoc es crucial en el sistema de facturación electrónica, ya que cada estado refleja una etapa específica en el proceso de validación y envío de documentos a la entidad tributaria. A continuación, se presenta una tabla que describe cada uno de los estados eDoc, proporcionando claridad sobre las acciones necesarias según el estado en que se encuentre el documento.

Estado
Descripción del Estado
Reenviar
Consultar
Acción Recomendada

2

Documento autorizado, cumple con todo lo requerido por la DGII y el ente tributario.

NO

NO

No se requieren acciones adicionales.

4

Error de procesamiento en eDoc, se debe radicar un ticket de atención en nuestra mesa de ayuda.

SI

NO

Notificar a soporte técnico. No reenviar automáticamente.

5

El documento fue recibido, pero no hubo respuesta a la consulta del estado hacia la entidad tributaria.

NO

SI

No reenviar. Consultar el estado del documento nuevamente.

6

Documento devuelto por el ente tributario, no cumple con las especificaciones del XML en campos obligatorios. Se debe corregir datos y volver a enviar con el mismo secuencial del documento rechazado.

SI

NO

Corregir según indicaciones y luego reenviar manualmente.

7

El documento no fue recibido por la entidad tributaria.

NO

SI

No reenviar. Consultar el estado del documento.

11

Documento anulado en el ente tributario.

NO

NO

No se requieren acciones adicionales.

15

Documento devuelto por eDoc previo a generación del XML por posible duplicidad, credenciales inválidas o Tipo de Documento no reconocido.

NO

SI

Si el documento es duplicado consultar el documento si ha sido autorizado previamente; Si las credenciales son invalidas verificar que se esté enviando la información correcta; y Si envía el documento en la clase equivocada se debe corregir y volver a enviar el mismo documento

18

Documento no encontrado en Edoc

NO

NO

Verificar que se esté enviando la información correcta

20

eDoc no se puede contactar al PAC, se realiza un posterior envío automático

NO

SI

Consulta el estado final del documento

  • Estado Autorizado (2): Este estado indica que el documento ha sido autorizado por la entidad tributaria. En este punto, no se requiere ninguna acción adicional como reenvío o consulta del estado, pues el documento ya ha completado su proceso satisfactoriamente.

  • Estados Transitorios (5, 7, 10, 20): Estos estados reflejan las fases intermedias en el proceso de envío y recepción de documentos con la entidad tributaria. En todos estos casos, no se deben reenviar los documentos, sino consultar su estado hasta que cambien a una situación definitiva.

  • Estados de Error y Corrección (4, 6, 15): El estado 4 indica un error en el proceso de envío o procesamiento, y no debe reenviarse automáticamente; es necesario revisar el error específico y corregirlo si es posible. El estado 6 se asigna a documentos rechazados por la entidad tributaria y requiere corrección manual antes de un reenvío. El estado 15 sugiere que el documento fue devuelto por eDoc empresarial y debe ser analizado para determinar la causa y decidir las acciones correctivas apropiadas. En estos casos, la corrección de errores es fundamental antes de cualquier intento de reenvío.

  • Estado de Anulación (11): Este estado indica que el documento ha sido anulado y, por lo tanto, ya no tiene validez legal o administrativa. No se requieren acciones adicionales para documentos en este estado, ya que han sido efectivamente retirados del proceso.

Consideraciones Importantes

  • Consultas de Estado: Para los estados que sugieren consultar el estado del documento, es recomendable establecer un intervalo regular de consultas para evitar la saturación del sistema y asegurar la actualización oportuna del estado del documento.

  • Notificaciones a Soporte: En casos de errores que no pueden ser resueltos directamente por el usuario, como el estado 4, es fundamental notificar al soporte técnico proporcionando todos los detalles necesarios para una rápida resolución del problema.

Diccionario de datos

Consumo

Recibe una nota de débito electrónica emitida para su firmado, transmisión al ente de autorización y posterior envío por correo electrónico al receptor.

post
Autorizaciones
AuthorizationstringRequerido

Ingrese cadena de autorización: JWT-Token

Cuerpo

Estructura del documento Nota de Débito

dSegstringOpcional

Número aleatorio entre 000,000,001 y 999,999,999, que integra el CUFE y tiene por objetivo asegurar la privacidad de las FE emitidas No se admite el valor “000,000,000”, ni que sea igual al campo B07. Llenar con ceros las posiciones a la izquierda. Origen: DGI

Opcional

Min: 9 - Max: 9

Example: 001125287
cufestringOpcional

Código Único de Factura Electrónica Origen: DGI

Opcional

Min: 66 - Max: 66

Example: FE0120000155668001-2-2018-3707892023061300000002040060120011252872
iTpEmisstringRequerido

Tipo de emisión (01:Autorización Previa normal, 02:Autorización Previa contingencia, 03:Autorización Posterior normal, 04:Autorización Posterior contingencia) Origen: DGI

Obligatorio

Min: 2 - Max: 2

Example: 01
dFechaContstring · date-timeOpcional

Fecha y hora de inicio de la operación en contingencia Origen: DGI

Condicional

Min: 25 - Max: 25

Obligatorio si iTpEmis = 02 y/o 04

Example: 2022-01-17T09:09:00-05:00
dMotContstringOpcional

Razón de la operación en contingencia Origen: DGI

Condicional

Min: 15 - Max: 250

Obligatorio si iTpEmis = 02 y/o 04 Si la contingencia dura más de 72 horas también debe explicar las razones para no haber regresado a la operación normal

Example: Sin internet
iDocstringOpcional

Tipo de emisión: 01: Factura de Operación Interna 02: Factura de Importación 03: Factura de Exportación 04: Nota de Crédito Referente a una o Varias FE 05: Nota de Débito Referente a una o Varias FE 06: Nota de Crédito Genérica 07: Nota de Débito Genérica 08: Factura de Zona Franca 09: Reembolso 10: Factura de operación extranjera Origen: DGI

Obligatorio

Min: 2 - Max: 2

Example: 01
dNroDFinteger · int64Opcional

Número del documento fiscal en la serie correspondiente, de 1 a 9999999999 Origen: DGI

Obligatorio

Min: 1 - Max: 10

No se admite el valor “cero” Llenar con ceros las posiciones a la izquierda Sólo se deben colocar números y se define Alfanumérico porque debe ser rellanado con ceros (0) a la izquierda.

Example: 100
dPtoFacDFinteger · int32Opcional

Punto de Facturación del documento fiscal. Origen: DGI

Obligatorio

Min: 1 - Max: 3

No se admite el valor “cero” Llenar con ceros las posiciones a la izquierda Sólo se deben colocar números y se define Alfanumérico porque debe ser rellanado con ceros (0) a la izquierda.

Example: 3
dFechaEmstring · dateRequerido

Fecha de emisión del documento Origen: DGI

Obligatorio

Min: 25 - Max: 25

No se admite el valor “cero” Llenar con ceros las posiciones a la izquierda Sólo se deben colocar números y se define Alfanumérico porque debe ser rellanado con ceros (0) a la izquierda.

Example: 2023-01-17T09:09:00-05:00
dFechaSalidastring · date-timeOpcional

Fecha de salida estimada de las mercancías Origen: DGI

Condicional Min: 25 - Max: 25

Informar cuando sea conocida

Example: 2023-01-17T09:09:00-05:00
iNatOpstringOpcional

Naturaleza de la Operación 01: Venta 02: Exportación 03: Re-exportación, 04: Venta de fuente extranjera, 10: Transferencia/Traspaso 11: Devolución 12: Consignación 13: Remesa 14: Entrega gratuita 20: Compra 21: Importación Origen: DGI

Obligatorio

Min: 2 - Max: 2

Example: 01
iTipoOpinteger · int32Opcional

Tipo de la operación (1: Salida o venta 2: Entrada o compra (factura de compra- para comercio informal. Ej.: taxista, trabajadores manuales)) Origen: DGI

Obligatorio

Min: 1 - Max: 1

1:Venta- para operaciones de venta ya se de productos o servicio

Example: 1
iDestinteger · int32Opcional

Destino de la operación (1: Panamá 2: Extranjero) Origen: DGI

Obligatorio

Min: 1 - Max: 3

1: Panamá- para ventas en el area Nacional

Example: 1
iFormCAFEinteger · int32Opcional

Formato de generación del CAFÉ 1: Sin generación de CAFE El emisor podrá decidir generar CAFE en cualquier momento posterior a la autorización de uso de FE. 2: Cinta de papel 3: Papel formato carta Origen: DGI

Obligatorio

Min: 1 - Max: 1

3: Papel formato carta

Example: 3
iEntCAFEinteger · int32Opcional

Manera de entrega del CAFE al receptor 1: Sin generación de CAFE  El emisor podrá decidir generar CAFE en cualquier momento posterior a la autorización de uso de FE 2: CAFE entregado para el receptor en papel 3: CAFE enviado para el receptor en formato electrónico. Origen: DGI

Obligatorio

Min: 1 - Max: 1

3: CAFE enviado para el receptor en formato electrónico.

Example: 3
dEnvFEinteger · int32Opcional

Envío del contenedor para el receptor 1: normal 2: El receptor exceptúa al emisor de la obligatoriedad de envío del contenedor. El emisor podrá decidir entregar el contenedor, por cualquier razón, en momento posterior a la autorización de uso, pero no era esta su intención en el momento de la emisión de la FE. Origen: DGI

Obligatorio

Min: 1 - Max: 1

1: normal

Example: 1
iProGeninteger · int32Opcional

Proceso de generación de la FE 1: Generación por el sistema de facturación del contribuyente (desarrollo propio o producto adquirido) 2: Generación por tercero contratado 3: Generación gratuita por tercero proveedor de solución 4: Generación gratuita por la DIRECCIÓN GENERAL DE INGRESOS en página web Origen: DGI

Obligatorio

Min: 1 - Max: 1

2: Generación por tercero contratado

Example: 2
iTipoSucinteger · int32Opcional

Tipo de Sucursal (1:Mayor cantidad de Operaciones venta al detal, 2:Mayor cantidad de Operaciones venta al por mayor) Origen: DGI

Condicional

Min: 1 - Max: 1

2:Mayor cantidad de Operaciones venta al por mayor

Example: 2
iTipoTranVentainteger · int32Opcional

Tipo de transacción de venta: 1: Venta de Giro del negocio 2: Venta Activo Fijo 3: Venta de Bienes Raíces 4: Prestación de Servicio Si no es venta, no informar este campo Origen: DGI

Condicional

Min: 1 - Max: 1

Tipo de Venta para el vendedor: 1: Venta de Giro del negocio

Example: 1
dInfEmFEstringOpcional

Información de interés del emisor con respeto a la FE Origen: DGI

Opcional

Min: 0 - Max: 5000

Se puede enviar varios datos adicionales separados por punto y coma (;) y mapear en el modelo CAFE en la posición que se requiera

Example: Informacion del emisor 1;Informacion del emisor 2
emailResponsablestringOpcional

Correo del responsable del documento Origen: GS

Opcional

Min: 0 - Max: 150

Example: [email protected]
secuencialERPstringOpcional

Código único del documento utilizado en ERP Origen: GS

Opcional

Min: 0 - Max: 30

Example: 930054013130000001
usuarioTransaccionERPstringOpcional

Usuario generó el documento Origen: GS

Opcional

Min: 0 - Max: 30

Example: gurusoft
codigoTransaccionERPstringOpcional

Código del documento utilizado en el ERP Origen: GS

Opcional

Min: 0 - Max: 30

Example: 9300540131
campo1stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo1
campo2stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo2
campo3stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo3
campo4stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo4
campo5stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo5
campo6stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo6
campo7stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo7
campo8stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo8
campo9stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo9
campo10stringOpcional

Campo con información adicional Origen: GS

Opcional

Min: 0 - Max: 1000

Example: Campo10
nombreIntegracionstringOpcional

Nombre de la integración Origen: GS

Opcional

Min: 0 - Max: 100

Example: ERP X
ipstringOpcional

IP de origen de la comunicación Origen: GS

Opcional

Min: 0 - Max: 50

Example: 192.168.0.1
offlinebooleanOpcional

Indica si la autorización sera false: previa o true: posterior Origen: GS

Opcional

Respuestas
200

La petición se ha procesado correctamente. No obstante, es necesario verificar el 'estado eDoc' para confirmar si el documento electrónico ha sido autorizado o rechazado, según los estados definidos.

application/json
post
/NotaDebito

Última actualización

¿Te fue útil?