{"swagger": "2.0", "info": {"title": "API de Factura Fácil", "description": "API para el manejo de facturas y otros documentos en Factura Fácil. <br>Para obtener algunos ejemplos de código puede visitar nuestro repositorio público en: https://github.com/Factura-Facil/ejemplos", "termsOfService": "https://www.facturafacil.com.pa", "contact": {"email": "info@facturafacil.com.pa"}, "version": "v1"}, "host": "api.facturafacil.com.pa", "schemes": ["https"], "basePath": "/", "consumes": ["application/json"], "produces": ["application/json"], "securityDefinitions": {"Basic": {"type": "basic"}}, "security": [{"Basic": []}], "paths": {"/api/pac/event/": {"get": {"operationId": "api_pac_event_list", "summary": "Lista de eventos", "description": "Lista de eventos a documentos de factura electrónica", "parameters": [{"name": "length", "in": "query", "description": "Number of results to return per page.", "required": false, "type": "integer"}, {"name": "start", "in": "query", "description": "The initial index from which to return the results.", "required": false, "type": "integer"}, {"name": "X-FF-Company", "in": "header", "description": "UUID del emisor", "required": true, "type": "string", "format": "uuid", "default": "X-FF-Company"}, {"name": "X-FF-API-Key", "in": "header", "description": "Clave de API válida", "required": true, "type": "string"}], "responses": {"200": {"description": "", "schema": {"$ref": "#/definitions/DataTablePaginatedResponse"}}}, "tags": ["Emisión de documentos"]}, "parameters": []}, "/api/pac/event/issue/": {"post": {"operationId": "api_pac_event_issue", "summary": "Emitir eventos", "description": "Emisión de eventos a documentos de factura electrónica", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/EventoPACIssue"}}, {"name": "X-FF-Company", "in": "header", "description": "UUID del emisor", "required": true, "type": "string", "format": "uuid", "default": "X-FF-Company"}, {"name": "X-FF-API-Key", "in": "header", "description": "Clave de API válida", "required": true, "type": "string"}], "responses": {"201": {"description": "", "schema": {"$ref": "#/definitions/EventoPACIssue"}}}, "tags": ["Emisión de documentos"]}, "parameters": []}, "/api/pac/reception_fe/detailed/": {"post": {"operationId": "api_pac_reception_fe_detailed", "summary": "Emitir documentos (FE/NC/ND/Exportación)", "description": "Emisión de Factura Electrónica, Nota de Crédito, Nota de Débito o Exportación.\n\nAutenticación:\n- Requiere API Key válido.\n\nAmbiente:\n- QA: environment=\"2\".\n- Producción: environment=\"1\".\n\nIdentificación del documento:\n- POS (dPtoFacDF): exactamente 3 dígitos (000–999).\n- Número fiscal (dNroDF): 10 dígitos con ceros a la izquierda; sin reinicio de secuencia.\n\nMontos y cálculo:\n- Valores como cadenas con 2 decimales (\"100.00\"); cálculo interno hasta 6 decimales.\n- Redondeo por línea y totales en 2 decimales (half-up).\n- Impuestos: type=\"01\"=ITBMS; code mapea la tasa vigente; se valida contra el catálogo.\n\nSucursal (branch):\n- Teléfono: 8 dígitos sin guiones.\n- Si no existe, enviar branch{ code, address, coordinates, phone, location, email } para registrarla.\n\nReceptor:\n- Consumidor Final: type=\"02\" (sin RUC/DV/ubicación).\n- Contribuyente/Gobierno: type=\"01\"/\"03\" con RUC, DV, address, location (PP-DD-CC).\n- Gobierno (type=\"03\"): items[].gns (CPBS abreviada) obligatorio.\n\nExportación:\n- Si dest_country!=\"PA\", incluir export_info{ incoterms, currency, exchange_rate, value }.\n- Si currency=\"ZZZ\", enviar currency_desc.\n\nNotas de crédito/débito:\n- Obligatorio document.referred{ fd_number | cufe, fd_date }.\n\nContingencia:\n- Si issue_type=contingency, informar contingency_start (ISO-8601 con offset) y contingency_reason.\n\nCatálogos DGI:\n- items[].mu según catálogo oficial; validar CPBS/GNS cuando aplique.\n\nRespuestas:\n- 201 autorizado: rejected=false (incluye cufe, authorization_number, pdf_url, qr_code_data, document_number, process_date).\n- 201 rechazado DGI: rejected=true con messages[]; puede incluir service_response y xml.\n- 400 validación local: messages[] con field_name/path.\n", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"$ref": "#/definitions/Document"}}, {"name": "X-FF-Company", "in": "header", "description": "UUID del emisor", "required": true, "type": "string", "format": "uuid", "default": "X-FF-Company"}, {"name": "X-FF-Branch", "in": "header", "description": "UUID de la sucursal", "required": false, "type": "string", "format": "uuid"}, {"name": "X-FF-API-Key", "in": "header", "description": "Clave de API válida", "required": true, "type": "string"}], "responses": {"201": {"description": "Creado (submission). Puede estar autorizado o rechazado por DGI.", "schema": {"$ref": "#/definitions/DocumentResult"}}, "400": {"description": "Validación local: campos requeridos, formatos inválidos o reglas de negocio.", "schema": {"$ref": "#/definitions/ErrorResponse"}, "examples": {"application/json": {"messages": [{"code": "400", "type": "R", "message": "Este campo es requerido cuando no existe header.id"}, {"code": "400", "type": "R", "message": "El ambiente de destino producción no es válido para el ambiente de pruebas"}, {"code": "400", "type": "R", "message": "El ambiente de destino pruebas no es válido para el ambiente de producción"}, {"code": "400", "type": "R", "message": "El código de punto de venta debe ser numérico, ejemplos: 001, 123, 555, 999"}, {"code": "400", "type": "R", "message": "El código de punto de venta debe estar en el rango 001-999"}, {"code": "400", "type": "R", "message": "La fecha de emisión no puede ser mayor a 2 días desde la fecha actual"}, {"code": "400", "type": "R", "message": "Se debe informar la sucursal que emite la factura"}, {"code": "400", "type": "R", "message": "Sucursal de destino no valida en el cuerpo o en la cabecera de la peticion"}, {"code": "400", "type": "R", "message": "La dirección es requerida si la sucursal no existe en el sistema"}, {"code": "400", "type": "R", "message": "Las coordenadas son requeridas si la sucursal no existe en el sistema"}, {"code": "400", "type": "R", "message": "El teléfono es requerido si la sucursal no existe en el sistema"}, {"code": "400", "type": "R", "message": "La ubicación es requerida si la sucursal no existe en el sistema"}, {"code": "400", "type": "R", "message": "Coordenadas inválidas, debe tener el formato: latitud,longitud"}, {"code": "400", "type": "R", "message": "Coordenadas inválidas, deben 2 números decimales separados por coma"}, {"code": "400", "type": "R", "message": "El código de seguridad debe ser un número de 9 dígitos"}, {"code": "400", "type": "R", "message": "Asegure un entero entre 0 y 9,999,999,999 (enviar 0 para usar secuencia interna)"}, {"code": "400", "type": "R", "message": "No less than 1 item is allowed"}, {"code": "400", "type": "R", "message": "No more than 1000 items are allowed"}, {"code": "400", "type": "R", "message": "No less than 1 payment is allowed"}, {"code": "400", "type": "R", "message": "No more than 10 payments are allowed"}, {"code": "400", "type": "R", "message": "El valor del descuento debe ser menor que el precio unitario del ítem"}, {"code": "400", "type": "R", "message": "Campo requerido"}, {"code": "400", "type": "R", "message": "Precio unitario inválido (use ≥ 0.00 con hasta 6 decimales)"}, {"code": "400", "type": "R", "message": "Cantidad inválida (use > 0 con hasta 6 decimales)"}, {"code": "400", "type": "R", "message": "Descripción requerida (mínimo 2 caracteres)"}, {"code": "400", "type": "R", "message": "GNS do not exists"}, {"code": "400", "type": "R", "message": "No items found in document data"}, {"code": "400", "type": "R", "message": "El país de destino es obligatorio para facturas de exportación y debe ser distinto a PA = Panamá"}, {"code": "400", "type": "R", "message": "La información de exportación es obligatoria para facturas de exportación (dest_country != \"PA\")"}, {"code": "400", "type": "R", "message": "Grupo de Datos de Facturas en Caso de Exportación informado en operación interna"}, {"code": "400", "type": "R", "message": "Siglas no válidas (usar catálogo DGI)"}, {"code": "400", "type": "R", "message": "Moneda no válida"}, {"code": "400", "type": "R", "message": "La descripción de la moneda es obligatoria cuando la moneda es ZZZ"}, {"code": "400", "type": "R", "message": "El tipo de cambio es obligatorio cuando se informa una moneda distinta a USD"}, {"code": "400", "type": "R", "message": "El valor de la exportación es obligatorio cuando se informa una moneda distinta a USD"}, {"code": "400", "type": "R", "message": "El dígito verificador es requerido si el tipo de receptor es contribuyente o gobierno"}, {"code": "400", "type": "R", "message": "La dirección es requerida si el tipo de receptor es contribuyente o gobierno"}, {"code": "400", "type": "R", "message": "El RUC es requerido si el tipo de receptor es contribuyente o gobierno"}, {"code": "400", "type": "R", "message": "La ubicación es requerida si el tipo de receptor es contribuyente o gobierno y debe corresponder a un código en la tabla de ubicaciones."}, {"code": "400", "type": "R", "message": "El dígito verificador no coincide con el RUC informado"}, {"code": "400", "type": "R", "message": "Ubicación inválida, debe tener el formato: provincia-distrito-corregimiento"}, {"code": "400", "type": "R", "message": "Código de ubicación no encontrado"}, {"code": "400", "type": "R", "message": "El RUC es requerido si el tipo de receptor es extranjero (pasaporte/tributaria extranjera)"}, {"code": "400", "type": "R", "message": "Informado RUC de contribuyente juridico existente en una factura de consumidor final"}, {"code": "400", "type": "R", "message": "No existe un país con el código XX en la tabla de paises validos"}, {"code": "400", "type": "R", "message": "El documento referenciado es obligatorio para notas de crédito y débito"}, {"code": "400", "type": "R", "message": "Número del documento fiscal referenciado inválido (longitud/CUFE)"}, {"code": "400", "type": "R", "message": "Fecha del documento fiscal referenciado requerida (YYYY-MM-DD)"}, {"code": "400", "type": "R", "message": "El código de bien o servicio (item.gns) es obligatorio cuando el tipo de receptor es 03 = Gobierno"}, {"code": "400", "type": "R", "message": "Las cuotas son obligatorias cuando el plazo de pago es a crédito"}, {"code": "400", "type": "R", "message": "No se permiten más de 99 cuotas"}, {"code": "400", "type": "R", "message": "Se debe informar al menos una cuota"}, {"code": "400", "type": "R", "message": "No more than 5 discounts are allowed"}, {"code": "400", "type": "R", "message": "El monto de descuento debe ser ≥ 0.01"}, {"code": "400", "type": "R", "message": "La descripción del descuento es requerida (1-500 caracteres)"}, {"code": "400", "type": "R", "message": "Tipo de pago inválido"}, {"code": "400", "type": "R", "message": "Monto de pago inválido (use ≥ 0.0)"}, {"code": "400", "type": "R", "message": "La descripción es obligatoria cuando el tipo de pago es 99"}, {"code": "400", "type": "R", "message": "Se requiere monto de la retención cuando el tipo es = Otros"}], "rejected": true}}}}, "tags": ["Emisión de documentos"]}, "parameters": []}, "/api/pac/reception_fe/find_by_cufe_or_id/": {"get": {"operationId": "api_pac_reception_fe_find_by_cufe_or_id", "summary": "Consultar documento por CUFE o UUID", "description": "Busca un documento emitido usando un identificador único.\n\n- Si el valor coincide con **UUID v4**, se consulta por `id`.\n- En caso contrario, se asume **CUFE** (debe iniciar con `FE` y tener 66 caracteres) y se consulta por `cufe`.\n- La búsqueda siempre se restringe a la empresa indicada en `X-FF-Company`.", "parameters": [{"name": "length", "in": "query", "description": "Number of results to return per page.", "required": false, "type": "integer"}, {"name": "start", "in": "query", "description": "The initial index from which to return the results.", "required": false, "type": "integer"}, {"name": "X-FF-Company", "in": "header", "description": "UUID del emisor", "required": true, "type": "string", "format": "uuid", "default": "X-FF-Company"}, {"name": "X-FF-API-Key", "in": "header", "description": "Clave de API válida", "required": true, "type": "string"}, {"name": "cufe_or_id", "in": "query", "description": "CUFE o UUID a consultar", "required": true, "type": "string", "pattern": "^FE[0-9\\w-]{64}$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"}], "responses": {"200": {"description": "", "schema": {"$ref": "#/definitions/DocumentStatus"}}, "400": {"description": "Petición no válida (parámetros faltantes o con formato incorrecto).", "examples": {"application/json": {"detail": "Parámetro cufe_or_id inválido"}}}, "401": {"description": "No autorizado. Falta o es inválido el API Key / token."}, "403": {"description": "No autorizado para la compañía indicada."}, "404": {"description": "No se encontró un documento con el identificador indicado."}}, "tags": ["Consultas"]}, "parameters": []}, "/api/pac/reception_fe/{id}/download_cafe/": {"get": {"operationId": "api_pac_reception_fe_download_cafe_list", "summary": "Descargar CAFE", "description": "", "parameters": [{"name": "cufe", "in": "query", "description": "CUFE del documento", "required": true, "type": "string"}, {"name": "id", "in": "path", "description": "UUID del documento", "required": true, "type": "string"}, {"name": "copies", "in": "query", "description": "Cantidad de copias. Las copias se añaden al mismo PDF como páginas adicionales. Máximo 5 copias", "required": false, "type": "integer"}, {"name": "view", "in": "query", "description": "Genera una respuesta sin attachment para que se pueda ver en un navegador sin disparar la descarga", "required": false, "type": "boolean"}], "responses": {"200": {"description": ""}}, "tags": ["Consultas"]}, "parameters": [{"name": "id", "in": "path", "required": true, "type": "string"}]}, "/api/pac/reception_fe/{id}/download_xml/": {"get": {"operationId": "api_pac_reception_fe_download_xml", "summary": "Descargar XML", "description": "Descarga el XML de un documento", "parameters": [{"name": "cufe", "in": "query", "description": "CUFE del documento", "required": true, "type": "string"}, {"name": "id", "in": "path", "description": "UUID del documento", "required": true, "type": "string"}], "responses": {"200": {"description": "application/xml"}}, "tags": ["Consultas"]}, "parameters": [{"name": "id", "in": "path", "description": "A UUID string identifying this documento emitido.", "required": true, "type": "string", "format": "uuid"}]}, "/api/pac/reception_fe/{id}/send_email/": {"post": {"operationId": "api_pac_reception_fe_send_email", "summary": "Enviar documento por correo", "description": "", "parameters": [{"name": "data", "in": "body", "required": true, "schema": {"type": "object", "properties": {"email": {"description": "Correo electrónico del receptor", "type": "string"}}}}, {"name": "X-FF-Company", "in": "header", "description": "UUID del emisor", "required": true, "type": "string", "format": "uuid", "default": "X-FF-Company"}, {"name": "X-FF-API-Key", "in": "header", "description": "Clave de API válida", "required": false, "type": "string"}, {"name": "id", "in": "path", "description": "UUID o CUFE del documento", "type": "string", "required": true}], "responses": {"200": {"description": "", "schema": {"type": "object", "properties": {"detail": {"description": "Resultado", "type": "string"}}}}}, "tags": ["Emisión de documentos"]}, "parameters": [{"name": "id", "in": "path", "description": "A UUID string identifying this documento emitido.", "required": true, "type": "string", "format": "uuid"}]}}, "definitions": {"EventoPAC": {"required": ["id", "response_ff", "response_dgi", "created_at", "updated_at", "document"], "type": "object", "properties": {"id": {"title": "Id", "type": "string", "format": "uuid"}, "response_ff": {"title": "Response ff", "type": "string", "minLength": 1}, "response_dgi": {"title": "Response dgi", "type": "string", "minLength": 1}, "reason": {"title": "Reason", "type": "string", "x-nullable": true}, "code": {"title": "Code", "type": "string", "maxLength": 4, "x-nullable": true}, "error": {"title": "Error", "type": "integer", "maximum": 2147483647, "minimum": -2147483648, "x-nullable": true}, "xml_data": {"title": "Xml data", "type": "string", "x-nullable": true}, "created_at": {"title": "Created at", "type": "string", "format": "date-time"}, "updated_at": {"title": "Updated at", "type": "string", "format": "date-time"}, "document": {"title": "Document", "type": "string"}}}, "DataTablePaginatedResponse": {"required": ["draw", "recordsFiltered", "data"], "type": "object", "properties": {"draw": {"title": "Draw", "description": "Number of this response (as sent in request) or 0 if no draw number specified", "type": "integer"}, "recordsFiltered": {"title": "Recordsfiltered", "description": "Total records, before filtering", "type": "integer"}, "data": {"type": "array", "items": {"$ref": "#/definitions/EventoPAC"}}}}, "EventoPACIssue": {"required": ["type", "cufe"], "type": "object", "properties": {"code": {"title": "Code", "type": "string", "maxLength": 4, "minLength": 4, "x-nullable": true}, "reason": {"title": "Reason", "type": "string", "maxLength": 500, "minLength": 15}, "type": {"title": "Type", "type": "string", "enum": ["AN", "MF"]}, "cufe": {"title": "Cufe", "type": "string", "maxLength": 66, "minLength": 66}, "rejected": {"title": "Rejected", "type": "boolean", "readOnly": true}, "digest_value": {"title": "Digest value", "type": "string", "readOnly": true, "minLength": 1}, "auth_date": {"title": "Auth date", "type": "string", "readOnly": true, "minLength": 1}, "response": {"title": "Response", "type": "string", "readOnly": true, "minLength": 1}, "message": {"title": "Message", "type": "string", "readOnly": true, "minLength": 1}}}, "DocumentBranch": {"description": "Información de la sucursal que emite la factura. Si no se informa se debe informar el UUID de la sucursal en la cabecera HTTP X-FF-Branch o el API Key debe ser especifico para la Sucursal", "required": ["code"], "type": "object", "properties": {"code": {"title": "Código de sucursal", "description": "Código de sucursal", "type": "string", "maxLength": 4, "minLength": 4}, "coordinates": {"title": "Coordenadas", "description": "Coordenadas de la sucursal emisora del documento. Ejemplo: +08.9539,-79.5343", "type": "string", "maxLength": 20, "minLength": 14}, "address": {"title": "Dirección", "description": "Dirección de la sucursal emisora del documento", "type": "string", "maxLength": 100, "x-nullable": true}, "phone": {"title": "Teléfono", "description": "Teléfono de la sucursal emisora del documento", "type": "string", "default": "999-9999", "maxLength": 9, "x-nullable": true}, "email": {"title": "Correo electrónico", "type": "string", "format": "email", "maxLength": 100, "x-nullable": true}, "location": {"title": "Ubicación", "description": "Código compuesto de la ubicación del la sucursal emisora", "type": "string", "maxLength": 8, "minLength": 5}}}, "DocumentHeader": {"description": "Información general del documento", "required": ["environment"], "type": "object", "properties": {"id": {"title": "Identificador", "description": "Identificador de control de envío. Para control interno del cliente. No requerido si existe system_ref", "type": "string", "minLength": 1}, "environment": {"title": "Ambiente", "description": "Ambiente en el que se emite la factura.\n 1=Producción, 2=Pruebas", "type": "string", "enum": ["1", "2"]}, "branch": {"$ref": "#/definitions/DocumentBranch"}, "issue_date": {"title": "Fecha/hora de emisión", "description": "Fecha/hora de emisión del documento. Formato: YYYY-MM-DD H:M:S. Si no se informa se toma la fecha actual", "type": "string", "format": "date-time"}, "pos": {"title": "Código de punto de venta", "description": "Código de punto de venta (POS). Si no se informa se toma 001", "type": "string", "default": "001", "maxLength": 3, "minLength": 3}}}, "DocumentReceptor": {"description": "Información del receptor del documento", "required": ["type", "name"], "type": "object", "properties": {"type": {"title": "Tipo de receptor", "description": "Identifica el tipo de receptor de la FE\n 01=Contribuyente, 02=Consumidor final, 03=Gobierno, 04=Extranjero", "type": "string", "enum": ["01", "02", "03", "04"]}, "name": {"title": "Nombre", "description": "Razón social o nombre y apellido del receptor de la FE", "type": "string", "maxLength": 100, "minLength": 1}, "ruc": {"title": "RUC", "description": "RUC del receptor de la FE, si el tipo de receptor es consumidor final puede llenarlo con la cédula de identificación del ciudadano si este lo solicita .", "type": "string", "maxLength": 20, "x-nullable": true}, "ruc_type": {"title": "Tipo de contribuyente", "description": "Valores posibles:\n 1=Natural, 2=Jurídico", "type": "string", "enum": ["1", "2"], "x-nullable": true}, "address": {"title": "Dirección", "description": "Dirección del receptor de la FE", "type": "string", "maxLength": 100, "x-nullable": true}, "email": {"title": "Correo electrónico", "description": "Correo electrónico del receptor de la FE", "type": "string", "maxLength": 255, "x-nullable": true}, "dv": {"title": "Dígito verificador", "description": "Dígito verificador del RUC del receptor de la FE. Es requerido y debe ser válido si el receptor es Contribuyente o Gobierno.", "type": "string", "maxLength": 2, "x-nullable": true}, "location": {"title": "Ubicación", "description": "Código compuesto de la ubicación del receptor de la FE", "type": "string", "maxLength": 8, "minLength": 5}, "country": {"title": "Country", "description": "País del documento del receptor de la FE. Solo si el tipo de documento es Pasaporte", "type": "string", "maxLength": 2, "minLength": 2}}}, "DocumentReferred": {"description": "Obligatorio si el documento es una nota de crédito o débito con documento referenciado", "required": ["fd_number", "fd_date"], "type": "object", "properties": {"fd_number": {"title": "Número", "description": "Número del documento fiscal referenciado, si la longitud es de 66 carácteres se tratará como CUFE.", "type": "string", "maxLength": 66, "minLength": 1}, "fd_date": {"title": "Fecha", "description": "Fecha de emisión del documento fiscal referenciado. Formato: YYYY-MM-DD", "type": "string", "format": "date"}}}, "DocumentItemTax": {"description": "Impuestos del ítem", "required": ["type", "amount"], "type": "object", "properties": {"type": {"title": "Tipo", "description": "Valores posibles:\n 01=ITBMS, 02=OTI, 03=ISC", "type": "string", "enum": ["01", "02", "03"]}, "code": {"title": "Código", "description": "Código del impuesto. Requerido para ITBMS y OTI. Valores posibles:\nPara ITBMS: 00 = Exento, 01 = 7%, 02 = 10%, 03 = 15%\nPara OTI: 00 = Cero, 01 = SUME911, 02 = Portabilidad númerica, 03 = Impuesto sobre seguro", "type": "string", "maxLength": 2, "minLength": 2}, "amount": {"title": "Monto", "description": "Monto del impuesto para el item", "type": "string", "format": "decimal"}, "rate": {"title": "Tasa", "description": "Tasa del impuesto para el item. Sólo aplica para ISC", "type": "string", "format": "decimal"}}}, "InvoiceItemsMedicine": {"description": "Obligatorio si el ítem es medicina o materia prima farmacéutica", "required": ["batch_number", "batch_quantity"], "type": "object", "properties": {"batch_number": {"title": "Número de lote", "description": "Número de lote de medicinas y materias primas farmacéuticas", "type": "string", "maxLength": 35, "minLength": 5}, "batch_quantity": {"title": "Cantidad de productos en el lote", "description": "Cantidad de productos en el lote de medicinas y materias primas farmacéuticas", "type": "integer", "minimum": 1}}}, "DocumentItem": {"description": "Grupo de datos que especifica cada ítem del detalle de la transacción", "required": ["line", "price", "quantity", "description", "taxes", "discount"], "type": "object", "properties": {"line": {"title": "Línea", "description": "Número secuencial del ítem", "type": "integer", "minimum": 1}, "price": {"title": "Precio unitario", "description": "Precio unitario de la transferencia del bien o servicio\nSi el ítem no es valorable: informar campo en 0.00", "type": "string", "format": "decimal"}, "mu": {"title": "Unidad de medida", "description": "Unidad de medida del código interno", "type": "string", "maxLength": 20, "minLength": 1}, "quantity": {"title": "Cantidad", "description": "Cantidad del producto o servicio, en la unidad de medida del código interno", "type": "string", "format": "decimal"}, "internal_code": {"title": "Código interno del item", "description": "Código interno del Ítem", "type": "string", "maxLength": 20, "x-nullable": true}, "description": {"title": "Descripción", "description": "Descripción del producto o servicio", "type": "string", "maxLength": 500, "minLength": 2}, "expiration_date": {"title": "Fecha de caducidad", "description": "Fecha de Fecha de caducidad del producto. Formato: YYYY-MM-DD", "type": "string", "format": "date", "x-nullable": true}, "manufacturing_date": {"title": "Fecha de fabricación", "description": "Fecha de fabricación del producto. Formato: YYYY-MM-DD", "type": "string", "format": "date", "x-nullable": true}, "taxes": {"description": "Impuestos del ítem", "type": "array", "items": {"$ref": "#/definitions/DocumentItemTax"}}, "discount": {"title": "Descuento", "description": "Descuento en el precio unitario del ítem\nInformar valor del descuento en Balboas, no en porcentaje.\nEl valor informado debe ser menor que el precio unitario del ítem\nSi el ítem no es valorable: No informar el campo.", "type": "string", "format": "decimal"}, "gns": {"title": "Código en CPBS", "description": "Código del Ítem en la Codificación Panameña de Bienes y Servicios\nCampo obligatorio si el tipo de receptor es 03 = Gobierno", "type": "string", "maxLength": 4}, "medicine": {"$ref": "#/definitions/InvoiceItemsMedicine"}, "additional_info": {"title": "Additional info", "type": "string", "maxLength": 5000}}}, "DocumentPayment": {"description": "Grupo de datos que especifica cada forma de pago de la transacción", "required": ["type", "amount"], "type": "object", "properties": {"type": {"title": "Tipo de pago", "description": "Valores posibles:\n 01=Crédito, 02=Efectivo, 03=Tarjeta de crédito, 04=Tarjeta de débito, 05=Tarjeta de fidelidad, 06=Vale, 07=Tarjeta de regalo, 08=Transferencia o déposito bancario, 09=Cheque, 10=Punto de venta, 99=Otro", "type": "string", "enum": ["01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "99"]}, "amount": {"title": "Monto", "description": "Monto del pago", "type": "number", "minimum": 0.0}, "description": {"title": "Descripción", "description": "Descripción del pago (opcional excepto cuando el tipo de pago es 99)", "type": "string", "maxLength": 100, "minLength": 10}}}, "ExportGroup": {"description": "Detalle de la exportación. Obligatoria para factura de exportación", "required": ["incoterms"], "type": "object", "properties": {"incoterms": {"title": "Incoterms", "description": "Debe corresponder a una de las siglas soportadas por la DGI", "type": "string", "maxLength": 3, "minLength": 3}, "currency": {"title": "Currency", "description": "Código de moneda soportado por la DGI", "type": "string", "maxLength": 3, "minLength": 3, "x-nullable": true}, "currency_desc": {"title": "Currency desc", "description": "Descripción de la moneda (en el caso de que la moneda sea ZZZ = otra)", "type": "string", "minLength": 1}, "exchange_rate": {"title": "Exchange rate", "description": "Tasa de cambio si la moneda de exportación es diferente a USD. Obligatorio si se envía currency", "type": "string", "format": "decimal", "x-nullable": true}, "value": {"title": "Value", "description": "Valor de la exportación en la moneda de exportación. Obligatorio si se envía currency que no sea USD", "type": "string", "format": "decimal"}, "port_of_shipment": {"title": "Port of shipment", "type": "string", "maxLength": 50, "minLength": 5, "x-nullable": true}}, "x-nullable": true}, "Withholding": {"description": "Retenciones aplicadas a la factura", "required": ["code"], "type": "object", "properties": {"amount": {"title": "Amount", "type": "string", "format": "decimal", "x-nullable": true}, "code": {"title": "Code", "type": "string", "enum": ["1", "2", "3", "4", "7", "8"]}}}, "DocumentInstallment": {"description": "Información de pago a cuotas de la factura", "required": ["expiration_date", "value"], "type": "object", "properties": {"expiration_date": {"title": "Expiration date", "type": "string", "format": "date"}, "value": {"title": "Value", "type": "string", "format": "decimal"}, "info": {"title": "Info", "type": "string", "maxLength": 1000}}}, "DocumentDiscount": {"description": "Descuentos aplicados a la factura. Máximo 5 items", "required": ["amount"], "type": "object", "properties": {"amount": {"title": "Amount", "type": "string", "format": "decimal"}, "description": {"title": "Description", "type": "string", "default": "Descuento", "maxLength": 500, "minLength": 1}}}, "DocumentOrderDetail": {"description": "Detalle de la orden de compra. Información adicional para el receptor del documento", "required": ["number"], "type": "object", "properties": {"number": {"title": "Number", "description": "Número del pedido de compra", "type": "string", "maxLength": 12, "minLength": 1}, "info": {"title": "Info", "description": "Información de interés del emisor con respecto al pedido comercial global", "type": "string", "maxLength": 4000, "x-nullable": true}, "acceptance_numbers": {"description": "Números de aceptación", "type": "array", "items": {"type": "string", "maxLength": 2, "minLength": 1}, "x-nullable": true}, "receptor_code": {"title": "Receptor code", "description": "Código de cliente/receptor", "type": "string", "maxLength": 50, "x-nullable": true}, "system_code": {"title": "System code", "description": "Código del sistema emisor", "type": "string", "maxLength": 50, "x-nullable": true}}, "x-nullable": true}, "DocumentBody": {"description": "Cuerpo del documento", "required": ["fd_number", "receptor", "items", "payments"], "type": "object", "properties": {"fd_number": {"title": "Número de documento fiscal", "description": "Número del documento fiscal en la serie correspondiente, de 0000000001 a 9999999999, no siendo permitido el reinicio de la numeración. Enviar cero para usar secuencia interna", "type": "integer", "maximum": 9999999999, "minimum": 0}, "type": {"title": "Tipo de documento", "type": "string", "enum": ["FAC", "NTC", "NTD", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10"], "default": "FAC"}, "sale_type": {"title": "Tipo de transacción de venta", "description": "Tipo de venta para el vendedor, si no es venta no informar este campo. \nValores posibles: \n1=Giro de negocio, 2=Activo fijo, 3=Bienes raíces, 4=Prestación de servicios", "type": "string", "enum": ["1", "2", "3", "4"], "default": "1", "x-nullable": true}, "info": {"title": "Info", "type": "string", "maxLength": 5000}, "receptor": {"$ref": "#/definitions/DocumentReceptor"}, "referred": {"$ref": "#/definitions/DocumentReferred"}, "items": {"description": "Grupo de datos que especifica cada ítem del detalle de la transacción", "type": "array", "items": {"$ref": "#/definitions/DocumentItem"}}, "payments": {"description": "Grupo de datos que especifica cada forma de pago de la transacción", "type": "array", "items": {"$ref": "#/definitions/DocumentPayment"}}, "total": {"title": "Total de la factura", "description": "Total de la factura, incluyendo impuestos. Si no se especifica se calcula automaticamente a partir de los datos", "type": "string", "format": "decimal"}, "dest_country": {"title": "Dest country", "description": "País de destino de la FE", "type": "string", "default": "PA", "maxLength": 2, "minLength": 2, "x-nullable": true}, "export_info": {"$ref": "#/definitions/ExportGroup"}, "withholding": {"$ref": "#/definitions/Withholding"}, "payment_term": {"title": "Plazo de pago", "description": "Valores posibles:\n 1=Contado, 2=Crédito/Plazo, 3=Mixto", "type": "integer", "enum": [1, 2, 3], "default": 1}, "installments": {"description": "Información de pago a cuotas de la factura", "type": "array", "items": {"$ref": "#/definitions/DocumentInstallment"}}, "discounts": {"description": "Descuentos aplicados a la factura. Máximo 5 items", "type": "array", "items": {"$ref": "#/definitions/DocumentDiscount"}}, "trim_amounts": {"title": "Trim amounts", "description": "Truncar ceros a la derecha en los montos. Ayuda cuando se usan menos de 6 decimales", "type": "boolean", "default": false}, "issue_type": {"title": "Issue type", "type": "string", "enum": ["01", "02", "03", "04"], "default": "01"}, "order_info": {"$ref": "#/definitions/DocumentOrderDetail"}}}, "Document": {"required": ["header", "document"], "type": "object", "properties": {"header": {"$ref": "#/definitions/DocumentHeader"}, "document": {"$ref": "#/definitions/DocumentBody"}, "document_uuid": {"title": "UUID del documento", "type": "string", "format": "uuid", "readOnly": true}}}, "DocumentResponseMessage": {"required": ["code", "message"], "type": "object", "properties": {"code": {"title": "Código de error", "description": "Según ficha tecnica de la DGI", "type": "string"}, "message": {"title": "Mensaje de error", "description": "Según ficha tecnica de la DGI", "type": "string"}, "field_name": {"title": "Nombre del campo", "description": "Campo con el error. No determinable para todos los códigos de error.", "type": "string"}, "path": {"title": "Ruta del campo", "description": "Ruta del campo con el error. No determinable para todos los códigos de error.", "type": "string"}, "type": {"title": "Tipo de error", "description": "Valores posibles:\n R=Rechazo, N=Notificación", "type": "string", "enum": ["R", "N"]}}}, "OriginalDocument": {"type": "object", "properties": {"cufe": {"title": "CUFE", "type": "string"}, "process_date": {"title": "Fecha de procesamiento", "description": "Sólo para documentos autorizados.", "type": "string"}, "document_uuid": {"title": "UUID del documento", "type": "string", "format": "uuid", "x-nullable": true}, "qr_code_data": {"title": "Código QR", "type": "string"}, "pdf_url": {"title": "URL del PDF", "type": "string"}, "customer_ruc": {"title": "RUC del cliente", "type": "string"}, "customer_name": {"title": "Nombre del cliente", "type": "string"}, "total": {"title": "Total", "type": "string", "format": "decimal"}, "payment_methods": {"type": "array", "items": {"$ref": "#/definitions/DocumentPayment"}}, "authorization_number": {"title": "Número de autorización", "type": "string"}}, "x-nullable": true}, "DocumentResult": {"type": "object", "properties": {"service_response": {"title": "Respuesta del servicio", "type": "string"}, "qr_code_data": {"title": "Código QR", "type": "string"}, "cufe": {"title": "CUFE", "type": "string"}, "did": {"title": "DID", "type": "string"}, "qr_image_b64": {"title": "Imagen del código QR en base64", "type": "string"}, "digest_value": {"title": "Digest value", "type": "string"}, "xml": {"title": "XML", "type": "string"}, "messages": {"type": "array", "items": {"$ref": "#/definitions/DocumentResponseMessage"}}, "rejected": {"title": "Rechazado", "type": "boolean"}, "pdf_url": {"title": "URL del PDF", "type": "string"}, "branch": {"title": "Sucursal", "description": "Código de la sucursal.", "type": "string"}, "pos": {"title": "POS", "description": "Código del POS.", "type": "string"}, "document_type": {"title": "Tipo de documento", "description": "Tipo de documento.", "type": "string"}, "document_number": {"title": "Número de documento", "description": "Número de documento.", "type": "string"}, "authorization_number": {"title": "Número de autorización", "description": "Sólo para documentos autorizados.", "type": "string"}, "process_date": {"title": "Fecha de procesamiento", "description": "Sólo para documentos autorizados.", "type": "string"}, "document_uuid": {"title": "UUID del documento", "type": "string", "format": "uuid", "x-nullable": true}, "original": {"$ref": "#/definitions/OriginalDocument"}, "duplicated": {"title": "Duplicado", "type": "boolean"}}}, "ErrorResponseMessage": {"required": ["message"], "type": "object", "properties": {"message": {"title": "Message", "description": "Descripción del error de validación local", "type": "string", "minLength": 1}, "type": {"title": "Type", "description": "Tipo de mensaje (p.ej. 'R')", "type": "string"}, "code": {"title": "Code", "description": "Código lógico (p.ej. '400')", "type": "string"}}}, "ErrorResponse": {"required": ["messages"], "type": "object", "properties": {"messages": {"type": "array", "items": {"$ref": "#/definitions/ErrorResponseMessage"}}, "rejected": {"title": "Rejected", "description": "True si la solicitud fue rechazada.", "type": "boolean", "default": true}, "duplicated": {"title": "Duplicated", "description": "True si es caso de duplicado (aplica más a 409/duplicados que a 400).", "type": "boolean"}}}, "DocumentStatus": {"required": ["id"], "type": "object", "properties": {"status": {"title": "Status", "type": "integer", "enum": [0, 1, 3, 10, -100, 20, 50], "x-nullable": true}, "status_display": {"title": "Status display", "type": "string", "readOnly": true, "minLength": 1}, "created_at": {"title": "Fecha de recepción", "type": "string", "format": "date-time", "x-nullable": true}, "updated_at": {"title": "Updated at", "type": "string", "format": "date-time", "x-nullable": true}, "xml_data": {"title": "Xml data", "type": "string", "readOnly": true}, "id": {"title": "Id", "type": "string", "format": "uuid"}, "cufe": {"title": "Cufe", "type": "string", "maxLength": 66, "x-nullable": true}}}}, "tags": [{"name": "Emisión de documentos", "description": "APIs para emitir documentos de facturación electrónica de distintos tipos. Las APIs visibles pueden depender de los permisos que tiene el usuario."}]}