Documentos

Objeto Documento

numberstringrequired

Número correlativo del documento en formato AA##-########. Por ejemplo, para Facturas podría ser F001-00004625 o FF23-429062

datestringrequired

Fecha del documento en formato ISO 8601. Por ejemplo 2024-12-25T11:22:33-05:00

external_idstringoptional

ID que puede usarse como referencia para temas de integración

customerobjectrequired

Cliente al que va dirigido el documento

companyobjectrequired

Compañía que emite el documento

currencystringrequired

Tipo de moneda del documento en formato ISO 4217 Alpha Version 2001. Por ejemplo, para Perú sería 'PEN'

payment_methodstringrequired

Método de pago, puede ser 'cash' para contado o 'credit' para ventas a crédito

tax_totalnumberrequired

Monto del impuesto total correspondiente a la sumatoria de impuestos de los ítems no gratuitos

sale_valuenumberrequired

Valor total de la venta correspondiente a la sumatoria de los montos de valor de venta de los ítems no gratuitos

subtotalnumberrequired

Subtotal de la transacción

totalnumberrequired

Precio total de la transacción, incluye monto por concepto de recargo al consumo y otros conceptos adicionales

taxed_amountnumberoptional

Monto correspondiente a la sumatoria de los valores de venta de los ítems gravados no gratuitos

exonerated_amountnumberoptional

Monto correspondiente a la sumatoria de los valores de venta de los ítems exonerados no gratuitos

unaffected_amountnumberoptional

Monto correspondiente a la sumatoria de los valores de venta de los ítems inafectos no gratuitos

free_amountnumberoptional

Monto correspondiente a la sumatoria de los valores de venta de los ítems gratuitos

tax_amountsarrayrequired

Listado de todos los tipos de impuestos obtenidos de los ítems y sus respectivas sumatorias de montos por tipo

legendsarrayoptional

Lista de leyendas

observationstringoptional

Observaciones adicionales del documento

metadataobjectoptional

Lista de información adicional, para temas de elaboración del PDF

itemsarrayrequired

Lista de ítems

chargesarrayoptional

Recargo al consumo u otros conceptos adicionales

document_pdfstringoptional

URL del archivo PDF, en caso desee enviar su propio PDF al cliente de la transacción

credit_installmentsarrayoptional

Cuotas de pago de una transacción a crédito

document_related_typestringoptional

Tipo del documento relacionado, solo aplicable para Notas

document_related_numberstringoptional

Número correlativo del documento relacionado, solo aplicable para Notas

document_related_datestringoptional

Fecha del documento relacionado, en formato YYYY-MM-DD, solo aplicable para Notas

reason_codestringoptional

Código del tipo de anulación según el Catálogo Nº 09 de Sunat, solo aplicable para Notas

reasonstringoptional

Razón de anulación, solo aplicable para Notas

discountsarrayoptional

Descuentos aplicados a nivel de comprobante.

prepaymentsarrayoptional

Anticipos relacionados con el comprobante.

detractionobjectoptional

Datos de detracción cuando la operación está sujeta al SPOT.

retentionobjectoptional

Retención aplicada al comprobante.

perceptionobjectoptional

Percepción aplicada al comprobante.

La API de Facturación permite obtener información correspondiente sobre los documentos que una compañía genera.

Identificadores y archivos

Cada documento creado por la API recibe un id interno con prefijo doc_. Ese identificador se usa para consultar el detalle, generar o recuperar el PDF, obtener documentos relacionados y enviar el comprobante por correo.

Cuando el procesamiento termina correctamente, la respuesta puede incluir:

Campo	Descripción
`document_pdf`	URL del PDF generado.
`document_file`	URL del XML del comprobante.
`document_cdr`	URL del CDR cuando aplica.
`qr_code`	Información o recurso de QR cuando está disponible.
`failure_code`	Código de error si el documento fue rechazado o falló.
`failure_message`	Mensaje de error asociado.

Para búsquedas paginadas usa limit y next_token. El next_token se devuelve dentro de meta cuando existe una página siguiente.

Lista de documentos por compañía

GET /api/document/company/{companyId}
Host: invoice.test.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

Path Params

Parámetro en la URL para el listado de Documentos por compañía.

Atributos

companyIdstringrequired

ID de la compañía sobre la cual se desea obtener los documentos electrónicos, debe ir al final del URL como un path param.

Query Params

Parámetros query para el listado de Documentos por compañía.

Atributos

limitnumberrequired

Límite de registros por consulta.

next_tokenstringoptional

Token requerido para acceder a la siguiente página de registros. Este es enviado tras la primera solicitud si es que hubiera más documentos en la siguiente página, considerando el límite previamente establecido.

Ejemplo de solicitud

GET https://invoice.test.tandia.io/api/document/company/com_61a43c55fbe873?limit=10&next_token=abcd12345

Respuesta

Al realizar la solicitud GET, la API responderá con un estado 200 si la solicitud fue exitosa y devolverá la respuesta en formato JSON. A continuación, la estructura de la respuesta.

{
    "data": [
        {
            "date": "2024-01-14T22:36:00-05:00",
            "business_name": "Tandia Test 0 S.A.C.",
            "failure_code": "",
            "company_id": "com_61a43c55fbe873",
            "failure_message": "",
            "type": "invoice",
            "tax_id": "01234567891",
            "number": "FF10-00000040",
            "total": 236,
            "id": "doc_57b22222222222",
            "document_pdf": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_pdf/file.pdf",
            "document_file": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_xml/file.xml",
            "status": "succeeded"
        }
    ],
    "meta": {
        "next_token": "token_para_siguientes_solicitudes"
    }
}

Búsqueda por Rango de fechas y Estado del Documento

GET /api/document/search/company/{companyId}
Host: invoice.test.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

Path Params

Parámetro en la URL para el filtro de Documentos por fecha y estado.

Atributos

companyIdstringrequired

ID de la compañía sobre la cual se desea obtener los documentos electrónicos, debe ir al final del URL como un path param.

Query Params

Parámetros query para el filtro de Documentos por fecha y estado.

Atributos

limitnumberrequired

Límite de registros por consulta.

start_datestringoptional

La fecha de inicio del rango de tiempo para el filtro. Su formato: YYYY-MM-DD (por ejemplo, "2024-02-20").

end_datestringoptional

La fecha de inicio del rango de tiempo para el filtro. Su formato: YYYY-MM-DD (por ejemplo, "2024-03-20").

statusstringoptional

Estado del documento (por ejemplo "succeeded" o "failed").

next_tokenstringoptional

Ejemplo de solicitud

GET https://invoice.test.tandia.io/api/document/search/company/com_61a43c55fbe873?limit=10&start_date=2024-01-01&end_date=2024-01-15&status=succeeded&next_token=abcd12345

Respuesta

Al realizar la solicitud GET, la API responderá con un estado 200 si la solicitud fue exitosa y devolverá la respuesta en formato JSON. A continuación, la estructura de la respuesta.

{
    "data": [
        {
            "date": "2024-01-01T22:36:00-05:00",
            "business_name": "Tandia Test 0 S.A.C.",
            "failure_code": "",
            "company_id": "com_61a43c55fbe873",
            "failure_message": "",
            "type": "invoice",
            "tax_id": "01234567891",
            "number": "FF10-00000040",
            "total": 236,
            "id": "doc_57b44444444444",
            "document_pdf": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_pdf/file.pdf",
            "document_file": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_xml/file.xml",
            "status": "succeeded"
        }
    ],
    "meta": {
        "next_token": "token_para_siguientes_solicitudes"
    }
}

Búsqueda por Tipo de Documento y Número

GET /api/document/search/company/{companyId}/{type}/{number}
Host: invoice.test.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

Path Params

Parámetro en la URL para el filtro de Documentos por tipo y número.

Atributos

companyIdstringrequired

ID de la compañía sobre la cual se desea obtener sus documentos electrónicos, debe ir al final del URL como un path param.

typestringoptional

Tipo del documento que se requiere (por ejemplo "invoice" o "receipt").

numberstringrequired

Número del documento.

Ejemplo de solicitud

GET https://invoice.test.tandia.io/api/document/search/company/com_61a43c55fbe873/invoice/F000-0001

Respuesta

Al realizar la solicitud GET, la API responderá con un estado 200 si la solicitud fue exitosa y devolverá la respuesta en formato JSON. A continuación, la estructura de la respuesta.

{
    "data": [
        {
            "date": "2024-01-14T22:36:00-05:00",
            "business_name": "Tandia Test 0 S.A.C.",
            "failure_code": "",
            "company_id": "com_61a43c55fbe873",
            "failure_message": "",
            "type": "invoice",
            "tax_id": "1122334455",
            "number": "F000-0001",
            "total": 236,
            "id": "doc_57b44444444422",
            "document_pdf": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_pdf/file.pdf",
            "document_file": "http://invoice.tandia.io:4566/enlace_hacia_el_doc_xml/file.xml",
            "status": "succeeded"
        }
    ],
    "meta": {
        "next_token": null
    }
}

Búsqueda por ID del Documento

GET /api/document/{documentId}
Host: invoice.test.tandia.io
Content-Type: application/json
Authorization: Bearer token-de-api

Path Params

Parámetro en la URL para la solicitud de un Documento por su ID.

Atributos

documentIdstringrequired

ID del documento sobre el cual se desea obtener información, debe ir al final del URL como un path param.

Ejemplo de solicitud

GET https://invoice.test.tandia.io/api/document/doc_e477e6c616834f77ab1443ed7d30ed9f

Respuesta

Al realizar la solicitud GET, la API responderá con un estado 200 si la solicitud fue exitosa y devolverá la respuesta en formato JSON. A continuación, la estructura de la respuesta.

{
  "type": "invoice",
  "id": "doc_e477e6c616834f77ab1443ed7d30ed9f",
  "external_id": "12345566",
  "number": "FF10-00000029",
  "date": "2023-11-01T18:46:00-05:00",
  "observation": null,
  "company": {
    "tax_id": "12345678910",
    "business_name": "Tu Empresa S.A.C.",
    "trade_name": "Tu Empresa S.A.C.",
    "email": "email@dominio.com",
    "phone": "+51 986187825",
    "country": "PE",
    "address": {
      "postal_zone": "150122",
      "country": "PE",
      "country_subentity": "LIMA",
      "city": "LIMA",
      "district": "MIRAFLORES",
      "city_subdivision": "MIRAFLORES",
      "address": "CALLE MARTIR JOSE OLAYA NRO. 129 INT. 1302 COM. SAN MIGUEL DE MIRAFLORES",
      "type_code": null
    },
    "logo": "url-logo"
  },
  "customer": {
    "document_type": "6",
    "document_number": "20740021552",
    "registration_name": "Jane Doe SAC",
    "family_name": null,
    "email": "jdoe@business.com",
    "document_extra": null
  },
  "metadata": {
    "seller": "David Doe",
    "customer_address": "Av. Primavera 123",
    "payments": [
      {
        "tag_amount": "EFECTIVO",
        "amount": "236.00"
      }
    ]
  },
  "status": "succeeded",
  "failure_code": null,
  "failure_message": null,
  "document_pdf": "url-pdf",
  "document_file": "url-xml",
  "document_cdr": "url-cdr",
  "payment_method": "cash",
  "currency": "PEN",
  "order_reference": null,
  "sale_value": 200.00,
  "total": 236.00,
  "tax_total": 36.00,
  "taxed_amount": 200.00,
  "unaffected_amount": null,
  "exonerated_amount": null,
  "free_amount": null,
  "tax_amounts": [
    {
      "code": "IGV",
      "amount": 36.00,
      "percentage": null,
      "affectation_type": null
    }
  ],
  "items": [
    {
      "taxes": [
        {
          "code": "IGV",
          "amount": 36.00,
          "percentage": 18,
          "affectation_type": "10"
        }
      ],
      "unit": "NIU",
      "quantity": 2.00,
      "code": "P001",
      "description": "PRODUCTO 1",
      "unit_price": 118.00,
      "unit_value": 100.00,
      "sale_value": 200.00,
      "subtotal": 200.00,
      "tax_total": 36.00,
      "discounts": null,
      "total": 236.00,
      "free": false
    }
  ]
}